Asterisk - The Open Source Telephony Project  21.4.1
include/asterisk/logger.h
Go to the documentation of this file.
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
21  *
22  * \brief Support for logging to various files, console and syslog
23  * Configuration in file logger.conf
24  */
25 
26 #ifndef _ASTERISK_LOGGER_H
27 #define _ASTERISK_LOGGER_H
28 
29 #include "asterisk/options.h" /* need option_debug */
30 
31 #if defined(__cplusplus) || defined(c_plusplus)
32 extern "C" {
33 #endif
34 
35 #define EVENTLOG "event_log"
36 #define QUEUELOG "queue_log"
37 
38 #define DEBUG_M(a) { \
39  a; \
40 }
41 
42 #define _A_ __FILE__, __LINE__, __FUNCTION__
43 
44 #define VERBOSE_PREFIX_1 " "
45 #define VERBOSE_PREFIX_2 " == "
46 #define VERBOSE_PREFIX_3 " -- "
47 #define VERBOSE_PREFIX_4 " > "
48 #define VERBOSE_PREFIX_5 " > "
49 #define VERBOSE_PREFIX_6 " > "
50 #define VERBOSE_PREFIX_7 " > "
51 #define VERBOSE_PREFIX_8 " > "
52 #define VERBOSE_PREFIX_9 " > "
53 #define VERBOSE_PREFIX_10 " > "
54 
55 #define AST_CALLID_BUFFER_LENGTH 13
56 
58  AST_LOGGER_SUCCESS = 0, /*!< Log channel was created or deleted successfully*/
59  AST_LOGGER_FAILURE = 1, /*!< Log channel already exists for create or doesn't exist for deletion of log channel */
60  AST_LOGGER_DECLINE = -1, /*!< Log channel request was not accepted */
61  AST_LOGGER_ALLOC_ERROR = -2 /*!< filename allocation error */
62 };
63 
64 /*! \brief Used for sending a log message
65  This is the standard logger function. Probably the only way you will invoke it would be something like this:
66  ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain. We should get some more. Will %d be enough?\n", "flux capacitor", 10);
67  where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
68  on which log you wish to output to. These are implemented as macros, that
69  will provide the function with the needed arguments.
70 
71  \param level Type of log event
72  \param file Will be provided by the AST_LOG_* macro
73  \param line Will be provided by the AST_LOG_* macro
74  \param function Will be provided by the AST_LOG_* macro
75  \param fmt This is what is important. The format is the same as your favorite breed of printf. You know how that works, right? :-)
76  */
77 
78 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
79  __attribute__((format(printf, 5, 6)));
80 
81 void ast_log_ap(int level, const char *file, int line, const char *function, const char *fmt, va_list ap)
82  __attribute__((format(printf, 5, 0)));
83 
84 /*!
85  * \brief Used for sending a log message with protection against recursion.
86  *
87  * \note This function should be used by all error messages that might be directly
88  * or indirectly caused by logging.
89  *
90  * \see ast_log for documentation on the parameters.
91  */
92 void ast_log_safe(int level, const char *file, int line, const char *function, const char *fmt, ...)
93  __attribute__((format(printf, 5, 6)));
94 
95 /* XXX needs documentation */
96 typedef unsigned int ast_callid;
97 
98 /*! \brief Used for sending a log message with a known call_id
99  This is a modified logger function which is functionally identical to the above logger function,
100  it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
101  join the log message with a call_id.
102 
103  \param level Type of log event
104  \param file Will be provided by the AST_LOG_* macro
105  \param line Will be provided by the AST_LOG_* macro
106  \param function Will be provided by the AST_LOG_* macro
107  \param callid This is the ast_callid that is associated with the log message. May be NULL.
108  \param fmt This is what is important. The format is the same as your favorite breed of printf. You know how that works, right? :-)
109 */
110 void ast_log_callid(int level, const char *file, int line, const char *function, ast_callid callid, const char *fmt, ...)
111  __attribute__((format(printf, 6, 7)));
112 
113 /*!
114  * \brief Retrieve the existing log channels
115  * \param logentry A callback to an updater function
116  * \param data Data passed into the callback for manipulation
117  *
118  * For each of the logging channels, logentry will be executed with the
119  * channel file name, log type, status of the log, and configuration levels.
120  *
121  * \retval 0 on success
122  * \retval 1 on failure
123  * \retval -2 on allocation error
124  */
125 int ast_logger_get_channels(int (*logentry)(const char *channel, const char *type,
126  const char *status, const char *configuration, void *data), void *data);
127 
128 /*!
129  * \brief Create a log channel
130  *
131  * \param log_channel Log channel to create
132  * \param components Logging config levels to add to the log channel
133  */
134 int ast_logger_create_channel(const char *log_channel, const char *components);
135 
136 /*!
137  * \brief Delete the specified log channel
138  *
139  * \param log_channel The log channel to delete
140  */
141 int ast_logger_remove_channel(const char *log_channel);
142 
143 /*!
144  * \brief Log a backtrace of the current thread's execution stack to the Asterisk log
145  */
146 void ast_log_backtrace(void);
147 
148 /*! \brief Reload logger while rotating log files */
149 int ast_logger_rotate(void);
150 
151 /*!
152  * \brief Rotate the specified log channel.
153  *
154  * \param log_channel The log channel to rotate
155  */
156 int ast_logger_rotate_channel(const char *log_channel);
157 
158 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
159 
160 /*!
161  * \brief Send a verbose message (based on verbose level)
162  *
163  * \details This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
164  *
165  * ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
166  *
167  * This will print the message to the console if the verbose level is set to a level >= 3
168  *
169  * Note the absence of a comma after the VERBOSE_PREFIX_3. This is important.
170  * VERBOSE_PREFIX_1 through VERBOSE_PREFIX_10 are defined.
171  *
172  * \version 11 added level parameter
173  */
174 void __attribute__((format(printf, 5, 6))) __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt, ...);
175 
176 /*!
177  * \brief Send a verbose message (based on verbose level) with deliberately specified callid
178  *
179  * \details just like __ast_verbose, only __ast_verbose_callid allows you to specify which callid is being used
180  * for the log without needing to bind it to a thread. NULL is a valid argument for this function and will
181  * allow you to specify that a log will never display a call id even when there is a call id bound to the
182  * thread.
183  */
184 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, ...);
185 
186 #define ast_verbose(...) __ast_verbose(_A_, -1, __VA_ARGS__)
187 #define ast_verbose_callid(callid, ...) __ast_verbose_callid(_A_, -1, callid, __VA_ARGS__)
188 
189 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);
190 
191 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
192 
193 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
194 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
195 
196 /*
197  * These gymnastics are due to platforms which designate char as unsigned by
198  * default. Level is the negative character -- offset by 1, because \0 is
199  * the string terminator.
200  */
201 #define VERBOSE_MAGIC2LEVEL(x) (((char) -*(signed char *) (x)) - 1)
202 #define VERBOSE_HASMAGIC(x) (*(signed char *) (x) < 0)
203 
204 void ast_console_puts(const char *string);
205 
206 /*!
207  * \brief log the string to the console, and all attached console clients
208  *
209  * \param string The message to write to the console
210  * \param level The log level of the message
211  *
212  * \version 1.6.1 added level parameter
213  */
214 void ast_console_puts_mutable(const char *string, int level);
215 
216 /*!
217  * \brief log the string to the console, and all attached console clients
218  * \since 14.0.0
219  *
220  * \param message The message to write to the console
221  * \param sublevel If the log level supports it, the sub-level of the message
222  * \param level The log level of the message
223  */
224 void ast_console_puts_mutable_full(const char *message, int level, int sublevel);
225 
226 void ast_console_toggle_mute(int fd, int silent);
227 
228 /*!
229  * \brief enables or disables logging of a specified level to the console
230  * fd specifies the index of the console receiving the level change
231  * level specifies the index of the logging level being toggled
232  * state indicates whether logging will be on or off (0 for off, 1 for on)
233  */
234 void ast_console_toggle_loglevel(int fd, int level, int state);
235 
236 /* Note: The AST_LOG_* macros below are the same as
237  * the LOG_* macros and are intended to eventually replace
238  * the LOG_* macros to avoid name collisions with the syslog(3)
239  * log levels. However, please do NOT remove
240  * the LOG_* macros from the source since these may be still
241  * needed for third-party modules
242  */
243 
244 #ifdef LOG_DEBUG
245 #undef LOG_DEBUG
246 #endif
247 #define __LOG_DEBUG 0
248 #define LOG_DEBUG __LOG_DEBUG, _A_
249 
250 #ifdef AST_LOG_DEBUG
251 #undef AST_LOG_DEBUG
252 #endif
253 #define AST_LOG_DEBUG __LOG_DEBUG, _A_
254 
255 #ifdef LOG_TRACE
256 #undef LOG_TRACE
257 #endif
258 #define __LOG_TRACE 1
259 #define LOG_TRACE __LOG_TRACE, _A_
260 
261 #ifdef AST_LOG_TRACE
262 #undef AST_LOG_TRACE
263 #endif
264 #define AST_LOG_TRACE __LOG_TRACE, _A_
265 
266 #ifdef LOG_NOTICE
267 #undef LOG_NOTICE
268 #endif
269 #define __LOG_NOTICE 2
270 #define LOG_NOTICE __LOG_NOTICE, _A_
271 
272 #ifdef AST_LOG_NOTICE
273 #undef AST_LOG_NOTICE
274 #endif
275 #define AST_LOG_NOTICE __LOG_NOTICE, _A_
276 
277 #ifdef LOG_WARNING
278 #undef LOG_WARNING
279 #endif
280 #define __LOG_WARNING 3
281 #define LOG_WARNING __LOG_WARNING, _A_
282 
283 #ifdef AST_LOG_WARNING
284 #undef AST_LOG_WARNING
285 #endif
286 #define AST_LOG_WARNING __LOG_WARNING, _A_
287 
288 #ifdef LOG_ERROR
289 #undef LOG_ERROR
290 #endif
291 #define __LOG_ERROR 4
292 #define LOG_ERROR __LOG_ERROR, _A_
293 
294 #ifdef AST_LOG_ERROR
295 #undef AST_LOG_ERROR
296 #endif
297 #define AST_LOG_ERROR __LOG_ERROR, _A_
298 
299 #ifdef LOG_VERBOSE
300 #undef LOG_VERBOSE
301 #endif
302 #define __LOG_VERBOSE 5
303 #define LOG_VERBOSE __LOG_VERBOSE, _A_
304 
305 #ifdef AST_LOG_VERBOSE
306 #undef AST_LOG_VERBOSE
307 #endif
308 #define AST_LOG_VERBOSE __LOG_VERBOSE, _A_
309 
310 #ifdef LOG_DTMF
311 #undef LOG_DTMF
312 #endif
313 #define __LOG_DTMF 6
314 #define LOG_DTMF __LOG_DTMF, _A_
315 
316 #ifdef AST_LOG_DTMF
317 #undef AST_LOG_DTMF
318 #endif
319 #define AST_LOG_DTMF __LOG_DTMF, _A_
320 
321 #define NUMLOGLEVELS 32
322 
323 /*!
324  * \brief Get the debug level for a module
325  * \param module the name of module
326  * \return the debug level
327  */
328 unsigned int ast_debug_get_by_module(const char *module);
329 
330 /*!
331  * \brief Register a new logger level
332  * \param name The name of the level to be registered
333  * \retval -1 if an error occurs
334  * \retval non-zero level to be used with ast_log for sending messages to this level
335  * \since 1.8
336  */
337 int ast_logger_register_level(const char *name);
338 
339 /*!
340  * \brief Retrieve dynamic logging level id
341  * \param name The name of the level
342  * \return The unique integer id for the given level
343  * \retval -1 if level name not found
344  */
345 int ast_logger_get_dynamic_level(const char *name);
346 
347 /*!
348  * \brief Unregister a previously registered logger level
349  * \param name The name of the level to be unregistered
350  * \since 1.8
351  */
352 void ast_logger_unregister_level(const char *name);
353 
354 /*!
355  * \brief Get the logger configured date format
356  *
357  * \return The date format string
358  *
359  * \since 13.0.0
360  */
361 const char *ast_logger_get_dateformat(void);
362 
363 /*!
364  * \brief factory function to create a new uniquely identifying callid.
365  *
366  * \return The call id
367  */
368 ast_callid ast_create_callid(void);
369 
370 /*!
371  * \brief extracts the callerid from the thread
372  *
373  * \retval Non-zero Call id related to the thread
374  * \retval 0 if no call_id is present in the thread
375  */
376 ast_callid ast_read_threadstorage_callid(void);
377 
378 /*!
379  * \brief Sets what is stored in the thread storage to the given
380  * callid if it does not match what is already there.
381  *
382  * \retval 0 - success
383  * \retval non-zero - failure
384  */
385 int ast_callid_threadassoc_change(ast_callid callid);
386 
387 /*!
388  * \brief Adds a known callid to thread storage of the calling thread
389  *
390  * \retval 0 - success
391  * \retval non-zero - failure
392  */
393 int ast_callid_threadassoc_add(ast_callid callid);
394 
395 /*!
396  * \brief Removes callid from thread storage of the calling thread
397  *
398  * \retval 0 - success
399  * \retval non-zero - failure
400  */
402 
403 /*!
404  * \brief Checks thread storage for a callid and stores a reference if it exists.
405  * If not, then a new one will be created, bound to the thread, and a reference
406  * to it will be stored.
407  *
408  * \param callid pointer to store the callid
409  * \retval 0 - callid was found
410  * \retval 1 - callid was created
411  * \retval -1 - the function failed somehow (presumably memory problems)
412  */
413 int ast_callid_threadstorage_auto(ast_callid *callid);
414 
415 /*!
416  * \brief Use in conjunction with ast_callid_threadstorage_auto. Cleans up the
417  * references and if the callid was created by threadstorage_auto, unbinds
418  * the callid from the threadstorage
419  * \param callid The callid set by ast_callid_threadstorage_auto
420  * \param callid_created The integer returned through ast_callid_threadstorage_auto
421  */
422 void ast_callid_threadstorage_auto_clean(ast_callid callid, int callid_created);
423 
424 /*!
425  * \brief copy a string representation of the callid into a target string
426  *
427  * \param buffer destination of callid string (should be able to store 13 characters or more)
428  * \param buffer_size maximum writable length of the string (Less than 13 will result in truncation)
429  * \param callid Callid for which string is being requested
430  */
431 void ast_callid_strnprint(char *buffer, size_t buffer_size, ast_callid callid);
432 
433 /*!
434  * \brief Send a log message to a dynamically registered log level
435  * \param level The log level to send the message to
436  *
437  * Like ast_log, the log message may include printf-style formats, and
438  * the data for these must be provided as additional parameters after
439  * the log message.
440  *
441  * \since 1.8
442  */
443 
444 #define ast_log_dynamic_level(level, ...) ast_log(level, _A_, __VA_ARGS__)
445 
446 #define DEBUG_ATLEAST(level) \
447  (option_debug >= (level) \
448  || (ast_opt_dbg_module \
449  && ((int)ast_debug_get_by_module(AST_MODULE) >= (level) \
450  || (int)ast_debug_get_by_module(__FILE__) >= (level))))
451 
452 /*!
453  * \brief Log a DEBUG message
454  * \param level The minimum value of option_debug for this message
455  * to get logged
456  */
457 #define ast_debug(level, ...) \
458  do { \
459  if (DEBUG_ATLEAST(level)) { \
460  ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
461  } \
462  } while (0)
463 
464 extern int ast_verb_sys_level;
465 
466 #define VERBOSITY_ATLEAST(level) ((level) <= ast_verb_sys_level)
467 
468 #define ast_verb(level, ...) \
469  do { \
470  if (VERBOSITY_ATLEAST(level) ) { \
471  __ast_verbose(_A_, level, __VA_ARGS__); \
472  } \
473  } while (0)
474 
475 #define ast_verb_callid(level, callid, ...) \
476  do { \
477  if (VERBOSITY_ATLEAST(level) ) { \
478  __ast_verbose_callid(_A_, level, callid, __VA_ARGS__); \
479  } \
480  } while (0)
481 
482 /*!
483  * \brief Re-evaluate the system max verbosity level (ast_verb_sys_level).
484  */
485 void ast_verb_update(void);
486 
487 /*!
488  * \brief Register this thread's console verbosity level pointer.
489  *
490  * \param level Where the verbose level value is.
491  */
492 void ast_verb_console_register(int *level);
493 
494 /*!
495  * \brief Unregister this thread's console verbosity level.
496  */
497 void ast_verb_console_unregister(void);
498 
499 /*!
500  * \brief Get this thread's console verbosity level.
501  *
502  * \return verbosity level of the console.
503  */
504 int ast_verb_console_get(void);
505 
506 /*!
507  * \brief Set this thread's console verbosity level.
508  *
509  * \param verb_level New level to set.
510  */
511 void ast_verb_console_set(int verb_level);
512 
513 /*!
514  * \brief Test if logger is initialized
515  *
516  * \retval true if the logger is initialized
517  */
518 int ast_is_logger_initialized(void);
519 
520 /*!
521  * \brief Set the maximum number of messages allowed in the processing queue
522  *
523  * \param queue_limit
524  */
525 void ast_logger_set_queue_limit(int queue_limit);
526 
527 /*!
528  * \brief Get the maximum number of messages allowed in the processing queue
529  *
530  * \return Queue limit
531  */
533 
534 
535 /*! \defgroup Scope_Trace Scope Trace
536  * @{
537 \page basic Basic Usage
538 
539 The Scope Trace facility allows you to instrument code and output scope entry
540 and exit messages with associated data.
541 \par
542 To start using it:
543  - You must have used --enable-dev-mode.
544  - In logger.conf, set a logger channel to output the "trace" level.
545  - Instrument your code as specified below.
546  - Use the cli or cli.conf to enable tracing:
547 \verbatim CLI> core set trace <trace_level> [ module ] \endverbatim
548 \par
549 Its simplest usage requires only 1 macro call that...
550  - Registers a destructor for a special variable that gets called when the
551  variable goes out of scope. Uses the same principle as RAII_VAR.
552  The destructor prints the name of the function with an "exiting" indicator
553  along with an optional message.
554  - Prints the name of the function with an "entering" indicator along with
555  an optional message.
556 
557 Simple Example:
558 The following code...
559 \code
560 static struct pjmedia_sdp_session *create_local_sdp(pjsip_inv_session *inv,
561  struct ast_sip_session *session, const pjmedia_sdp_session *offer)
562 {
563  SCOPE_TRACE(1, "%s\n", ast_sip_session_get_name(session));
564  ...
565 }
566 \endcode
567 would produce...
568 \verbatim
569 [2020-05-17 15:16:51 -0600] TRACE[953402] : --> res_pjsip_session.c:4283 create_local_sdp PJSIP/1173-00000001
570 [2020-05-17 15:16:51 -0600] TRACE[953402] : <-- res_pjsip_session.c:4283 create_local_sdp PJSIP/1173-00000001
571 \endverbatim
572 
573 There is one odd bit. There's no way to capture the line number of there the scope exited
574 so it's always going to be the line where SCOPE_TRACE is located.
575 \par
576 Similar to RAII_VAR, any block scope can be traced including "if", "for", "while", etc.
577 \note "case" statements don't create a scope block by themselves but you can create
578 a block for it, or use the generic trace functions mentioned below.
579 
580 \par Scope Output and Level:
581 Rather than sending trace messages to the debug facility, a new facility "trace" has been
582 added to logger. A corresponding CLI command "core set trace", and a corresponding "trace"
583 parameter in asterisk.conf were added. This allows a separate log channel to be created
584 just for storing trace messages. The levels are the same as those for debug and verbose.
585 
586 \par Scope Indenting:
587 Each time SCOPE_TRACE or SCOPE_TRACE is called, a thread-local indent value is
588 incremented on scope enter, and decremented on scope exit. This allows output
589 like the following (timestamp omitted for brevity):
590 \verbatim
591 TRACE[953402] : --> res_pjsip_session.c:3940 session_inv_on_tsx_state_changed PJSIP/1173-00000001 TSX State: Proceeding Inv State: CALLING
592 TRACE[953402] : --> res_pjsip_session.c:3680 handle_incoming PJSIP/1173-00000001
593 TRACE[953402] : --> res_pjsip_session.c:3661 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
594 TRACE[953402] : --> res_pjsip_session.c:3669 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Supplement: chan_pjsip
595 TRACE[953402] : --> chan_pjsip.c:3265 chan_pjsip_incoming_response_after_media PJSIP/1173-00000001 Method: INVITE Status: 100 After Media
596 TRACE[953402] : --> chan_pjsip.c:3194 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
597 TRACE[953402] : chan_pjsip.c:3245 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Ignored
598 TRACE[953402] : <-- chan_pjsip.c:3194 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
599 TRACE[953402] : <-- chan_pjsip.c:3265 chan_pjsip_incoming_response_after_media PJSIP/1173-00000001 Method: INVITE Status: 100 After Media
600 TRACE[953402] : <-- res_pjsip_session.c:3669 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Supplement: chan_pjsip
601 TRACE[953402] : <-- res_pjsip_session.c:3661 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
602 TRACE[953402] : <-- res_pjsip_session.c:3680 handle_incoming PJSIP/1173-00000001
603 TRACE[953402] : <-- res_pjsip_session.c:3940 session_inv_on_tsx_state_changed PJSIP/1173-00000001 TSX State: Proceeding Inv State: CALLING
604 \endverbatim
605 \note The trace level indicates which messages to print and has no effect on indent.
606 
607 \par Generic Trace Messages:
608 Sometimes you may just want to print a message to the trace log with the appropriate indent
609 such as when executing a "case" clause in a "switch" statement. For example, the deepest
610 message in the sample output above (chan_pjsip.c:3245) is just a single message instead of
611 an entry/exit message. To do so, you can use the ast_trace macros...
612 \code
613  ast_trace(1, "%s Method: %.*s Status: %d Ignored\n", ast_sip_session_get_name(session),
614  (int)rdata->msg_info.cseq->method.name.slen, rdata->msg_info.cseq->method.name.ptr, status.code);
615 \endcode
616 
617 \note Final note: The trace facility, like debug, is only available when AST_DEVMODE is defined.
618 
619 */
620 
621 /*!
622 \page TRACE_PREFIX TRACE_PREFIX
623 The default prefix to each log and trace line is
624 <tt>"filename:line function"</tt> which is defined in the
625 macro \c _A_ at the top of this file:
626 \code
627 #define _A_ __FILE__, __LINE__, __FUNCTION__
628 \endcode
629 They become 3 arguments to the __ast_trace function
630 and most of the ast_log* functions. For scope tracing,
631 that may be unnecessary clutter in the trace output so
632 you can now customise that with the \c _TRACE_PREFIX_
633 macro. Like \c _A_, it MUST resolve to 3 arguments:
634 \verbatim
635 const char *, int, const char *
636 \endverbatim
637 so the minimum would be:
638 \code
639 #define _TRACE_PREFIX_ "",0,""
640 \endcode
641 Normally you should define \c _TRACE_PREFIX_ in your source
642 file before including logger.h.
643 \code
644 #define _TRACE_PREFIX_ "", __LINE__, ""
645 #include "asterisk/logger.h"
646 \endcode
647 You can also define it later in your source file
648 but because logger.h sets it to a default value, you'll
649 have to undefine it first, then define it your your liking.
650 If you want to go back to the default, you'll have to
651 undefine it again, then define it to \c _TRACE_PREFIX_DEFAULT_.
652 \code
653 #undef _TRACE_PREFIX_
654 #define _TRACE_PREFIX_ "", __LINE__, ""
655 <code>
656 #undef _TRACE_PREFIX_
657 #define _TRACE_PREFIX_ _TRACE_PREFIX_DEFAULT_
658 \endcode
659 
660 \note Macros have a compilation unit scope so
661 defining \c _TRACE_PREFIX_ in one source file does NOT
662 make it apply to any others. So if you define it
663 in source file A, then call a function in source
664 file B, the trace output from B will display based
665 on how \c _TRACE_PREFIX_ is defined in B, not A.
666  */
667 
668 #define _TRACE_PREFIX_DEFAULT_ _A_
669 #ifndef _TRACE_PREFIX_
670 #define _TRACE_PREFIX_ _TRACE_PREFIX_DEFAULT_
671 #endif
672 
673 /*!
674  * \brief Get the trace level for a module
675  * \param module the name of module
676  * \return the trace level
677  */
678 unsigned int ast_trace_get_by_module(const char *module);
679 
680 /*!
681  * \brief load logger.conf configuration for console socket connections
682  */
684 
685 #define TRACE_ATLEAST(level) \
686  (option_trace >= (level) \
687  || (ast_opt_trace_module \
688  && ((int)ast_trace_get_by_module(AST_MODULE) >= (level) \
689  || (int)ast_trace_get_by_module(__FILE__) >= (level))))
690 
691 /*!
692  * \brief Controls if and when indenting is applied.
693  */
695  /*! Use the existing indent level */
697  /*! Increment the indent before printing the message */
699  /*! Increment the indent after printing the message */
701  /*! Decrement the indent before printing the message */
703  /*! Decrement the indent after printing the message */
705  /*! Set the indent to the one provided */
707  /*! Don't use or alter the level */
709 };
710 
711 #ifdef AST_DEVMODE
712 
713 void __attribute__((format (printf, 6, 7))) __ast_trace(const char *file, int line, const char *func,
714  enum ast_trace_indent_type indent_type, unsigned long indent, const char* format, ...);
715 
716 /*!
717  * \brief Print a trace message
718  *
719  * \param level The trace level
720  * \param indent_type One of the \ref ast_trace_indent_type values
721  * \param ... A printf style format string, optionally with arguments
722  *
723  */
724 #define ast_trace_raw(level, indent_type, ...) \
725  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__); \
726  if (TRACE_ATLEAST(level < 0 ? __scope_level : level)) { \
727  __ast_trace(_TRACE_PREFIX_, indent_type, 0, " " __VA_ARGS__); \
728  }
729 
730 /*!
731  * \brief Print a basic trace message
732  *
733  * \param level The trace level
734  * \param ... A printf style format string, optionally with arguments
735  *
736  * This will print the file, line and function at the current indent level
737  */
738 #define ast_trace(level, ...) \
739  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__); \
740  if (TRACE_ATLEAST(level < 0 ? __scope_level : level)) { \
741  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_SAME, 0, " " __VA_ARGS__); \
742  }
743 
744 /*!
745  * \brief Get the current indent level
746  *
747  * \return The current indent level
748  */
749 unsigned long _ast_trace_get_indent(void);
750 #define ast_trace_get_indent() _ast_trace_get_indent()
751 
752 /*!
753  * \brief Set the current indent level
754  *
755  * \param indent The new indent level
756  */
757 void _ast_trace_set_indent(unsigned long indent);
758 #define ast_trace_set_indent(indent) _ast_trace_set_indent(indent)
759 
760 /*!
761  * \brief Increment the indent level
762  *
763  * \return The new indent level
764  */
765 unsigned long _ast_trace_inc_indent(void);
766 #define ast_trace_inc_indent() _ast_trace_inc_indent()
767 
768 /*!
769  * \brief Decrement the indent level
770  *
771  * \return The new indent level
772  */
773 unsigned long _ast_trace_dec_indent(void);
774 #define ast_trace_dec_indent() _ast_trace_dec_indent()
775 
776 /*!
777  * \brief Print a trace message with details when a scope is entered or existed.
778  *
779  * \param level The trace level
780  * \param ... A printf style format string, optionally with arguments
781  *
782  * This will print the file, line and function plus details at the current indent level.
783  * \note Like RAII_VAR, this macro must be called before any code in the scope.
784  *
785  * \note The variables used to detect scope change will look like
786  * __scopevar1234__EXIT and __scopevar1234__ENTER.
787  * The ENTER variable and function are needed to prevent mixed code and declaration issues.
788  * If we simple called __ast_trace, then this macro would need to be the last line
789  * of scope variable declaration. The following would fail.
790  *
791  * SCOPE_TRACE(1, "Help!\n");
792  * int i;
793  */
794 #define SCOPE_TRACE(level, ...) \
795  const char *__trace_funcname = __PRETTY_FUNCTION__; \
796  auto void __scopevar ## __LINE__ ## __EXIT(void * v); \
797  void __scopevar ## __LINE__ ## __EXIT(void * v __attribute__((unused))) { \
798  if (TRACE_ATLEAST(level)) { \
799  __ast_trace(__FILE__, __LINE__, __trace_funcname, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
800  } \
801  } \
802  void *__scopevar ## __LINE__ ## __TRACER __attribute__((cleanup(__scopevar ## __LINE__ ## __EXIT))) = (void *) __PRETTY_FUNCTION__ ; \
803  auto int __scopevar ## __LINE__ ## __ENTER(void); \
804  int __scopevar ## __LINE__ ## __ENTER(void) { \
805  if (TRACE_ATLEAST(level)) { \
806  __ast_trace(__FILE__, __LINE__, __trace_funcname, AST_TRACE_INDENT_INC_AFTER, 0, " " __VA_ARGS__); \
807  } \
808  return 0; \
809  } \
810  int __scopevar ## __LINE__ ## __RETURN __attribute__((unused)) = __scopevar ## __LINE__ ## __ENTER()
811 
812 /*!
813  * \brief Non RAII_VAR Scope Trace macros
814  * The advantage of these macros is that the EXITs will have the actual
815  * line number where the scope exited. Much less code is required as well.
816  */
817 
818 /*!
819  * \brief Scope Enter
820  *
821  * \param level The trace level
822  * \param ... A printf style format string, optionally with arguments
823  */
824 #define SCOPE_ENTER(level, ...) \
825  int __scope_level = level; \
826  int __scope_task = 0; \
827  ast_debug(__scope_level, " " __VA_ARGS__); \
828  if (TRACE_ATLEAST(level)) { \
829  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_INC_AFTER, 0, " " __VA_ARGS__); \
830  } \
831 
832 #define SCOPE_ENTER_TASK(level, indent, ...) \
833  int __scope_level = level; \
834  int __scope_task = 1; \
835  ast_debug(__scope_level, " " __VA_ARGS__); \
836  if (TRACE_ATLEAST(level)) { \
837  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_PROVIDED, indent, " " __VA_ARGS__); \
838  } \
839 
840 /*!
841  * \def SCOPE_CALL
842  * \brief Wrap a function call in "--> Calling:" and "<-- Return from:" trace messages
843  *
844  * \param level The trace level (usually -1 to use the same level as the calling function)
845  * \param __funcname The name of the function to call (return value, if any, is ignored)
846  * \param ... Arguments to pass to the function
847  *
848  * Simple Example:
849  * The following code called from inside the app_voicemail.c leave_voicemail function...
850 \code
851  SCOPE_CALL(-1, store_file, dir, vmu->mailbox, vmu->context, msgnum);
852 \endcode
853  * would produce...
854 \verbatim
855 1 app_voicemail_odbc.c:7161 leave_voicemail: --> Calling store_file
856 1 --> app_voicemail_odbc.c:4483 store_file: dir: /var/spool/asterisk/voicemail/default/1179/INBOX user: 1179 context: default msgnum: 8
857 2 app_voicemail_odbc.c:4502 store_file: Formats: wav49|gsm|wav Using format: 'WAV'
858 2 app_voicemail_odbc.c:4510 store_file: Base path: '/var/spool/asterisk/voicemail/default/1179/INBOX/msg0008'
859 2 app_voicemail_odbc.c:4513 store_file: Basename: 'msg0008'
860 1 <-- app_voicemail_odbc.c:4597 store_file: Success
861 1 app_voicemail_odbc.c:7161 leave_voicemail: <-- Return from store_file
862 \endverbatim
863  */
864 #define SCOPE_CALL(level, __funcname, ...) \
865 ({ \
866  ast_trace(level, "--> Calling %s\n", #__funcname); \
867  __funcname(__VA_ARGS__); \
868  ast_trace(level, "<-- Return from %s\n", #__funcname); \
869 })
870 
871 /*!
872  * \def SCOPE_CALL_WITH_RESULT
873  * \brief Wrap a function call returning a value in "--> Calling:" and "<-- Return from:" trece messages
874  *
875  * \param level The trace level (usually -1 to use the same level as the calling function)
876  * \param __type The return type of the function
877  * \param __funcname The name of the function to call
878  * \param ... Arguments to pass to the function
879  *
880  * Simple Example:
881  * The following code called from inside the app_voicemail.c leave_voicemail function...
882 \code
883  int res = 0;
884  res = SCOPE_CALL_WITH_RESULT(-1, int, store_file, dir, vmu->mailbox, vmu->context, msgnum);
885 \endcode
886  * would produce...
887 \verbatim
888 1 app_voicemail_odbc.c:7161 leave_voicemail: --> Calling store_file
889 1 --> app_voicemail_odbc.c:4483 store_file: dir: /var/spool/asterisk/voicemail/default/1179/INBOX user: 1179 context: default msgnum: 8
890 2 app_voicemail_odbc.c:4502 store_file: Formats: wav49|gsm|wav Using format: 'WAV'
891 2 app_voicemail_odbc.c:4510 store_file: Base path: '/var/spool/asterisk/voicemail/default/1179/INBOX/msg0008'
892 2 app_voicemail_odbc.c:4513 store_file: Basename: 'msg0008'
893 1 <-- app_voicemail_odbc.c:4597 store_file: Success
894 1 app_voicemail_odbc.c:7161 leave_voicemail: <-- Return from store_file
895 \endverbatim
896  * ...and the return value of the store_file function would be assigned to the variable res.
897  */
898 #define SCOPE_CALL_WITH_RESULT(level, __type, __funcname, ...) \
899 ({ \
900  __type __var; \
901  ast_trace(level, "--> Calling %s\n", #__funcname); \
902  __var = __funcname(__VA_ARGS__); \
903  ast_trace(level, "<-- Return from %s\n", #__funcname) \
904  __var; \
905 })
906 
907 #define SCOPE_CALL_WITH_INT_RESULT(level, __funcname, ...) \
908  SCOPE_CALL_WITH_RESULT(level, int, __funcname, __VA_ARGS__)
909 
910 /*!
911  * \brief Scope Exit
912  *
913  * \param ... A printf style format string, optionally with arguments
914  *
915  * \details
916  * This macro can be used at the exit points of a statement block since it just prints the message.
917  */
918 #define SCOPE_EXIT(...) \
919  ast_debug(__scope_level, " " __VA_ARGS__); \
920  if (TRACE_ATLEAST(__scope_level)) { \
921  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
922  if (__scope_task) { \
923  _ast_trace_set_indent(0); \
924  } \
925  } \
926 
927 /*!
928  * \brief Scope Exit with expression
929  *
930  * \param __expr An expression to execute after printing the message
931  * \param ... A printf style format string, optionally with arguments
932  *
933  * \details
934  * Handy for getting out of or continuing loops.
935  *
936  * \code
937  * while(something) {
938  * SCOPE_ENTER(2, "In a while\n");
939  * if (something) {
940  * SCOPE_EXIT_EXPR(break, "Somethiung broke me\n");
941  * } else {
942  * SCOPE_EXIT_EXPR(continue, "Somethiung continued me\n");
943  * }
944  * }
945  * \endcode
946  */
947 #define SCOPE_EXIT_EXPR(__expr, ...) \
948  ast_debug(__scope_level, " " __VA_ARGS__); \
949  if (TRACE_ATLEAST(__scope_level)) { \
950  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
951  if (__scope_task) { \
952  _ast_trace_set_indent(0); \
953  } \
954  } \
955  __expr
956 
957 /*!
958  * \brief Scope Exit with return
959  *
960  * \param ... A printf style format string, optionally with arguments
961  *
962  * \details
963  * This macro can be used at the exit points of a function when no value
964  * needs to be returned.
965  */
966 #define SCOPE_EXIT_RTN(...) \
967  ast_debug(__scope_level, " " __VA_ARGS__); \
968  if (TRACE_ATLEAST(__scope_level)) { \
969  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
970  if (__scope_task) { \
971  _ast_trace_set_indent(0); \
972  } \
973  } \
974  return
975 
976 /*!
977  * \brief Scope Exit with return value
978  *
979  * \param __return_value The return value
980  * \param ... A printf style format string, optionally with arguments
981  *
982  * \details
983  * This macro can be used at the exit points of a function when a value
984  * needs to be returned.
985  */
986 #define SCOPE_EXIT_RTN_VALUE(__return_value, ...) \
987  ast_debug(__scope_level, " " __VA_ARGS__); \
988  if (TRACE_ATLEAST(__scope_level)) { \
989  __ast_trace(_TRACE_PREFIX_, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
990  if (__scope_task) { \
991  _ast_trace_set_indent(0); \
992  } \
993  } \
994  return(__return_value)
995 
996 #else /* AST_DEVMODE */
997 #define ast_trace_raw(level, indent_type, ...) \
998  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__)
999 
1000 #define ast_trace(level, ...) \
1001  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__)
1002 
1003 #define ast_trace_get_indent() (0)
1004 #define ast_trace_set_indent(indent)
1005 #define ast_trace_inc_indent()
1006 #define ast_trace_dec_indent()
1007 #define SCOPE_TRACE(__level, ...)
1008 
1009 #define SCOPE_ENTER(level, ...) \
1010  int __scope_level = level; \
1011  ast_debug(level, " " __VA_ARGS__)
1012 
1013 #define SCOPE_ENTER_TASK(level, indent, ...) \
1014  int __scope_level = level; \
1015  ast_debug(level, " " __VA_ARGS__)
1016 
1017 #define SCOPE_CALL(level, __funcname, ...) \
1018  __funcname(__VA_ARGS__)
1019 
1020 #define SCOPE_CALL_WITH_RESULT(level, __var, __funcname, ...) \
1021  __var = __funcname(__VA_ARGS__)
1022 
1023 #define SCOPE_CALL_WITH_INT_RESULT(level, __funcname, ...) \
1024  __funcname(__VA_ARGS__)
1025 
1026 #define SCOPE_EXIT(...) \
1027  ast_debug(__scope_level, " " __VA_ARGS__)
1028 
1029 #define SCOPE_EXIT_EXPR(__expr, ...) \
1030  ast_debug(__scope_level, " " __VA_ARGS__); \
1031  __expr
1032 
1033 #define SCOPE_EXIT_RTN(...) \
1034  ast_debug(__scope_level, " " __VA_ARGS__); \
1035  return
1036 
1037 #define SCOPE_EXIT_RTN_VALUE(__return_value, ...) \
1038  ast_debug(__scope_level, " " __VA_ARGS__); \
1039  return __return_value
1040 
1041 #endif /* AST_DEVMODE */
1042 
1043 /*!
1044  * The following macros will print log messages before running
1045  * the associated SCOPE_ macro.
1046  */
1047 
1048 #define SCOPE_EXIT_LOG(__log_level, ...) \
1049 ({ \
1050  ast_log(__log_level, " " __VA_ARGS__); \
1051  SCOPE_EXIT(" " __VA_ARGS__); \
1052 })
1053 
1054 #define SCOPE_EXIT_LOG_RTN(__log_level, ...) \
1055 ({ \
1056  ast_log(__log_level, " " __VA_ARGS__); \
1057  SCOPE_EXIT_RTN(" " __VA_ARGS__); \
1058 })
1059 
1060 #define SCOPE_EXIT_LOG_RTN_VALUE(__value, __log_level, ...) \
1061 ({ \
1062  ast_log(__log_level, " " __VA_ARGS__); \
1063  SCOPE_EXIT_RTN_VALUE(__value, " " __VA_ARGS__); \
1064 })
1065 
1066 #define SCOPE_EXIT_LOG_EXPR(__expr, __log_level, ...) \
1067 ({ \
1068  ast_log(__log_level, " " __VA_ARGS__); \
1069  SCOPE_EXIT_EXPR(__expr, " " __VA_ARGS__); \
1070 })
1071 
1072 #define ast_trace_log(__level, __log_level, ...) \
1073 ({ \
1074  ast_log(__log_level, " " __VA_ARGS__); \
1075  ast_trace(__level < 0 ? __scope_level : __level, " " __VA_ARGS__); \
1076 })
1077 
1078 
1079 #if defined(__cplusplus) || defined(c_plusplus)
1080 }
1081 #endif
1082 
1083 /*!
1084  * @}
1085  */
1086 
1087 #endif /* _ASTERISK_LOGGER_H */
void ast_verb_console_unregister(void)
Unregister this thread's console verbosity level.
Definition: logger.c:2662
void ast_verb_update(void)
Re-evaluate the system max verbosity level (ast_verb_sys_level).
Definition: logger.c:2584
unsigned int ast_trace_get_by_module(const char *module)
Get the trace level for a module.
Definition: main/cli.c:153
int ast_logger_get_dynamic_level(const char *name)
Retrieve dynamic logging level id.
Definition: logger.c:2880
int ast_logger_rotate(void)
Reload logger while rotating log files.
Definition: logger.c:1327
int ast_logger_get_channels(int(*logentry)(const char *channel, const char *type, const char *status, const char *configuration, void *data), void *data)
Retrieve the existing log channels.
Definition: logger.c:1409
int ast_callid_threadassoc_change(ast_callid callid)
Sets what is stored in the thread storage to the given callid if it does not match what is already th...
Definition: logger.c:2307
int ast_logger_get_queue_limit(void)
Get the maximum number of messages allowed in the processing queue.
Definition: logger.c:2937
void ast_logger_set_queue_limit(int queue_limit)
Set the maximum number of messages allowed in the processing queue.
Definition: logger.c:2932
void ast_verb_console_register(int *level)
Register this thread's console verbosity level pointer.
Definition: logger.c:2646
void ast_logger_unregister_level(const char *name)
Unregister a previously registered logger level.
Definition: logger.c:2909
Definition: astman.c:222
int ast_callid_threadassoc_add(ast_callid callid)
Adds a known callid to thread storage of the calling thread.
Definition: logger.c:2320
int ast_verb_console_get(void)
Get this thread's console verbosity level.
Definition: logger.c:2673
int ast_logger_create_channel(const char *log_channel, const char *components)
Create a log channel.
Definition: logger.c:1521
ast_callid ast_read_threadstorage_callid(void)
extracts the callerid from the thread
Definition: logger.c:2298
void ast_console_puts(const char *string)
write the string to the root console, and all attached network console clients
Definition: asterisk.c:1356
void ast_log_backtrace(void)
Log a backtrace of the current thread's execution stack to the Asterisk log.
Definition: logger.c:2510
void __ast_verbose_callid(const char *file, int line, const char *func, int level, ast_callid callid, const char *fmt,...)
Send a verbose message (based on verbose level) with deliberately specified callid.
Definition: logger.c:2562
void __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt,...)
Send a verbose message (based on verbose level)
Definition: logger.c:2550
int ast_callid_threadassoc_remove(void)
Removes callid from thread storage of the calling thread.
Definition: logger.c:2339
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: ael_main.c:130
void ast_callid_threadstorage_auto_clean(ast_callid callid, int callid_created)
Use in conjunction with ast_callid_threadstorage_auto. Cleans up the references and if the callid was...
Definition: logger.c:2378
void ast_log_safe(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message with protection against recursion.
Definition: logger.c:2475
int ast_verb_sys_level
Definition: options.c:64
ast_trace_indent_type
Controls if and when indenting is applied.
void ast_log_callid(int level, const char *file, int line, const char *function, ast_callid callid, const char *fmt,...)
Used for sending a log message with a known call_id This is a modified logger function which is funct...
Definition: logger.c:2501
int ast_logger_rotate_channel(const char *log_channel)
Rotate the specified log channel.
Definition: logger.c:1332
void ast_console_toggle_loglevel(int fd, int level, int state)
enables or disables logging of a specified level to the console fd specifies the index of the console...
Definition: asterisk.c:1251
int ast_logger_remove_channel(const char *log_channel)
Delete the specified log channel.
Definition: logger.c:1587
int ast_callid_threadstorage_auto(ast_callid *callid)
Checks thread storage for a callid and stores a reference if it exists. If not, then a new one will b...
Definition: logger.c:2356
void ast_init_logger_for_socket_console(void)
load logger.conf configuration for console socket connections
Definition: logger.c:713
void ast_console_puts_mutable_full(const char *message, int level, int sublevel)
log the string to the console, and all attached console clients
Definition: asterisk.c:1323
const char * ast_logger_get_dateformat(void)
Get the logger configured date format.
Definition: logger.c:2927
int ast_logger_register_level(const char *name)
Register a new logger level.
Definition: logger.c:2851
ast_callid ast_create_callid(void)
factory function to create a new uniquely identifying callid.
Definition: logger.c:2293
int ast_is_logger_initialized(void)
Test if logger is initialized.
Definition: logger.c:2175
void ast_verb_console_set(int verb_level)
Set this thread's console verbosity level.
Definition: logger.c:2691
Options provided by main asterisk program.
void ast_console_toggle_mute(int fd, int silent)
mute or unmute a console from logging
Definition: asterisk.c:1274
void ast_callid_strnprint(char *buffer, size_t buffer_size, ast_callid callid)
copy a string representation of the callid into a target string
Definition: logger.c:2288
void ast_console_puts_mutable(const char *string, int level)
log the string to the console, and all attached console clients
Definition: asterisk.c:1316
unsigned int ast_debug_get_by_module(const char *module)
Get the debug level for a module.
Definition: main/cli.c:136