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