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