2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 1999 - 2005, Digium, Inc.
6 * Mark Spencer <markster@digium.com>
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.
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.
21 \brief Support for logging to various files, console and syslog
22 Configuration in file logger.conf
25 #ifndef _ASTERISK_LOGGER_H
26 #define _ASTERISK_LOGGER_H
28 #include "asterisk/options.h" /* need option_debug */
30 #if defined(__cplusplus) || defined(c_plusplus)
34 #define EVENTLOG "event_log"
35 #define QUEUELOG "queue_log"
37 #define DEBUG_M(a) { \
41 #define VERBOSE_PREFIX_1 " "
42 #define VERBOSE_PREFIX_2 " == "
43 #define VERBOSE_PREFIX_3 " -- "
44 #define VERBOSE_PREFIX_4 " > "
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.
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? :-)
60 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
61 __attribute__((format(printf, 5, 6)));
63 void ast_backtrace(void);
65 /*! \brief Reload logger without rotating log files */
66 int logger_reload(void);
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, ...);
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.
77 void __attribute__((format(printf, 4, 5))) __ast_verbose(const char *file, int line, const char *func, const char *fmt, ...);
79 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
81 void __attribute__((format(printf, 4, 0))) __ast_verbose_ap(const char *file, int line, const char *func, const char *fmt, va_list ap);
83 #define ast_verbose_ap(fmt, ap) __ast_verbose_ap(__FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, ap)
85 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
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;
90 void ast_console_puts(const char *string);
93 * \brief log the string to the console, and all attached
95 * \version 1.6.1 added level parameter
97 void ast_console_puts_mutable(const char *string, int level);
98 void ast_console_toggle_mute(int fd, int silent);
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)
106 void ast_console_toggle_loglevel(int fd, int level, int state);
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
116 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
121 #define __LOG_DEBUG 0
122 #define LOG_DEBUG __LOG_DEBUG, _A_
127 #define AST_LOG_DEBUG __LOG_DEBUG, _A_
132 #define __LOG_NOTICE 2
133 #define LOG_NOTICE __LOG_NOTICE, _A_
135 #ifdef AST_LOG_NOTICE
136 #undef AST_LOG_NOTICE
138 #define AST_LOG_NOTICE __LOG_NOTICE, _A_
143 #define __LOG_WARNING 3
144 #define LOG_WARNING __LOG_WARNING, _A_
146 #ifdef AST_LOG_WARNING
147 #undef AST_LOG_WARNING
149 #define AST_LOG_WARNING __LOG_WARNING, _A_
154 #define __LOG_ERROR 4
155 #define LOG_ERROR __LOG_ERROR, _A_
160 #define AST_LOG_ERROR __LOG_ERROR, _A_
165 #define __LOG_VERBOSE 5
166 #define LOG_VERBOSE __LOG_VERBOSE, _A_
168 #ifdef AST_LOG_VERBOSE
169 #undef AST_LOG_VERBOSE
171 #define LOG_VERBOSE __LOG_VERBOSE, _A_
177 #define LOG_DTMF __LOG_DTMF, _A_
182 #define AST_LOG_DTMF __LOG_DTMF, _A_
184 #define NUMLOGLEVELS 7
187 * \brief Get the debug level for a module
188 * \param module the name of module
189 * \return the debug level
191 unsigned int ast_debug_get_by_module(const char *module);
194 * \brief Get the verbose level for a module
195 * \param module the name of module
196 * \return the verbose level
198 unsigned int ast_verbose_get_by_module(const char *module);
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
207 int ast_logger_register_level(const char *name);
210 * \brief Unregister a previously registered logger level
211 * \param name The name of the level to be unregistered
215 void ast_logger_unregister_level(const char *name);
218 * \brief Send a log message to a dynamically registered log level
219 * \param level The log level to send the message to
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
229 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
232 * \brief Log a DEBUG message
233 * \param level The minimum value of option_debug for this message
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__); \
241 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_module && ast_verbose_get_by_module(AST_MODULE) >= (level)))
243 #define ast_verb(level, ...) do { \
244 if (VERBOSITY_ATLEAST((level)) ) { \
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__); \
254 ast_verbose(__VA_ARGS__); \
258 #ifndef _LOGGER_BACKTRACE_H
259 #define _LOGGER_BACKTRACE_H
261 #define AST_MAX_BT_FRAMES 32
264 * A structure to hold backtrace information. This structure provides an easy means to
265 * store backtrace information or pass backtraces to other functions.
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 */
272 /*! Tells if the ast_bt structure was dynamically allocated */
273 unsigned int alloced:1;
277 * Allocates memory for an ast_bt and stores addresses and symbols.
279 * \return Returns NULL on failure, or the allocated ast_bt on success
282 struct ast_bt *ast_bt_create(void);
285 * Fill an allocated ast_bt with addresses
291 int ast_bt_get_addresses(struct ast_bt *bt);
295 * Free dynamically allocated portions of an ast_bt
300 void *ast_bt_destroy(struct ast_bt *bt);
302 /* \brief Retrieve symbols for a set of backtrace addresses
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
310 char **ast_bt_get_symbols(void **addresses, size_t num_frames);
312 #endif /* HAVE_BKTR */
313 #endif /* _LOGGER_BACKTRACE_H */
315 #if defined(__cplusplus) || defined(c_plusplus)
319 #endif /* _ASTERISK_LOGGER_H */