Asterisk - The Open Source Telephony Project GIT-master-85241bd
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)
32extern "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
78void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
79 __attribute__((format(printf, 5, 6)));
80
81void 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 */
92void 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 */
96typedef 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*/
110void 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 */
125int 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 */
134int 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 */
141int 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 */
146void ast_log_backtrace(void);
147
148/*! \brief Reload logger while rotating log files */
149int ast_logger_rotate(void);
150
151/*!
152 * \brief Rotate the specified log channel.
153 *
154 * \param log_channel The log channel to rotate
155 */
156int ast_logger_rotate_channel(const char *log_channel);
157
158void __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 */
174void __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 */
184void __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
189void __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
191void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
192
193int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
194int 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
204void 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 */
214void 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 */
224void ast_console_puts_mutable_full(const char *message, int level, int sublevel);
225
226void 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 */
234void 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 */
328unsigned 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 */
337int 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 */
345int 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 */
352void 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 */
361const 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 */
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 */
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 */
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 */
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 */
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 */
422void 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 */
431void 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
464extern 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 */
485void 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 */
492void ast_verb_console_register(int *level);
493
494/*!
495 * \brief Unregister this thread's console verbosity level.
496 */
498
499/*!
500 * \brief Get this thread's console verbosity level.
501 *
502 * \return verbosity level of the console.
503 */
504int 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 */
511void 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 */
519
520/*!
521 * \brief Set the maximum number of messages allowed in the processing queue
522 *
523 * \param queue_limit
524 */
525void 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
539The Scope Trace facility allows you to instrument code and output scope entry
540and exit messages with associated data.
541\par
542To 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
549Its 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
557Simple Example:
558The following code...
559\code
560static 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
567would 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
573There is one odd bit. There's no way to capture the line number of there the scope exited
574so it's always going to be the line where SCOPE_TRACE is located.
575\par
576Similar 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
578a block for it, or use the generic trace functions mentioned below.
579
580\par Scope Output and Level:
581Rather than sending trace messages to the debug facility, a new facility "trace" has been
582added to logger. A corresponding CLI command "core set trace", and a corresponding "trace"
583parameter in asterisk.conf were added. This allows a separate log channel to be created
584just for storing trace messages. The levels are the same as those for debug and verbose.
585
586\par Scope Indenting:
587Each time SCOPE_TRACE or SCOPE_TRACE is called, a thread-local indent value is
588incremented on scope enter, and decremented on scope exit. This allows output
589like the following (timestamp omitted for brevity):
590\verbatim
591TRACE[953402] : --> res_pjsip_session.c:3940 session_inv_on_tsx_state_changed PJSIP/1173-00000001 TSX State: Proceeding Inv State: CALLING
592TRACE[953402] : --> res_pjsip_session.c:3680 handle_incoming PJSIP/1173-00000001
593TRACE[953402] : --> res_pjsip_session.c:3661 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
594TRACE[953402] : --> res_pjsip_session.c:3669 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Supplement: chan_pjsip
595TRACE[953402] : --> chan_pjsip.c:3265 chan_pjsip_incoming_response_after_media PJSIP/1173-00000001 Method: INVITE Status: 100 After Media
596TRACE[953402] : --> chan_pjsip.c:3194 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
597TRACE[953402] : chan_pjsip.c:3245 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Ignored
598TRACE[953402] : <-- chan_pjsip.c:3194 chan_pjsip_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
599TRACE[953402] : <-- chan_pjsip.c:3265 chan_pjsip_incoming_response_after_media PJSIP/1173-00000001 Method: INVITE Status: 100 After Media
600TRACE[953402] : <-- res_pjsip_session.c:3669 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100 Supplement: chan_pjsip
601TRACE[953402] : <-- res_pjsip_session.c:3661 handle_incoming_response PJSIP/1173-00000001 Method: INVITE Status: 100
602TRACE[953402] : <-- res_pjsip_session.c:3680 handle_incoming PJSIP/1173-00000001
603TRACE[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:
608Sometimes you may just want to print a message to the trace log with the appropriate indent
609such as when executing a "case" clause in a "switch" statement. For example, the deepest
610message in the sample output above (chan_pjsip.c:3245) is just a single message instead of
611an 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
623The default prefix to each log and trace line is
624<tt>"filename:line function"</tt> which is defined in the
625macro \c _A_ at the top of this file:
626\code
627#define _A_ __FILE__, __LINE__, __FUNCTION__
628\endcode
629They become 3 arguments to the __ast_trace function
630and most of the ast_log* functions. For scope tracing,
631that may be unnecessary clutter in the trace output so
632you can now customise that with the \c _TRACE_PREFIX_
633macro. Like \c _A_, it MUST resolve to 3 arguments:
634\verbatim
635const char *, int, const char *
636\endverbatim
637so the minimum would be:
638\code
639#define _TRACE_PREFIX_ "",0,""
640\endcode
641Normally you should define \c _TRACE_PREFIX_ in your source
642file before including logger.h.
643\code
644#define _TRACE_PREFIX_ "", __LINE__, ""
645#include "asterisk/logger.h"
646\endcode
647You can also define it later in your source file
648but because logger.h sets it to a default value, you'll
649have to undefine it first, then define it your your liking.
650If you want to go back to the default, you'll have to
651undefine 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
661defining \c _TRACE_PREFIX_ in one source file does NOT
662make it apply to any others. So if you define it
663in source file A, then call a function in source
664file B, the trace output from B will display based
665on 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 */
678unsigned 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
713void __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 */
749unsigned 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 */
757void _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 */
765unsigned 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 */
773unsigned 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
8551 app_voicemail_odbc.c:7161 leave_voicemail: --> Calling store_file
8561 --> app_voicemail_odbc.c:4483 store_file: dir: /var/spool/asterisk/voicemail/default/1179/INBOX user: 1179 context: default msgnum: 8
8572 app_voicemail_odbc.c:4502 store_file: Formats: wav49|gsm|wav Using format: 'WAV'
8582 app_voicemail_odbc.c:4510 store_file: Base path: '/var/spool/asterisk/voicemail/default/1179/INBOX/msg0008'
8592 app_voicemail_odbc.c:4513 store_file: Basename: 'msg0008'
8601 <-- app_voicemail_odbc.c:4597 store_file: Success
8611 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
8881 app_voicemail_odbc.c:7161 leave_voicemail: --> Calling store_file
8891 --> app_voicemail_odbc.c:4483 store_file: dir: /var/spool/asterisk/voicemail/default/1179/INBOX user: 1179 context: default msgnum: 8
8902 app_voicemail_odbc.c:4502 store_file: Formats: wav49|gsm|wav Using format: 'WAV'
8912 app_voicemail_odbc.c:4510 store_file: Base path: '/var/spool/asterisk/voicemail/default/1179/INBOX/msg0008'
8922 app_voicemail_odbc.c:4513 store_file: Basename: 'msg0008'
8931 <-- app_voicemail_odbc.c:4597 store_file: Success
8941 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_EXIT(...) \
1024 ast_debug(__scope_level, " " __VA_ARGS__)
1025
1026#define SCOPE_EXIT_EXPR(__expr, ...) \
1027 ast_debug(__scope_level, " " __VA_ARGS__); \
1028 __expr
1029
1030#define SCOPE_EXIT_RTN(...) \
1031 ast_debug(__scope_level, " " __VA_ARGS__); \
1032 return
1033
1034#define SCOPE_EXIT_RTN_VALUE(__return_value, ...) \
1035 ast_debug(__scope_level, " " __VA_ARGS__); \
1036 return __return_value
1037
1038#endif /* AST_DEVMODE */
1039
1040/*!
1041 * The following macros will print log messages before running
1042 * the associated SCOPE_ macro.
1043 */
1044
1045#define SCOPE_EXIT_LOG(__log_level, ...) \
1046({ \
1047 ast_log(__log_level, " " __VA_ARGS__); \
1048 SCOPE_EXIT(" " __VA_ARGS__); \
1049})
1050
1051#define SCOPE_EXIT_LOG_RTN(__log_level, ...) \
1052({ \
1053 ast_log(__log_level, " " __VA_ARGS__); \
1054 SCOPE_EXIT_RTN(" " __VA_ARGS__); \
1055})
1056
1057#define SCOPE_EXIT_LOG_RTN_VALUE(__value, __log_level, ...) \
1058({ \
1059 ast_log(__log_level, " " __VA_ARGS__); \
1060 SCOPE_EXIT_RTN_VALUE(__value, " " __VA_ARGS__); \
1061})
1062
1063#define SCOPE_EXIT_LOG_EXPR(__expr, __log_level, ...) \
1064({ \
1065 ast_log(__log_level, " " __VA_ARGS__); \
1066 SCOPE_EXIT_EXPR(__expr, " " __VA_ARGS__); \
1067})
1068
1069#define ast_trace_log(__level, __log_level, ...) \
1070({ \
1071 ast_log(__log_level, " " __VA_ARGS__); \
1072 ast_trace(__level < 0 ? __scope_level : __level, " " __VA_ARGS__); \
1073})
1074
1075
1076#if defined(__cplusplus) || defined(c_plusplus)
1077}
1078#endif
1079
1080/*!
1081 * @}
1082 */
1083
1084#endif /* _ASTERISK_LOGGER_H */
jack_status_t status
Definition: app_jack.c:146
static const char type[]
Definition: chan_ooh323.c:109
#define attribute_warn_unused_result
Definition: compiler.h:71
static const char name[]
Definition: format_mp3.c:68
void ast_init_logger_for_socket_console(void)
load logger.conf configuration for console socket connections
Definition: logger.c:713
unsigned int ast_trace_get_by_module(const char *module)
Get the trace level for a module.
Definition: main/cli.c:153
ast_trace_indent_type
Controls if and when indenting is applied.
@ AST_TRACE_INDENT_INC_BEFORE
@ AST_TRACE_INDENT_SAME
@ AST_TRACE_INDENT_PROVIDED
@ AST_TRACE_INDENT_NONE
@ AST_TRACE_INDENT_INC_AFTER
@ AST_TRACE_INDENT_DEC_BEFORE
@ AST_TRACE_INDENT_DEC_AFTER
int ast_verb_sys_level
Definition: options.c:64
int ast_logger_get_dynamic_level(const char *name)
Retrieve dynamic logging level id.
Definition: logger.c:2880
int ast_logger_get_queue_limit(void)
Get the maximum number of messages allowed in the processing queue.
Definition: logger.c:2937
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:2545
int ast_logger_rotate_channel(const char *log_channel)
Rotate the specified log channel.
Definition: logger.c:1332
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
int ast_logger_rotate(void)
Reload logger while rotating log files.
Definition: logger.c:1327
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_verb_console_unregister(void)
Unregister this thread's console verbosity level.
Definition: logger.c:2662
int ast_logger_create_channel(const char *log_channel, const char *components)
Create a log channel.
Definition: logger.c:1521
void ast_verb_console_register(int *level)
Register this thread's console verbosity level pointer.
Definition: logger.c:2646
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
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_logger_remove_channel(const char *log_channel)
Delete the specified log channel.
Definition: logger.c:1587
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
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:1247
int ast_is_logger_initialized(void)
Test if logger is initialized.
Definition: logger.c:2175
void ast_console_toggle_mute(int fd, int silent)
mute or unmute a console from logging
Definition: asterisk.c:1270
ast_callid ast_read_threadstorage_callid(void)
extracts the callerid from the thread
Definition: logger.c:2298
int ast_callid_threadassoc_add(ast_callid callid)
Adds a known callid to thread storage of the calling thread.
Definition: logger.c:2320
void ast_console_puts_mutable(const char *string, int level)
log the string to the console, and all attached console clients
Definition: asterisk.c:1312
ast_callid ast_create_callid(void)
factory function to create a new uniquely identifying callid.
Definition: logger.c:2293
unsigned int ast_callid
void ast_console_puts(const char *string)
write the string to the root console, and all attached network console clients
Definition: asterisk.c:1352
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
void ast_log_ap(int level, const char *file, int line, const char *function, const char *fmt, va_list ap)
Definition: logger.c:2462
int ast_register_verbose(void(*verboser)(const char *string)) attribute_warn_unused_result
int ast_callid_threadassoc_remove(void)
Removes callid from thread storage of the calling thread.
Definition: logger.c:2339
void ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt,...)
Definition: logger.c:965
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
@ AST_LOGGER_DECLINE
@ AST_LOGGER_FAILURE
@ AST_LOGGER_SUCCESS
@ AST_LOGGER_ALLOC_ERROR
int ast_logger_register_level(const char *name)
Register a new logger level.
Definition: logger.c:2851
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_update(void)
Re-evaluate the system max verbosity level (ast_verb_sys_level).
Definition: logger.c:2584
void ast_child_verbose(int level, const char *fmt,...)
Definition: logger.c:921
int ast_unregister_verbose(void(*verboser)(const char *string)) attribute_warn_unused_result
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_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_verb_console_get(void)
Get this thread's console verbosity level.
Definition: logger.c:2673
const char * ast_logger_get_dateformat(void)
Get the logger configured date format.
Definition: logger.c:2927
void ast_logger_unregister_level(const char *name)
Unregister a previously registered logger level.
Definition: logger.c:2909
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:1319
unsigned int ast_debug_get_by_module(const char *module)
Get the debug level for a module.
Definition: main/cli.c:136
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_verb_console_set(int verb_level)
Set this thread's console verbosity level.
Definition: logger.c:2691
Options provided by main asterisk program.
Definition: astman.c:222