91824d70440fe705007f17736b7cfc483fcbff9e
[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  * \since 1.6.1
102  */
103 void ast_console_toggle_loglevel(int fd, int level, int state);
104
105 /* Note: The AST_LOG_* macros below are the same as
106  * the LOG_* macros and are intended to eventually replace
107  * the LOG_* macros to avoid name collisions as has been
108  * seen in app_voicemail. However, please do NOT remove
109  * the LOG_* macros from the source since these may be still
110  * needed for third-party modules
111  */
112
113 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
114
115 #ifdef LOG_DEBUG
116 #undef LOG_DEBUG
117 #endif
118 #define __LOG_DEBUG    0
119 #define LOG_DEBUG      __LOG_DEBUG, _A_
120
121 #ifdef AST_LOG_DEBUG
122 #undef AST_LOG_DEBUG
123 #endif
124 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
125
126 #ifdef LOG_NOTICE
127 #undef LOG_NOTICE
128 #endif
129 #define __LOG_NOTICE   2
130 #define LOG_NOTICE     __LOG_NOTICE, _A_
131
132 #ifdef AST_LOG_NOTICE
133 #undef AST_LOG_NOTICE
134 #endif
135 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
136
137 #ifdef LOG_WARNING
138 #undef LOG_WARNING
139 #endif
140 #define __LOG_WARNING  3
141 #define LOG_WARNING    __LOG_WARNING, _A_
142
143 #ifdef AST_LOG_WARNING
144 #undef AST_LOG_WARNING
145 #endif
146 #define AST_LOG_WARNING    __LOG_WARNING, _A_
147
148 #ifdef LOG_ERROR
149 #undef LOG_ERROR
150 #endif
151 #define __LOG_ERROR    4
152 #define LOG_ERROR      __LOG_ERROR, _A_
153
154 #ifdef AST_LOG_ERROR
155 #undef AST_LOG_ERROR
156 #endif
157 #define AST_LOG_ERROR      __LOG_ERROR, _A_
158
159 #ifdef LOG_VERBOSE
160 #undef LOG_VERBOSE
161 #endif
162 #define __LOG_VERBOSE  5
163 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
164
165 #ifdef AST_LOG_VERBOSE
166 #undef AST_LOG_VERBOSE
167 #endif
168 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
169
170 #ifdef LOG_DTMF
171 #undef LOG_DTMF
172 #endif
173 #define __LOG_DTMF  6
174 #define LOG_DTMF    __LOG_DTMF, _A_
175
176 #ifdef AST_LOG_DTMF
177 #undef AST_LOG_DTMF
178 #endif
179 #define AST_LOG_DTMF    __LOG_DTMF, _A_
180
181 #define NUMLOGLEVELS 6
182
183 /*!
184  * \brief Get the debug level for a module
185  * \param module the name of module
186  * \return the debug level
187  */
188 unsigned int ast_debug_get_by_module(const char *module);
189
190 /*!
191  * \brief Get the verbose level for a module
192  * \param module the name of module
193  * \return the verbose level
194  */
195 unsigned int ast_verbose_get_by_module(const char *module);
196
197 /*!
198  * \brief Register a new logger level
199  * \param name The name of the level to be registered
200  * \retval -1 if an error occurs
201  * \retval non-zero level to be used with ast_log for sending messages to this level
202  * \since 1.8
203  */
204 int ast_logger_register_level(const char *name);
205
206 /*!
207  * \brief Unregister a previously registered logger level
208  * \param name The name of the level to be unregistered
209  * \return nothing
210  * \since 1.8
211  */
212 void ast_logger_unregister_level(const char *name);
213
214 /*!
215  * \brief Send a log message to a dynamically registered log level
216  * \param level The log level to send the message to
217  *
218  * Like ast_log, the log message may include printf-style formats, and
219  * the data for these must be provided as additional parameters after
220  * the log message.
221  *
222  * \return nothing
223  * \since 1.8
224  */
225
226 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
227
228 /*!
229  * \brief Log a DEBUG message
230  * \param level The minimum value of option_debug for this message
231  *        to get logged
232  */
233 #define ast_debug(level, ...) do {       \
234         if (option_debug >= (level) || (ast_opt_dbg_module && ast_debug_get_by_module(AST_MODULE) >= (level)) ) \
235                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
236 } while (0)
237
238 #define VERBOSITY_ATLEAST(level) (option_verbose >= (level) || (ast_opt_verb_module && ast_verbose_get_by_module(AST_MODULE) >= (level)))
239
240 #define ast_verb(level, ...) do { \
241         if (VERBOSITY_ATLEAST((level)) ) { \
242                 if (level >= 4) \
243                         ast_verbose(VERBOSE_PREFIX_4 __VA_ARGS__); \
244                 else if (level == 3) \
245                         ast_verbose(VERBOSE_PREFIX_3 __VA_ARGS__); \
246                 else if (level == 2) \
247                         ast_verbose(VERBOSE_PREFIX_2 __VA_ARGS__); \
248                 else if (level == 1) \
249                         ast_verbose(VERBOSE_PREFIX_1 __VA_ARGS__); \
250                 else \
251                         ast_verbose(__VA_ARGS__); \
252         } \
253 } while (0)
254
255 #ifndef _LOGGER_BACKTRACE_H
256 #define _LOGGER_BACKTRACE_H
257 #ifdef HAVE_BKTR
258 #define AST_MAX_BT_FRAMES 32
259 /* \brief
260  *
261  * A structure to hold backtrace information. This structure provides an easy means to
262  * store backtrace information or pass backtraces to other functions.
263  */
264 struct ast_bt {
265         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
266         void *addresses[AST_MAX_BT_FRAMES];
267         /*! The number of stack frames in the backtrace */
268         int num_frames;
269         /*! Tells if the ast_bt structure was dynamically allocated */
270         unsigned int alloced:1;
271 };
272
273 /* \brief
274  * Allocates memory for an ast_bt and stores addresses and symbols.
275  *
276  * \return Returns NULL on failure, or the allocated ast_bt on success
277  * \since 1.6.1
278  */
279 struct ast_bt *ast_bt_create(void);
280
281 /* \brief
282  * Fill an allocated ast_bt with addresses
283  *
284  * \retval 0 Success
285  * \retval -1 Failure
286  * \since 1.6.1
287  */
288 int ast_bt_get_addresses(struct ast_bt *bt);
289
290 /* \brief
291  *
292  * Free dynamically allocated portions of an ast_bt
293  *
294  * \retval NULL.
295  * \since 1.6.1
296  */
297 void *ast_bt_destroy(struct ast_bt *bt);
298
299 /* \brief Retrieve symbols for a set of backtrace addresses
300  *
301  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
302  * \param num_frames Number of addresses in the addresses list
303  * \retval NULL Unable to allocate memory
304  * \return List of strings
305  * \since 1.6.2.16
306  */
307 char **ast_bt_get_symbols(void **addresses, size_t num_frames);
308
309 #endif /* HAVE_BKTR */
310 #endif /* _LOGGER_BACKTRACE_H */
311
312 #if defined(__cplusplus) || defined(c_plusplus)
313 }
314 #endif
315
316 #endif /* _ASTERISK_LOGGER_H */