include/asterisk/logger.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2005, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*!
  20   \file logger.h
  21   \brief Support for logging to various files, console and syslog
  22         Configuration in file logger.conf
  23 */
  24
  25 #ifndef _ASTERISK_LOGGER_H
  26 #define _ASTERISK_LOGGER_H
  27
  28 #include "asterisk/options.h"   /* need option_debug */
  29
  30 #if defined(__cplusplus) || defined(c_plusplus)
  31 extern "C" {
  32 #endif
  33
  34 #define EVENTLOG "event_log"
  35 #define QUEUELOG        "queue_log"
  36
  37 #define DEBUG_M(a) { \
  38         a; \
  39 }
  40
  41 #define VERBOSE_PREFIX_1 " "
  42 #define VERBOSE_PREFIX_2 "  == "
  43 #define VERBOSE_PREFIX_3 "    -- "
  44 #define VERBOSE_PREFIX_4 "       > "
  45
  46 /*! \brief Used for sending a log message
  47         This is the standard logger function.  Probably the only way you will invoke it would be something like this:
  48         ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
  49         where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
  50         on which log you wish to output to. These are implemented as macros, that
  51         will provide the function with the needed arguments.
  52
  53         \param level    Type of log event
  54         \param file     Will be provided by the AST_LOG_* macro
  55         \param line     Will be provided by the AST_LOG_* macro
  56         \param function Will be provided by the AST_LOG_* macro
  57         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
  58  */
  59
  60 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
  61         __attribute__((format(printf, 5, 6)));
  62
  63 void ast_backtrace(void);
  64
  65 /*! \brief Reload logger without rotating log files */
  66 int logger_reload(void);
  67
  68 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
  69
  70 /*! Send a verbose message (based on verbose level)
  71         \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
  72         ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
  73         This will print the message to the console if the verbose level is set to a level >= 3
  74         Note the abscence of a comma after the VERBOSE_PREFIX_3.  This is important.
  75         VERBOSE_PREFIX_1 through VERBOSE_PREFIX_3 are defined.
  76  */
  77 void __attribute__((format(printf, 4, 5))) __ast_verbose(const char *file, int line, const char *func, const char *fmt, ...);
  78
  79 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__,  __VA_ARGS__)
  80
  81 void __attribute__((format(printf, 4, 0))) __ast_verbose_ap(const char *file, int line, const char *func, const char *fmt, va_list ap);
  82
  83 #define ast_verbose_ap(fmt, ap) __ast_verbose_ap(__FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, ap)
  84
  85 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
  86
  87 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
  88 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
  89
  90 void ast_console_puts(const char *string);
  91
  92 /*!
  93  * \brief log the string to the console, and all attached
  94  * console clients
  95  * \version 1.6.1 added level parameter
  96  */
  97 void ast_console_puts_mutable(const char *string, int level);
  98 void ast_console_toggle_mute(int fd, int silent);
  99
 100 /*!
 101  * \brief enables or disables logging of a specified level to the console
 102  * fd specifies the index of the console receiving the level change
 103  * level specifies the index of the logging level being toggled
 104  * state indicates whether logging will be on or off (0 for off, 1 for on)
 105  */
 106 void ast_console_toggle_loglevel(int fd, int level, int state);
 107
 108 /* Note: The AST_LOG_* macros below are the same as
 109  * the LOG_* macros and are intended to eventually replace
 110  * the LOG_* macros to avoid name collisions as has been
 111  * seen in app_voicemail. However, please do NOT remove
 112  * the LOG_* macros from the source since these may be still
 113  * needed for third-party modules
 114  */
 115
 116 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
 117
 118 #ifdef LOG_DEBUG
 119 #undef LOG_DEBUG
 120 #endif
 121 #define __LOG_DEBUG    0
 122 #define LOG_DEBUG      __LOG_DEBUG, _A_
 123
 124 #ifdef AST_LOG_DEBUG
 125 #undef AST_LOG_DEBUG
 126 #endif
 127 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
 128
 129 #ifdef LOG_NOTICE
 130 #undef LOG_NOTICE
 131 #endif
 132 #define __LOG_NOTICE   2
 133 #define LOG_NOTICE     __LOG_NOTICE, _A_
 134
 135 #ifdef AST_LOG_NOTICE
 136 #undef AST_LOG_NOTICE
 137 #endif
 138 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
 139
 140 #ifdef LOG_WARNING
 141 #undef LOG_WARNING
 142 #endif
 143 #define __LOG_WARNING  3
 144 #define LOG_WARNING    __LOG_WARNING, _A_
 145
 146 #ifdef AST_LOG_WARNING
 147 #undef AST_LOG_WARNING
 148 #endif
 149 #define AST_LOG_WARNING    __LOG_WARNING, _A_
 150
 151 #ifdef LOG_ERROR
 152 #undef LOG_ERROR
 153 #endif
 154 #define __LOG_ERROR    4
 155 #define LOG_ERROR      __LOG_ERROR, _A_
 156
 157 #ifdef AST_LOG_ERROR
 158 #undef AST_LOG_ERROR
 159 #endif
 160 #define AST_LOG_ERROR      __LOG_ERROR, _A_
 161
 162 #ifdef LOG_VERBOSE
 163 #undef LOG_VERBOSE
 164 #endif
 165 #define __LOG_VERBOSE  5
 166 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
 167
 168 #ifdef AST_LOG_VERBOSE
 169 #undef AST_LOG_VERBOSE
 170 #endif
 171 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
 172
 173 #ifdef LOG_DTMF
 174 #undef LOG_DTMF
 175 #endif
 176 #define __LOG_DTMF  6
 177 #define LOG_DTMF    __LOG_DTMF, _A_
 178
 179 #ifdef AST_LOG_DTMF
 180 #undef AST_LOG_DTMF
 181 #endif
 182 #define AST_LOG_DTMF    __LOG_DTMF, _A_
 183
 184 #define NUMLOGLEVELS 7
 185
 186 /*!
 187  * \brief Get the debug level for a module
 188  * \param module the name of module
 189  * \return the debug level
 190  */
 191 unsigned int ast_debug_get_by_module(const char *module);
 192
 193 /*!
 194  * \brief Get the verbose level for a module
 195  * \param module the name of module
 196  * \return the verbose level
 197  */
 198 unsigned int ast_verbose_get_by_module(const char *module);
 199
 200 /*!
 201  * \brief Register a new logger level
 202  * \param name The name of the level to be registered
 203  * \retval -1 if an error occurs
 204  * \retval non-zero level to be used with ast_log for sending messages to this level
 205  * \since 1.8
 206  */
 207 int ast_logger_register_level(const char *name);
 208
 209 /*!
 210  * \brief Unregister a previously registered logger level
 211  * \param name The name of the level to be unregistered
 212  * \return nothing
 213  * \since 1.8
 214  */
 215 void ast_logger_unregister_level(const char *name);
 216
 217 /*!
 218  * \brief Send a log message to a dynamically registered log level
 219  * \param level The log level to send the message to
 220  *
 221  * Like ast_log, the log message may include printf-style formats, and
 222  * the data for these must be provided as additional parameters after
 223  * the log message.
 224  *
 225  * \return nothing
 226  * \since 1.8
 227  */
 228
 229 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
 230
 231 /*!
 232  * \brief Log a DEBUG message
 233  * \param level The minimum value of option_debug for this message
 234  *        to get logged
 235  */
 236 #define ast_debug(level, ...) do {       \
 237         if (option_debug >= (level) || (ast_opt_dbg_module && ast_debug_get_by_module(AST_MODULE) >= (level)) ) \
 238                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
 239 } while (0)
 240
 241 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_module && ast_verbose_get_by_module(AST_MODULE) >= (level)))
 242
 243 #define ast_verb(level, ...) do { \
 244         if (VERBOSITY_ATLEAST((level)) ) { \
 245                 if (level >= 4) \
 246                         ast_verbose(VERBOSE_PREFIX_4 __VA_ARGS__); \
 247                 else if (level == 3) \
 248                         ast_verbose(VERBOSE_PREFIX_3 __VA_ARGS__); \
 249                 else if (level == 2) \
 250                         ast_verbose(VERBOSE_PREFIX_2 __VA_ARGS__); \
 251                 else if (level == 1) \
 252                         ast_verbose(VERBOSE_PREFIX_1 __VA_ARGS__); \
 253                 else \
 254                         ast_verbose(__VA_ARGS__); \
 255         } \
 256 } while (0)
 257
 258 #ifndef _LOGGER_BACKTRACE_H
 259 #define _LOGGER_BACKTRACE_H
 260 #ifdef HAVE_BKTR
 261 #define AST_MAX_BT_FRAMES 32
 262 /* \brief
 263  *
 264  * A structure to hold backtrace information. This structure provides an easy means to
 265  * store backtrace information or pass backtraces to other functions.
 266  */
 267 struct ast_bt {
 268         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
 269         void *addresses[AST_MAX_BT_FRAMES];
 270         /*! The number of stack frames in the backtrace */
 271         int num_frames;
 272         /*! Tells if the ast_bt structure was dynamically allocated */
 273         unsigned int alloced:1;
 274 };
 275
 276 /* \brief
 277  * Allocates memory for an ast_bt and stores addresses and symbols.
 278  *
 279  * \return Returns NULL on failure, or the allocated ast_bt on success
 280  * \since 1.6.1
 281  */
 282 struct ast_bt *ast_bt_create(void);
 283
 284 /* \brief
 285  * Fill an allocated ast_bt with addresses
 286  *
 287  * \retval 0 Success
 288  * \retval -1 Failure
 289  * \since 1.6.1
 290  */
 291 int ast_bt_get_addresses(struct ast_bt *bt);
 292
 293 /* \brief
 294  *
 295  * Free dynamically allocated portions of an ast_bt
 296  *
 297  * \retval NULL.
 298  * \since 1.6.1
 299  */
 300 void *ast_bt_destroy(struct ast_bt *bt);
 301
 302 /* \brief Retrieve symbols for a set of backtrace addresses
 303  *
 304  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
 305  * \param num_frames Number of addresses in the addresses list
 306  * \retval NULL Unable to allocate memory
 307  * \return List of strings
 308  * \since 1.6.2.16
 309  */
 310 char **ast_bt_get_symbols(void **addresses, size_t num_frames);
 311
 312 #endif /* HAVE_BKTR */
 313 #endif /* _LOGGER_BACKTRACE_H */
 314
 315 #if defined(__cplusplus) || defined(c_plusplus)
 316 }
 317 #endif
 318
 319 #endif /* _ASTERISK_LOGGER_H */