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