Asterisk - The Open Source Telephony Project  18.5.0
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 <[email protected]>
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 
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 void ast_log_ap(int level, const char *file, int line, const char *function, const char *fmt, va_list ap)
73  __attribute__((format(printf, 5, 0)));
74 
75 /*!
76  * \brief Used for sending a log message with protection against recursion.
77  *
78  * \note This function should be used by all error messages that might be directly
79  * or indirectly caused by logging.
80  *
81  * \see ast_log for documentation on the parameters.
82  */
83 void ast_log_safe(int level, const char *file, int line, const char *function, const char *fmt, ...)
84  __attribute__((format(printf, 5, 6)));
85 
86 /* XXX needs documentation */
87 typedef unsigned int ast_callid;
88 
89 /*! \brief Used for sending a log message with a known call_id
90  This is a modified logger function which is functionally identical to the above logger function,
91  it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
92  join the log message with a call_id.
93 
94  \param level Type of log event
95  \param file Will be provided by the AST_LOG_* macro
96  \param line Will be provided by the AST_LOG_* macro
97  \param function Will be provided by the AST_LOG_* macro
98  \param callid This is the ast_callid that is associated with the log message. May be NULL.
99  \param fmt This is what is important. The format is the same as your favorite breed of printf. You know how that works, right? :-)
100 */
101 void ast_log_callid(int level, const char *file, int line, const char *function, ast_callid callid, const char *fmt, ...)
102  __attribute__((format(printf, 6, 7)));
103 
104 /*!
105  * \brief Retrieve the existing log channels
106  * \param logentry A callback to an updater function
107  * \param data Data passed into the callback for manipulation
108  *
109  * For each of the logging channels, logentry will be executed with the
110  * channel file name, log type, status of the log, and configuration levels.
111  *
112  * \retval 0 on success
113  * \retval 1 on failure
114  * \retval -2 on allocation error
115  */
116 int ast_logger_get_channels(int (*logentry)(const char *channel, const char *type,
117  const char *status, const char *configuration, void *data), void *data);
118 
119 /*!
120  * \brief Create a log channel
121  *
122  * \param log_channel Log channel to create
123  * \param components Logging config levels to add to the log channel
124  */
125 int ast_logger_create_channel(const char *log_channel, const char *components);
126 
127 /*!
128  * \brief Delete the specified log channel
129  *
130  * \param log_channel The log channel to delete
131  */
132 int ast_logger_remove_channel(const char *log_channel);
133 
134 /*!
135  * \brief Log a backtrace of the current thread's execution stack to the Asterisk log
136  */
137 void ast_log_backtrace(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_TRACE
249 #undef LOG_TRACE
250 #endif
251 #define __LOG_TRACE 1
252 #define LOG_TRACE __LOG_TRACE, _A_
253 
254 #ifdef AST_LOG_TRACE
255 #undef AST_LOG_TRACE
256 #endif
257 #define AST_LOG_TRACE __LOG_TRACE, _A_
258 
259 #ifdef LOG_NOTICE
260 #undef LOG_NOTICE
261 #endif
262 #define __LOG_NOTICE 2
263 #define LOG_NOTICE __LOG_NOTICE, _A_
264 
265 #ifdef AST_LOG_NOTICE
266 #undef AST_LOG_NOTICE
267 #endif
268 #define AST_LOG_NOTICE __LOG_NOTICE, _A_
269 
270 #ifdef LOG_WARNING
271 #undef LOG_WARNING
272 #endif
273 #define __LOG_WARNING 3
274 #define LOG_WARNING __LOG_WARNING, _A_
275 
276 #ifdef AST_LOG_WARNING
277 #undef AST_LOG_WARNING
278 #endif
279 #define AST_LOG_WARNING __LOG_WARNING, _A_
280 
281 #ifdef LOG_ERROR
282 #undef LOG_ERROR
283 #endif
284 #define __LOG_ERROR 4
285 #define LOG_ERROR __LOG_ERROR, _A_
286 
287 #ifdef AST_LOG_ERROR
288 #undef AST_LOG_ERROR
289 #endif
290 #define AST_LOG_ERROR __LOG_ERROR, _A_
291 
292 #ifdef LOG_VERBOSE
293 #undef LOG_VERBOSE
294 #endif
295 #define __LOG_VERBOSE 5
296 #define LOG_VERBOSE __LOG_VERBOSE, _A_
297 
298 #ifdef AST_LOG_VERBOSE
299 #undef AST_LOG_VERBOSE
300 #endif
301 #define AST_LOG_VERBOSE __LOG_VERBOSE, _A_
302 
303 #ifdef LOG_DTMF
304 #undef LOG_DTMF
305 #endif
306 #define __LOG_DTMF 6
307 #define LOG_DTMF __LOG_DTMF, _A_
308 
309 #ifdef AST_LOG_DTMF
310 #undef AST_LOG_DTMF
311 #endif
312 #define AST_LOG_DTMF __LOG_DTMF, _A_
313 
314 #define NUMLOGLEVELS 32
315 
316 /*!
317  * \brief Get the debug level for a module
318  * \param module the name of module
319  * \return the debug level
320  */
321 unsigned int ast_debug_get_by_module(const char *module);
322 
323 /*!
324  * \brief Register a new logger level
325  * \param name The name of the level to be registered
326  * \retval -1 if an error occurs
327  * \retval non-zero level to be used with ast_log for sending messages to this level
328  * \since 1.8
329  */
330 int ast_logger_register_level(const char *name);
331 
332 /*!
333  * \brief Checks if a dynamic logger level exists
334  * \param name The name of the dynamic level for which to check existence
335  * \retval -1 if no such dynamic level exists
336  * \retval non-zero negative to be used with ast_log_dynamic_level for sending messages to this level
337  */
338 int ast_dynamic_logger_level(const char *name);
339 
340 /*!
341  * \brief Unregister a previously registered logger level
342  * \param name The name of the level to be unregistered
343  * \return nothing
344  * \since 1.8
345  */
346 void ast_logger_unregister_level(const char *name);
347 
348 /*!
349  * \brief Get the logger configured date format
350  *
351  * \retval The date format string
352  *
353  * \since 13.0.0
354  */
355 const char *ast_logger_get_dateformat(void);
356 
357 /*!
358  * \brief factory function to create a new uniquely identifying callid.
359  *
360  * \retval The call id
361  */
362 ast_callid ast_create_callid(void);
363 
364 /*!
365  * \brief extracts the callerid from the thread
366  *
367  * \retval Non-zero Call id related to the thread
368  * \retval 0 if no call_id is present in the thread
369  */
370 ast_callid ast_read_threadstorage_callid(void);
371 
372 /*!
373  * \brief Sets what is stored in the thread storage to the given
374  * callid if it does not match what is already there.
375  *
376  * \retval 0 - success
377  * \retval non-zero - failure
378  */
379 int ast_callid_threadassoc_change(ast_callid callid);
380 
381 /*!
382  * \brief Adds a known callid to thread storage of the calling thread
383  *
384  * \retval 0 - success
385  * \retval non-zero - failure
386  */
387 int ast_callid_threadassoc_add(ast_callid callid);
388 
389 /*!
390  * \brief Removes callid from thread storage of the calling thread
391  *
392  * \retval 0 - success
393  * \retval non-zero - failure
394  */
396 
397 /*!
398  * \brief Checks thread storage for a callid and stores a reference if it exists.
399  * If not, then a new one will be created, bound to the thread, and a reference
400  * to it will be stored.
401  *
402  * \param callid pointer to store the callid
403  * \retval 0 - callid was found
404  * \retval 1 - callid was created
405  * \retval -1 - the function failed somehow (presumably memory problems)
406  */
407 int ast_callid_threadstorage_auto(ast_callid *callid);
408 
409 /*!
410  * \brief Use in conjunction with ast_callid_threadstorage_auto. Cleans up the
411  * references and if the callid was created by threadstorage_auto, unbinds
412  * the callid from the threadstorage
413  * \param callid The callid set by ast_callid_threadstorage_auto
414  * \param callid_created The integer returned through ast_callid_threadstorage_auto
415  */
416 void ast_callid_threadstorage_auto_clean(ast_callid callid, int callid_created);
417 
418 /*!
419  * \brief copy a string representation of the callid into a target string
420  *
421  * \param buffer destination of callid string (should be able to store 13 characters or more)
422  * \param buffer_size maximum writable length of the string (Less than 13 will result in truncation)
423  * \param callid Callid for which string is being requested
424  */
425 void ast_callid_strnprint(char *buffer, size_t buffer_size, ast_callid callid);
426 
427 /*!
428  * \brief Send a log message to a dynamically registered log level
429  * \param level The log level to send the message to
430  *
431  * Like ast_log, the log message may include printf-style formats, and
432  * the data for these must be provided as additional parameters after
433  * the log message.
434  *
435  * \return nothing
436  * \since 1.8
437  */
438 
439 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
440 
441 #define DEBUG_ATLEAST(level) \
442  (option_debug >= (level) \
443  || (ast_opt_dbg_module \
444  && ((int)ast_debug_get_by_module(AST_MODULE) >= (level) \
445  || (int)ast_debug_get_by_module(__FILE__) >= (level))))
446 
447 /*!
448  * \brief Log a DEBUG message
449  * \param level The minimum value of option_debug for this message
450  * to get logged
451  */
452 #define ast_debug(level, ...) \
453  do { \
454  if (DEBUG_ATLEAST(level)) { \
455  ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
456  } \
457  } while (0)
458 
459 extern int ast_verb_sys_level;
460 
461 #define VERBOSITY_ATLEAST(level) ((level) <= ast_verb_sys_level)
462 
463 #define ast_verb(level, ...) \
464  do { \
465  if (VERBOSITY_ATLEAST(level) ) { \
466  __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, __VA_ARGS__); \
467  } \
468  } while (0)
469 
470 #define ast_verb_callid(level, callid, ...) \
471  do { \
472  if (VERBOSITY_ATLEAST(level) ) { \
473  __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, callid, __VA_ARGS__); \
474  } \
475  } while (0)
476 
477 /*!
478  * \brief Re-evaluate the system max verbosity level (ast_verb_sys_level).
479  *
480  * \return Nothing
481  */
482 void ast_verb_update(void);
483 
484 /*!
485  * \brief Register this thread's console verbosity level pointer.
486  *
487  * \param level Where the verbose level value is.
488  *
489  * \return Nothing
490  */
491 void ast_verb_console_register(int *level);
492 
493 /*!
494  * \brief Unregister this thread's console verbosity level.
495  *
496  * \return Nothing
497  */
498 void ast_verb_console_unregister(void);
499 
500 /*!
501  * \brief Get this thread's console verbosity level.
502  *
503  * \retval verbosity level of the console.
504  */
505 int ast_verb_console_get(void);
506 
507 /*!
508  * \brief Set this thread's console verbosity level.
509  *
510  * \param verb_level New level to set.
511  *
512  * \return Nothing
513  */
514 void ast_verb_console_set(int verb_level);
515 
516 /*!
517  * \brief Test if logger is initialized
518  *
519  * \retval true if the logger is initialized
520  */
521 int ast_is_logger_initialized(void);
522 
523 /*!
524  * \brief Set the maximum number of messages allowed in the processing queue
525  *
526  * \param queue_limit
527  *
528  * \return Nothing
529  */
530 void ast_logger_set_queue_limit(int queue_limit);
531 
532 /*!
533  * \brief Get the maximum number of messages allowed in the processing queue
534  *
535  * \return Queue limit
536  */
538 
539 
540 /*!
541  \page Scope_Trace Scope Trace
542 
543 The Scope Trace facility allows you to instrument code and output scope entry
544 and exit messages with associated data.
545 
546 To start using it:
547  * You must have used --enable-dev-mode.
548  * In logger.conf, set a logger channel to output the "trace" level.
549  * Instrument your code as specified below.
550  * Use the cli or cli.conf to enable tracing: CLI> core set trace <trace_level> [ module ]
551 
552 Its simplest usage requires only 1 macro call that...
553  - Registers a descructor for a special variable that gets called when the
554  variable goes out of scope. Uses the same principle as RAII_VAR.
555  The destructor prints the name of the function with an "exiting" indicator
556  along with an optional message.
557  - Prints the name of the function with an "entering" indicator along with
558  an optional message.
559 
560 Simple Example:
561 The following code...
562 \code
563 static struct pjmedia_sdp_session *create_local_sdp(pjsip_inv_session *inv,
564  struct ast_sip_session *session, const pjmedia_sdp_session *offer)
565 {
566  SCOPE_TRACE(1, "%s\n", ast_sip_session_get_name(session));
567  ...
568 }
569 \endcode
570 would produce...
571 \b [2020-05-17 15:16:51 -0600] TRACE[953402] : --> res_pjsip_session.c:4283 create_local_sdp PJSIP/1173-00000001
572 \b [2020-05-17 15:16:51 -0600] TRACE[953402] : <-- res_pjsip_session.c:4283 create_local_sdp PJSIP/1173-00000001
573 
574 There is one odd bit. There's no way to capture the line number of there the scope exited
575 so it's always going to be the line where SCOPE_TRACE is located.
576 
577 Similar to RAII_VAR, any block scope can be traced including "if", "for", "while", etc.
578 \note "case" statements don't create a scope block by themselves but you can create
579 a block for it, or use the generic trace functions mentioned below.
580 
581 Scope Output and Level:
582 
583 Rather than sending trace messages to the debug facility, a new facility "trace" has been
584 added to logger. A corresponding CLI command "core set trace", and a corresponding "trace"
585 parameter in asterisk.conf were added. This allows a separate log channel to be created
586 just for storing trace messages. The levels are the same as those for debug and verbose.
587 
588 Scope Indenting:
589 
590 Each time SCOPE_TRACE or SCOPE_TRACE is called, a thread-local indent value is
591 incremented on scope enter, and decremented on scope exit. This allows output
592 like the following (timestamp omitted for brevity):
593 
594 TRACE[953402] : --> res_pjsip_session.c:3940 session_inv_on_tsx_state_changed PJSIP/1173-00000001 TSX State: Proceeding Inv State: CALLING
595 TRACE[953402] : --> res_pjsip_session.c:3680 handle_incoming PJSIP/1173-00000001
596 TRACE[953402] : --> res_pjsip_session.c:3661 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
597 TRACE[953402] : --> res_pjsip_session.c:3669 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Supplement: chan_pjsip
598 TRACE[953402] : --> chan_pjsip.c:3265 chan_pjsip_incoming_response_after_media PJSIP/1173-00000001 Method: INVITE Status: 100 After Media
599 TRACE[953402] : --> chan_pjsip.c:3194 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
600 TRACE[953402] : chan_pjsip.c:3245 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Ignored
601 TRACE[953402] : <-- chan_pjsip.c:3194 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
602 TRACE[953402] : <-- chan_pjsip.c:3265 chan_pjsip_incoming_response_after_media PJSIP/1173-00000001 Method: INVITE Status: 100 After Media
603 TRACE[953402] : <-- res_pjsip_session.c:3669 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Supplement: chan_pjsip
604 TRACE[953402] : <-- res_pjsip_session.c:3661 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
605 TRACE[953402] : <-- res_pjsip_session.c:3680 handle_incoming PJSIP/1173-00000001
606 TRACE[953402] : <-- res_pjsip_session.c:3940 session_inv_on_tsx_state_changed PJSIP/1173-00000001 TSX State: Proceeding Inv State: CALLING
607 
608 \note The trace level indicates which messages to print and has no effect on indent.
609 
610 Generic Trace Messages:
611 
612 Sometimes you may just want to print a message to the trace log with the appropriate indent
613 such as when executing a "case" clause in a "switch" statement. For example, the deepest
614 message in the sample output above (chan_pjsip.c:3245) is just a single message instead of
615 an entry/exit message. To do so, you can use the ast_trace macros...
616 \code
617  ast_trace(1, "%s Method: %.*s Status: %d Ignored\n", ast_sip_session_get_name(session),
618  (int)rdata->msg_info.cseq->method.name.slen, rdata->msg_info.cseq->method.name.ptr, status.code);
619 \endcode
620 
621 /note Final note: The trace facility, like debug, is only available when AST_DEVMODE is defined.
622 
623  */
624 
625 /*!
626  * \brief Get the trace level for a module
627  * \param module the name of module
628  * \return the trace level
629  */
630 unsigned int ast_trace_get_by_module(const char *module);
631 
632 /*!
633  * \brief load logger.conf configuration for console socket connections
634  */
636 
637 #define TRACE_ATLEAST(level) \
638  (option_trace >= (level) \
639  || (ast_opt_trace_module \
640  && ((int)ast_trace_get_by_module(AST_MODULE) >= (level) \
641  || (int)ast_trace_get_by_module(__FILE__) >= (level))))
642 
643 /*!
644  * \brief Controls if and when indenting is applied.
645  */
647  /*! Use the existing indent level */
649  /*! Increment the indent before printing the message */
651  /*! Increment the indent after printing the message */
653  /*! Decrement the indent before printing the message */
655  /*! Decrement the indent after printing the message */
657  /*! Set the indent to the one provided */
659  /*! Don't use or alter the level */
661 };
662 
663 #ifdef AST_DEVMODE
664 
665 void __attribute__((format (printf, 6, 7))) __ast_trace(const char *file, int line, const char *func,
666  enum ast_trace_indent_type indent_type, unsigned long indent, const char* format, ...);
667 
668 /*!
669  * \brief Print a trace message
670  *
671  * \param level The trace level
672  * \param indent_type One of the \ref ast_trace_indent_type values
673  * \param (optional) A printf style format string
674  * \param (optional) Arguments
675  *
676  */
677 #define ast_trace_raw(level, indent_type, ...) \
678  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__); \
679  if (TRACE_ATLEAST(level < 0 ? __scope_level : level)) { \
680  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, indent_type, 0, " " __VA_ARGS__); \
681  }
682 
683 /*!
684  * \brief Print a basic trace message
685  *
686  * \param level The trace level
687  * \param (optional) A printf style format string
688  * \param (optional) Arguments
689  *
690  * This will print the file, line and function at the current indent level
691  */
692 #define ast_trace(level, ...) \
693  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__); \
694  if (TRACE_ATLEAST(level < 0 ? __scope_level : level)) { \
695  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_SAME, 0, " " __VA_ARGS__); \
696  }
697 
698 /*!
699  * \brief Get the current indent level
700  *
701  * \returns The current indent level
702  */
703 unsigned long _ast_trace_get_indent(void);
704 #define ast_trace_get_indent() _ast_trace_get_indent()
705 
706 /*!
707  * \brief Set the current indent level
708  *
709  * \param indent The new indent level
710  */
711 void _ast_trace_set_indent(unsigned long indent);
712 #define ast_trace_set_indent(indent) _ast_trace_set_indent(indent)
713 
714 /*!
715  * \brief Increment the indent level
716  *
717  * \returns The new indent level
718  */
719 unsigned long _ast_trace_inc_indent(void);
720 #define ast_trace_inc_indent() _ast_trace_inc_indent()
721 
722 /*!
723  * \brief Decrement the indent level
724  *
725  * \returns The new indent level
726  */
727 unsigned long _ast_trace_dec_indent(void);
728 #define ast_trace_dec_indent() _ast_trace_dec_indent()
729 
730 /*!
731  * \brief Print a trace message with details when a scope is entered or existed.
732  *
733  * \param level The trace level
734  * \param (optional) A printf style format string
735  * \param (optional) Arguments
736  *
737  * This will print the file, line and function plus details at the current indent level.
738  * \note Like RAII_VAR, this macro must be called before any code in the scope.
739  *
740  * \note The variables used to detect scope change will look like
741  * __scopevar1234__EXIT and __scopevar1234__ENTER.
742  * The ENTER variable and function are needed to prevent mixed code and declaration issues.
743  * If we simple called __ast_trace, then this macro would need to be the last line
744  * of scope variable declaration. The following would fail.
745  *
746  * SCOPE_TRACE(1, "Help!\n");
747  * int i;
748  */
749 #define SCOPE_TRACE(level, ...) \
750  const char *__trace_funcname = __PRETTY_FUNCTION__; \
751  auto void __scopevar ## __LINE__ ## __EXIT(void * v); \
752  void __scopevar ## __LINE__ ## __EXIT(void * v __attribute__((unused))) { \
753  if (TRACE_ATLEAST(level)) { \
754  __ast_trace(__FILE__, __LINE__, __trace_funcname, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
755  } \
756  } \
757  void *__scopevar ## __LINE__ ## __TRACER __attribute__((cleanup(__scopevar ## __LINE__ ## __EXIT))) = (void *) __PRETTY_FUNCTION__ ; \
758  auto int __scopevar ## __LINE__ ## __ENTER(void); \
759  int __scopevar ## __LINE__ ## __ENTER(void) { \
760  if (TRACE_ATLEAST(level)) { \
761  __ast_trace(__FILE__, __LINE__, __trace_funcname, AST_TRACE_INDENT_INC_AFTER, 0, " " __VA_ARGS__); \
762  } \
763  return 0; \
764  } \
765  int __scopevar ## __LINE__ ## __RETURN __attribute__((unused)) = __scopevar ## __LINE__ ## __ENTER()
766 
767 /*!
768  * \brief Non RAII_VAR Scope Trace macros
769  * The advantage of these macros is that the EXITs will have the actual
770  * line number where the scope exited. Much less code is required as well.
771  */
772 
773 /*!
774  * \brief Scope Enter
775  *
776  * \param level The trace level
777  * \param (optional) A printf style format string
778  * \param (optional) Arguments
779  */
780 #define SCOPE_ENTER(level, ...) \
781  int __scope_level = level; \
782  int __scope_task = 0; \
783  ast_debug(__scope_level, " " __VA_ARGS__); \
784  if (TRACE_ATLEAST(level)) { \
785  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_INC_AFTER, 0, " " __VA_ARGS__); \
786  } \
787 
788 #define SCOPE_ENTER_TASK(level, indent, ...) \
789  int __scope_level = level; \
790  int __scope_task = 1; \
791  ast_debug(__scope_level, " " __VA_ARGS__); \
792  if (TRACE_ATLEAST(level)) { \
793  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_PROVIDED, indent, " " __VA_ARGS__); \
794  } \
795 
796 /*!
797  * \brief Scope Exit
798  *
799  * \param (optional) A printf style format string
800  * \param (optional) Arguments
801  *
802  * \details
803  * This macro can be used at the exit points of a statement block since it just prints the message.
804  */
805 #define SCOPE_EXIT(...) \
806  ast_debug(__scope_level, " " __VA_ARGS__); \
807  if (TRACE_ATLEAST(__scope_level)) { \
808  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
809  if (__scope_task) { \
810  _ast_trace_set_indent(0); \
811  } \
812  } \
813 
814 /*!
815  * \brief Scope Exit with expression
816  *
817  * \param __expr An expression to execute after printing the message
818  * \param (optional) A printf style format string
819  * \param (optional) Arguments
820  *
821  * \details
822  * Handy for getting out of or continuing loops.
823  *
824  * \example
825  * while(something) {
826  * SCOPE_ENTER(2, "In a while\n");
827  * if (something) {
828  * SCOPE_EXIT_EXPR(break, "Somethiung broke me\n");
829  * } else {
830  * SCOPE_EXIT_EXPR(contniue, "Somethiung continued me\n");
831  * }
832  * }
833  */
834 #define SCOPE_EXIT_EXPR(__expr, ...) \
835  ast_debug(__scope_level, " " __VA_ARGS__); \
836  if (TRACE_ATLEAST(__scope_level)) { \
837  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
838  if (__scope_task) { \
839  _ast_trace_set_indent(0); \
840  } \
841  } \
842  __expr
843 
844 /*!
845  * \brief Scope Exit with return
846  *
847  * \param (optional) A printf style format string
848  * \param (optional) Arguments
849  *
850  * \details
851  * This macro can be used at the exit points of a function when no value
852  * needs to be returned.
853  */
854 #define SCOPE_EXIT_RTN(...) \
855  ast_debug(__scope_level, " " __VA_ARGS__); \
856  if (TRACE_ATLEAST(__scope_level)) { \
857  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
858  if (__scope_task) { \
859  _ast_trace_set_indent(0); \
860  } \
861  } \
862  return
863 
864 /*!
865  * \brief Scope Exit with return value
866  *
867  * \param __return_value The return value
868  * \param (optional) A printf style format string
869  * \param (optional) Arguments
870  *
871  * \details
872  * This macro can be used at the exit points of a function when a value
873  * needs to be returned.
874  */
875 #define SCOPE_EXIT_RTN_VALUE(__return_value, ...) \
876  ast_debug(__scope_level, " " __VA_ARGS__); \
877  if (TRACE_ATLEAST(__scope_level)) { \
878  __ast_trace(__FILE__, __LINE__, __PRETTY_FUNCTION__, AST_TRACE_INDENT_DEC_BEFORE, 0, " " __VA_ARGS__); \
879  if (__scope_task) { \
880  _ast_trace_set_indent(0); \
881  } \
882  } \
883  return(__return_value)
884 
885 #else /* AST_DEVMODE */
886 #define ast_trace_raw(level, indent_type, ...) \
887  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__)
888 
889 #define ast_trace(level, ...) \
890  ast_debug(level < 0 ? __scope_level : level, " " __VA_ARGS__)
891 
892 #define ast_trace_get_indent() (0)
893 #define ast_trace_set_indent(indent)
894 #define ast_trace_inc_indent()
895 #define ast_trace_dec_indent()
896 #define SCOPE_TRACE(__level, ...)
897 
898 #define SCOPE_ENTER(level, ...) \
899  int __scope_level = level; \
900  ast_debug(level, " " __VA_ARGS__)
901 
902 #define SCOPE_ENTER_TASK(level, indent, ...) \
903  int __scope_level = level; \
904  ast_debug(level, " " __VA_ARGS__)
905 
906 #define SCOPE_EXIT(...) \
907  ast_debug(__scope_level, " " __VA_ARGS__)
908 
909 #define SCOPE_EXIT_EXPR(__expr, ...) \
910  ast_debug(__scope_level, " " __VA_ARGS__); \
911  __expr
912 
913 #define SCOPE_EXIT_RTN(...) \
914  ast_debug(__scope_level, " " __VA_ARGS__); \
915  return
916 
917 #define SCOPE_EXIT_RTN_VALUE(__return_value, ...) \
918  ast_debug(__scope_level, " " __VA_ARGS__); \
919  return __return_value
920 
921 #endif /* AST_DEVMODE */
922 
923 /*!
924  * The following macros will print log messages before running
925  * the associated SCOPE_ macro.
926  */
927 
928 #define SCOPE_EXIT_LOG(__log_level, ...) \
929 ({ \
930  ast_log(__log_level, " " __VA_ARGS__); \
931  SCOPE_EXIT(" " __VA_ARGS__); \
932 })
933 
934 #define SCOPE_EXIT_LOG_RTN(__log_level, ...) \
935 ({ \
936  ast_log(__log_level, " " __VA_ARGS__); \
937  SCOPE_EXIT_RTN(" " __VA_ARGS__); \
938 })
939 
940 #define SCOPE_EXIT_LOG_RTN_VALUE(__value, __log_level, ...) \
941 ({ \
942  ast_log(__log_level, " " __VA_ARGS__); \
943  SCOPE_EXIT_RTN_VALUE(__value, " " __VA_ARGS__); \
944 })
945 
946 #define SCOPE_EXIT_LOG_EXPR(__expr, __log_level, ...) \
947 ({ \
948  ast_log(__log_level, " " __VA_ARGS__); \
949  SCOPE_EXIT_EXPR(__expr, " " __VA_ARGS__); \
950 })
951 
952 #define ast_trace_log(__level, __log_level, ...) \
953 ({ \
954  ast_log(__log_level, " " __VA_ARGS__); \
955  ast_trace(__level < 0 ? __scope_level : __level, " " __VA_ARGS__); \
956 })
957 
958 
959 #if defined(__cplusplus) || defined(c_plusplus)
960 }
961 #endif
962 
963 #endif /* _ASTERISK_LOGGER_H */
void ast_console_puts(const char *string)
write the string to the root console, and all attached network console clients
Definition: asterisk.c:1314
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
static const char type[]
Definition: chan_ooh323.c:109
ast_logger_results
Definition: logger.h:48
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:1281
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:2149
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:1336
unsigned long _ast_trace_dec_indent(void)
Decrement the indent level.
Definition: logger.c:2396
int ast_verb_console_get(void)
Get this thread&#39;s console verbosity level.
Definition: logger.c:2323
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:2042
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:1971
const char * ast_logger_get_dateformat(void)
Get the logger configured date format.
Definition: logger.c:2577
int ast_logger_rotate_channel(const char *log_channel)
Rotate the specified log channel.
Definition: logger.c:1259
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:2198
void ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt,...)
Definition: logger.c:894
int ast_logger_rotate(void)
Reload logger while rotating log files.
Definition: logger.c:1254
Definition: astman.c:222
unsigned long _ast_trace_inc_indent(void)
Increment the indent level.
Definition: logger.c:2387
unsigned int ast_callid
Definition: logger.h:87
Definition: muted.c:95
void ast_init_logger_for_socket_console(void)
load logger.conf configuration for console socket connections
Definition: logger.c:684
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:1209
void ast_console_toggle_mute(int fd, int silent)
mute or unmute a console from logging
Definition: asterisk.c:1232
int ast_callid_threadassoc_remove(void)
Removes callid from thread storage of the calling thread.
Definition: logger.c:2003
ast_callid ast_read_threadstorage_callid(void)
extracts the callerid from the thread
Definition: logger.c:1962
void ast_log_backtrace(void)
Log a backtrace of the current thread&#39;s execution stack to the Asterisk log.
Definition: logger.c:2158
void ast_verb_console_register(int *level)
Register this thread&#39;s console verbosity level pointer.
Definition: logger.c:2296
void ast_child_verbose(int level, const char *fmt,...)
Definition: logger.c:850
int ast_callid_threadassoc_add(ast_callid callid)
Adds a known callid to thread storage of the calling thread.
Definition: logger.c:1984
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:2210
void ast_logger_unregister_level(const char *name)
Unregister a previously registered logger level.
Definition: logger.c:2536
ast_trace_indent_type
Controls if and when indenting is applied.
Definition: logger.h:646
int ast_register_verbose(void(*verboser)(const char *string)) attribute_warn_unused_result
unsigned int ast_trace_get_by_module(const char *module)
Get the trace level for a module.
Definition: main/cli.c:153
void ast_logger_set_queue_limit(int queue_limit)
Set the maximum number of messages allowed in the processing queue.
Definition: logger.c:2582
int ast_logger_register_level(const char *name)
Register a new logger level.
Definition: logger.c:2503
int ast_logger_create_channel(const char *log_channel, const char *components)
Create a log channel.
Definition: logger.c:1419
int ast_verb_sys_level
Definition: options.c:64
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:2123
ast_callid ast_create_callid(void)
factory function to create a new uniquely identifying callid.
Definition: logger.c:1957
int ast_logger_get_queue_limit(void)
Get the maximum number of messages allowed in the processing queue.
Definition: logger.c:2587
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:1952
void ast_verb_console_unregister(void)
Unregister this thread&#39;s console verbosity level.
Definition: logger.c:2312
int ast_is_logger_initialized(void)
Test if logger is initialized.
Definition: logger.c:1841
unsigned long _ast_trace_get_indent(void)
Get the current indent level.
Definition: logger.c:2377
int ast_logger_remove_channel(const char *log_channel)
Delete the specified log channel.
Definition: logger.c:1485
static const char name[]
Definition: cdr_mysql.c:74
int ast_dynamic_logger_level(const char *name)
Checks if a dynamic logger level exists.
Definition: logger.c:2514
#define attribute_warn_unused_result
Definition: compiler.h:71
void __ast_verbose_ap(const char *file, int line, const char *func, int level, ast_callid callid, const char *fmt, va_list ap)
Definition: logger.c:2193
void ast_console_puts_mutable(const char *string, int level)
log the string to the console, and all attached console clients
Definition: asterisk.c:1274
void ast_verb_update(void)
Re-evaluate the system max verbosity level (ast_verb_sys_level).
Definition: logger.c:2232
void _ast_trace_set_indent(unsigned long indent)
Set the current indent level.
Definition: logger.c:2382
void ast_verb_console_set(int verb_level)
Set this thread&#39;s console verbosity level.
Definition: logger.c:2341
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:2020
Options provided by main asterisk program.
unsigned int ast_debug_get_by_module(const char *module)
Get the debug level for a module.
Definition: main/cli.c:136
int ast_unregister_verbose(void(*verboser)(const char *string)) attribute_warn_unused_result
static snd_pcm_format_t format
Definition: chan_alsa.c:102
void ast_log_ap(int level, const char *file, int line, const char *function, const char *fmt, va_list ap)
Definition: logger.c:2110
jack_status_t status
Definition: app_jack.c:146
void __ast_trace(const char *file, int line, const char *func, enum ast_trace_indent_type indent_type, unsigned long indent, const char *format,...)
Definition: logger.c:2405