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