logger: Support JSON logging with Verbose messages
[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 #define AST_CALLID_BUFFER_LENGTH 13
47
48 enum ast_logger_results {
49         AST_LOGGER_SUCCESS = 0, /*!< Log channel was created or deleted successfully*/
50         AST_LOGGER_FAILURE = 1, /*!< Log channel already exists for create or doesn't exist for deletion of log channel */
51         AST_LOGGER_DECLINE = -1, /*!< Log channel request was not accepted */
52         AST_LOGGER_ALLOC_ERROR = -2 /*!< filename allocation error */
53 };
54
55 /*! \brief Used for sending a log message
56         This is the standard logger function.  Probably the only way you will invoke it would be something like this:
57         ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
58         where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
59         on which log you wish to output to. These are implemented as macros, that
60         will provide the function with the needed arguments.
61
62         \param level    Type of log event
63         \param file     Will be provided by the AST_LOG_* macro
64         \param line     Will be provided by the AST_LOG_* macro
65         \param function Will be provided by the AST_LOG_* macro
66         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
67  */
68
69 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
70         __attribute__((format(printf, 5, 6)));
71
72 /*!
73  * \brief Used for sending a log message with protection against recursion.
74  *
75  * \note This function should be used by all error messages that might be directly
76  * or indirectly caused by logging.
77  *
78  * \see ast_log for documentation on the parameters.
79  */
80 void ast_log_safe(int level, const char *file, int line, const char *function, const char *fmt, ...)
81         __attribute__((format(printf, 5, 6)));
82
83 /* XXX needs documentation */
84 typedef unsigned int ast_callid;
85
86 /*! \brief Used for sending a log message with a known call_id
87         This is a modified logger function which is functionally identical to the above logger function,
88         it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
89         join the log message with a call_id.
90
91         \param level    Type of log event
92         \param file     Will be provided by the AST_LOG_* macro
93         \param line     Will be provided by the AST_LOG_* macro
94         \param function Will be provided by the AST_LOG_* macro
95         \param callid   This is the ast_callid that is associated with the log message. May be NULL.
96         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
97 */
98 void ast_log_callid(int level, const char *file, int line, const char *function, ast_callid callid, const char *fmt, ...)
99         __attribute__((format(printf, 6, 7)));
100
101 /*!
102  * \brief Retrieve the existing log channels
103  * \param logentry A callback to an updater function
104  * \param data Data passed into the callback for manipulation
105  *
106  * For each of the logging channels, logentry will be executed with the
107  * channel file name, log type, status of the log, and configuration levels.
108  *
109  * \retval 0 on success
110  * \retval 1 on failure
111  * \retval -2 on allocation error
112  */
113 int ast_logger_get_channels(int (*logentry)(const char *channel, const char *type,
114         const char *status, const char *configuration, void *data), void *data);
115
116 /*!
117  * \brief Create a log channel
118  *
119  * \param log_channel Log channel to create
120  * \param components Logging config levels to add to the log channel
121  */
122 int ast_logger_create_channel(const char *log_channel, const char *components);
123
124 /*!
125  * \brief Delete the specified log channel
126  *
127  * \param log_channel The log channel to delete
128  */
129 int ast_logger_remove_channel(const char *log_channel);
130
131 /*!
132  * \brief Log a backtrace of the current thread's execution stack to the Asterisk log
133  */
134 void ast_log_backtrace(void);
135
136 /*! \brief Reload logger without rotating log files */
137 int logger_reload(void);
138
139 /*! \brief Reload logger while rotating log files */
140 int ast_logger_rotate(void);
141
142 /*!
143  * \brief Rotate the specified log channel.
144  *
145  * \param log_channel The log channel to rotate
146  */
147 int ast_logger_rotate_channel(const char *log_channel);
148
149 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
150
151 /*!
152  * \brief Send a verbose message (based on verbose level)
153  *
154  * \details This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
155  *
156  * ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
157  *
158  * This will print the message to the console if the verbose level is set to a level >= 3
159  *
160  * Note the absence of a comma after the VERBOSE_PREFIX_3.  This is important.
161  * VERBOSE_PREFIX_1 through VERBOSE_PREFIX_4 are defined.
162  *
163  * \version 11 added level parameter
164  */
165 void __attribute__((format(printf, 5, 6))) __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt, ...);
166
167 /*!
168  * \brief Send a verbose message (based on verbose level) with deliberately specified callid
169  *
170  * \details just like __ast_verbose, only __ast_verbose_callid allows you to specify which callid is being used
171  * for the log without needing to bind it to a thread. NULL is a valid argument for this function and will
172  * allow you to specify that a log will never display a call id even when there is a call id bound to the
173  * thread.
174  */
175 void __attribute__((format(printf, 6, 7))) __ast_verbose_callid(const char *file, int line, const char *func, int level, ast_callid callid, const char *fmt, ...);
176
177 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, __VA_ARGS__)
178 #define ast_verbose_callid(callid, ...) __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, callid, __VA_ARGS__)
179
180 void __attribute__((format(printf, 6, 0))) __ast_verbose_ap(const char *file, int line, const char *func, int level, ast_callid callid, const char *fmt, va_list ap);
181
182 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
183
184 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
185 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
186
187 /*
188  * These gymnastics are due to platforms which designate char as unsigned by
189  * default.  Level is the negative character -- offset by 1, because \0 is
190  * the string terminator.
191  */
192 #define VERBOSE_MAGIC2LEVEL(x) (((char) -*(signed char *) (x)) - 1)
193 #define VERBOSE_HASMAGIC(x)     (*(signed char *) (x) < 0)
194
195 void ast_console_puts(const char *string);
196
197 /*!
198  * \brief log the string to the console, and all attached console clients
199  *
200  * \param string The message to write to the console
201  * \param level The log level of the message
202  *
203  * \version 1.6.1 added level parameter
204  */
205 void ast_console_puts_mutable(const char *string, int level);
206
207 /*!
208  * \brief log the string to the console, and all attached console clients
209  * \since 14.0.0
210  *
211  * \param message The message to write to the console
212  * \param sublevel If the log level supports it, the sub-level of the message
213  * \param level The log level of the message
214  */
215 void ast_console_puts_mutable_full(const char *message, int level, int sublevel);
216
217 void ast_console_toggle_mute(int fd, int silent);
218
219 /*!
220  * \brief enables or disables logging of a specified level to the console
221  * fd specifies the index of the console receiving the level change
222  * level specifies the index of the logging level being toggled
223  * state indicates whether logging will be on or off (0 for off, 1 for on)
224  */
225 void ast_console_toggle_loglevel(int fd, int level, int state);
226
227 /* Note: The AST_LOG_* macros below are the same as
228  * the LOG_* macros and are intended to eventually replace
229  * the LOG_* macros to avoid name collisions with the syslog(3)
230  * log levels. However, please do NOT remove
231  * the LOG_* macros from the source since these may be still
232  * needed for third-party modules
233  */
234
235 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
236
237 #ifdef LOG_DEBUG
238 #undef LOG_DEBUG
239 #endif
240 #define __LOG_DEBUG    0
241 #define LOG_DEBUG      __LOG_DEBUG, _A_
242
243 #ifdef AST_LOG_DEBUG
244 #undef AST_LOG_DEBUG
245 #endif
246 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
247
248 #ifdef LOG_NOTICE
249 #undef LOG_NOTICE
250 #endif
251 #define __LOG_NOTICE   2
252 #define LOG_NOTICE     __LOG_NOTICE, _A_
253
254 #ifdef AST_LOG_NOTICE
255 #undef AST_LOG_NOTICE
256 #endif
257 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
258
259 #ifdef LOG_WARNING
260 #undef LOG_WARNING
261 #endif
262 #define __LOG_WARNING  3
263 #define LOG_WARNING    __LOG_WARNING, _A_
264
265 #ifdef AST_LOG_WARNING
266 #undef AST_LOG_WARNING
267 #endif
268 #define AST_LOG_WARNING    __LOG_WARNING, _A_
269
270 #ifdef LOG_ERROR
271 #undef LOG_ERROR
272 #endif
273 #define __LOG_ERROR    4
274 #define LOG_ERROR      __LOG_ERROR, _A_
275
276 #ifdef AST_LOG_ERROR
277 #undef AST_LOG_ERROR
278 #endif
279 #define AST_LOG_ERROR      __LOG_ERROR, _A_
280
281 #ifdef LOG_VERBOSE
282 #undef LOG_VERBOSE
283 #endif
284 #define __LOG_VERBOSE  5
285 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
286
287 #ifdef AST_LOG_VERBOSE
288 #undef AST_LOG_VERBOSE
289 #endif
290 #define AST_LOG_VERBOSE    __LOG_VERBOSE, _A_
291
292 #ifdef LOG_DTMF
293 #undef LOG_DTMF
294 #endif
295 #define __LOG_DTMF  6
296 #define LOG_DTMF    __LOG_DTMF, _A_
297
298 #ifdef AST_LOG_DTMF
299 #undef AST_LOG_DTMF
300 #endif
301 #define AST_LOG_DTMF    __LOG_DTMF, _A_
302
303 #define NUMLOGLEVELS 32
304
305 /*!
306  * \brief Get the debug level for a module
307  * \param module the name of module
308  * \return the debug level
309  */
310 unsigned int ast_debug_get_by_module(const char *module);
311
312 /*!
313  * \brief Get the verbose level for a module
314  * \param module the name of module
315  * \return the verbose level
316  * \version 11.0.0 deprecated
317  */
318 unsigned int ast_verbose_get_by_module(const char *module) __attribute__((deprecated));
319
320 /*!
321  * \brief Register a new logger level
322  * \param name The name of the level to be registered
323  * \retval -1 if an error occurs
324  * \retval non-zero level to be used with ast_log for sending messages to this level
325  * \since 1.8
326  */
327 int ast_logger_register_level(const char *name);
328
329 /*!
330  * \brief Unregister a previously registered logger level
331  * \param name The name of the level to be unregistered
332  * \return nothing
333  * \since 1.8
334  */
335 void ast_logger_unregister_level(const char *name);
336
337 /*!
338  * \brief Get the logger configured date format
339  *
340  * \retval The date format string
341  *
342  * \since 13.0.0
343  */
344 const char *ast_logger_get_dateformat(void);
345
346 /*!
347  * \brief factory function to create a new uniquely identifying callid.
348  *
349  * \retval The call id
350  */
351 ast_callid ast_create_callid(void);
352
353 /*!
354  * \brief extracts the callerid from the thread
355  *
356  * \retval Non-zero Call id related to the thread
357  * \retval 0 if no call_id is present in the thread
358  */
359 ast_callid ast_read_threadstorage_callid(void);
360
361 /*!
362  * \brief Sets what is stored in the thread storage to the given
363  *        callid if it does not match what is already there.
364  *
365  * \retval 0 - success
366  * \retval non-zero - failure
367  */
368 int ast_callid_threadassoc_change(ast_callid callid);
369
370 /*!
371  * \brief Adds a known callid to thread storage of the calling thread
372  *
373  * \retval 0 - success
374  * \retval non-zero - failure
375  */
376 int ast_callid_threadassoc_add(ast_callid callid);
377
378 /*!
379  * \brief Removes callid from thread storage of the calling thread
380  *
381  * \retval 0 - success
382  * \retval non-zero - failure
383  */
384 int ast_callid_threadassoc_remove(void);
385
386 /*!
387  * \brief Checks thread storage for a callid and stores a reference if it exists.
388  *        If not, then a new one will be created, bound to the thread, and a reference
389  *        to it will be stored.
390  *
391  * \param callid pointer to store the callid
392  * \retval 0 - callid was found
393  * \retval 1 - callid was created
394  * \retval -1 - the function failed somehow (presumably memory problems)
395  */
396 int ast_callid_threadstorage_auto(ast_callid *callid);
397
398 /*!
399  * \brief Use in conjunction with ast_callid_threadstorage_auto. Cleans up the
400  *        references and if the callid was created by threadstorage_auto, unbinds
401  *        the callid from the threadstorage
402  * \param callid The callid set by ast_callid_threadstorage_auto
403  * \param callid_created The integer returned through ast_callid_threadstorage_auto
404  */
405 void ast_callid_threadstorage_auto_clean(ast_callid callid, int callid_created);
406
407 /*!
408  * \brief copy a string representation of the callid into a target string
409  *
410  * \param buffer destination of callid string (should be able to store 13 characters or more)
411  * \param buffer_size maximum writable length of the string (Less than 13 will result in truncation)
412  * \param callid Callid for which string is being requested
413  */
414 void ast_callid_strnprint(char *buffer, size_t buffer_size, ast_callid callid);
415
416 /*!
417  * \brief Send a log message to a dynamically registered log level
418  * \param level The log level to send the message to
419  *
420  * Like ast_log, the log message may include printf-style formats, and
421  * the data for these must be provided as additional parameters after
422  * the log message.
423  *
424  * \return nothing
425  * \since 1.8
426  */
427
428 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
429
430 #define DEBUG_ATLEAST(level) \
431         (option_debug >= (level) \
432                 || (ast_opt_dbg_module && (int)ast_debug_get_by_module(AST_MODULE) >= (level)))
433
434 /*!
435  * \brief Log a DEBUG message
436  * \param level The minimum value of option_debug for this message
437  *        to get logged
438  */
439 #define ast_debug(level, ...) \
440         do { \
441                 if (DEBUG_ATLEAST(level)) { \
442                         ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
443                 } \
444         } while (0)
445
446 extern int ast_verb_sys_level;
447
448 #define VERBOSITY_ATLEAST(level) ((level) <= ast_verb_sys_level)
449
450 #define ast_verb(level, ...) \
451         do { \
452                 if (VERBOSITY_ATLEAST(level) ) { \
453                         __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, __VA_ARGS__); \
454                 } \
455         } while (0)
456
457 #define ast_verb_callid(level, callid, ...) \
458         do { \
459                 if (VERBOSITY_ATLEAST(level) ) { \
460                         __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, callid, __VA_ARGS__); \
461                 } \
462         } while (0)
463
464 /*!
465  * \brief Re-evaluate the system max verbosity level (ast_verb_sys_level).
466  *
467  * \return Nothing
468  */
469 void ast_verb_update(void);
470
471 /*!
472  * \brief Register this thread's console verbosity level pointer.
473  *
474  * \param level Where the verbose level value is.
475  *
476  * \return Nothing
477  */
478 void ast_verb_console_register(int *level);
479
480 /*!
481  * \brief Unregister this thread's console verbosity level.
482  *
483  * \return Nothing
484  */
485 void ast_verb_console_unregister(void);
486
487 /*!
488  * \brief Get this thread's console verbosity level.
489  *
490  * \retval verbosity level of the console.
491  */
492 int ast_verb_console_get(void);
493
494 /*!
495  * \brief Set this thread's console verbosity level.
496  *
497  * \param verb_level New level to set.
498  *
499  * \return Nothing
500  */
501 void ast_verb_console_set(int verb_level);
502
503 #if defined(__cplusplus) || defined(c_plusplus)
504 }
505 #endif
506
507 #endif /* _ASTERISK_LOGGER_H */