a2a28809f203852c6b020831f112c12ba788f0db
[asterisk/asterisk.git] / 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 */