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