Introducing the log message unique call identifiers feature
[asterisk/asterisk.git] / include / asterisk / logger.h
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 logger.h
21   \brief Support for logging to various files, console and syslog
22         Configuration in file logger.conf
23 */
24
25 #ifndef _ASTERISK_LOGGER_H
26 #define _ASTERISK_LOGGER_H
27
28 #include "asterisk/options.h"   /* need option_debug */
29
30 #if defined(__cplusplus) || defined(c_plusplus)
31 extern "C" {
32 #endif
33
34 #define EVENTLOG "event_log"
35 #define QUEUELOG        "queue_log"
36
37 #define DEBUG_M(a) { \
38         a; \
39 }
40
41 #define VERBOSE_PREFIX_1 " "
42 #define VERBOSE_PREFIX_2 "  == "
43 #define VERBOSE_PREFIX_3 "    -- "
44 #define VERBOSE_PREFIX_4 "       > "
45
46 /*! \brief Used for sending a log message
47         This is the standard logger function.  Probably the only way you will invoke it would be something like this:
48         ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
49         where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
50         on which log you wish to output to. These are implemented as macros, that
51         will provide the function with the needed arguments.
52
53         \param level    Type of log event
54         \param file     Will be provided by the AST_LOG_* macro
55         \param line     Will be provided by the AST_LOG_* macro
56         \param function Will be provided by the AST_LOG_* macro
57         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
58  */
59
60 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
61         __attribute__((format(printf, 5, 6)));
62
63 /* XXX needs documentation */
64 struct ast_callid;
65
66 /*! \brief Used for sending a log message with a known call_id
67         This is a modified logger function which is functionally identical to the above logger function,
68         it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
69         join the log message with a call_id.
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 callid   This is the ast_callid that is associated with the log message. May be NULL.
76         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
77 */
78 void ast_log_callid(int level, const char *file, int line, const char *function, struct ast_callid *callid, const char *fmt, ...)
79         __attribute__((format(printf, 6, 7)));
80
81 void ast_backtrace(void);
82
83 /*! \brief Reload logger without rotating log files */
84 int logger_reload(void);
85
86 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
87
88 /*! Send a verbose message (based on verbose level)
89  *      \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
90  *      ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
91  *      This will print the message to the console if the verbose level is set to a level >= 3
92  *      Note the absence of a comma after the VERBOSE_PREFIX_3.  This is important.
93  *      VERBOSE_PREFIX_1 through VERBOSE_PREFIX_4 are defined.
94  *  \version 11 added level parameter
95  */
96 void __attribute__((format(printf, 5, 6))) __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt, ...);
97
98 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, __VA_ARGS__)
99
100 void __attribute__((format(printf, 5, 0))) __ast_verbose_ap(const char *file, int line, const char *func, int level, const char *fmt, va_list ap);
101
102 #define ast_verbose_ap(fmt, ap) __ast_verbose_ap(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, fmt, ap)
103
104 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
105
106 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
107 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
108
109 void ast_console_puts(const char *string);
110
111 /*!
112  * \brief log the string to the console, and all attached
113  * console clients
114  * \version 1.6.1 added level parameter
115  */
116 void ast_console_puts_mutable(const char *string, int level);
117 void ast_console_toggle_mute(int fd, int silent);
118
119 /*!
120  * \brief enables or disables logging of a specified level to the console
121  * fd specifies the index of the console receiving the level change
122  * level specifies the index of the logging level being toggled
123  * state indicates whether logging will be on or off (0 for off, 1 for on)
124  */
125 void ast_console_toggle_loglevel(int fd, int level, int state);
126
127 /* Note: The AST_LOG_* macros below are the same as
128  * the LOG_* macros and are intended to eventually replace
129  * the LOG_* macros to avoid name collisions with the syslog(3)
130  * log levels. However, please do NOT remove
131  * the LOG_* macros from the source since these may be still
132  * needed for third-party modules
133  */
134
135 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
136
137 #ifdef LOG_DEBUG
138 #undef LOG_DEBUG
139 #endif
140 #define __LOG_DEBUG    0
141 #define LOG_DEBUG      __LOG_DEBUG, _A_
142
143 #ifdef AST_LOG_DEBUG
144 #undef AST_LOG_DEBUG
145 #endif
146 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
147
148 #ifdef LOG_NOTICE
149 #undef LOG_NOTICE
150 #endif
151 #define __LOG_NOTICE   2
152 #define LOG_NOTICE     __LOG_NOTICE, _A_
153
154 #ifdef AST_LOG_NOTICE
155 #undef AST_LOG_NOTICE
156 #endif
157 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
158
159 #ifdef LOG_WARNING
160 #undef LOG_WARNING
161 #endif
162 #define __LOG_WARNING  3
163 #define LOG_WARNING    __LOG_WARNING, _A_
164
165 #ifdef AST_LOG_WARNING
166 #undef AST_LOG_WARNING
167 #endif
168 #define AST_LOG_WARNING    __LOG_WARNING, _A_
169
170 #ifdef LOG_ERROR
171 #undef LOG_ERROR
172 #endif
173 #define __LOG_ERROR    4
174 #define LOG_ERROR      __LOG_ERROR, _A_
175
176 #ifdef AST_LOG_ERROR
177 #undef AST_LOG_ERROR
178 #endif
179 #define AST_LOG_ERROR      __LOG_ERROR, _A_
180
181 #ifdef LOG_VERBOSE
182 #undef LOG_VERBOSE
183 #endif
184 #define __LOG_VERBOSE  5
185 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
186
187 #ifdef AST_LOG_VERBOSE
188 #undef AST_LOG_VERBOSE
189 #endif
190 #define AST_LOG_VERBOSE    __LOG_VERBOSE, _A_
191
192 #ifdef LOG_DTMF
193 #undef LOG_DTMF
194 #endif
195 #define __LOG_DTMF  6
196 #define LOG_DTMF    __LOG_DTMF, _A_
197
198 #ifdef AST_LOG_DTMF
199 #undef AST_LOG_DTMF
200 #endif
201 #define AST_LOG_DTMF    __LOG_DTMF, _A_
202
203 #define NUMLOGLEVELS 32
204
205 /*!
206  * \brief Get the debug level for a module
207  * \param module the name of module
208  * \return the debug level
209  */
210 unsigned int ast_debug_get_by_module(const char *module);
211
212 /*!
213  * \brief Get the verbose level for a module
214  * \param module the name of module
215  * \return the verbose level
216  */
217 unsigned int ast_verbose_get_by_module(const char *module);
218
219 /*!
220  * \brief Register a new logger level
221  * \param name The name of the level to be registered
222  * \retval -1 if an error occurs
223  * \retval non-zero level to be used with ast_log for sending messages to this level
224  * \since 1.8
225  */
226 int ast_logger_register_level(const char *name);
227
228 /*!
229  * \brief Unregister a previously registered logger level
230  * \param name The name of the level to be unregistered
231  * \return nothing
232  * \since 1.8
233  */
234 void ast_logger_unregister_level(const char *name);
235
236 /*!
237  * \brief factory function to create a new uniquely identifying callid.
238  *
239  * \retval ast_callid struct pointer containing the call id
240  *
241  * \note The newly created callid will be referenced upon creation and this function should be
242  * paired with a call to ast_callid_unref()
243  */
244 struct ast_callid *ast_create_callid(void);
245
246 /*!
247  * \brief extracts the callerid from the thread
248  *
249  * \retval ast_callid reference to call_id related to the thread
250  * \retval NULL if no call_id is present in the thread
251  *
252  * This reference must be unreffed before it loses scope to prevent memory leaks.
253  */
254 struct ast_callid *ast_read_threadstorage_callid(void);
255
256 /*!
257  * \brief Increase callid reference count
258  *
259  * \param c the ast_callid
260  *
261  * \retval c always
262  */
263 #define ast_callid_ref(c) ({ ao2_ref(c, +1); (c); })
264
265 /*!
266  * \brief Decrease callid reference count
267  *
268  * \param c the ast_callid
269  *
270  * \retval NULL always
271  */
272 #define ast_callid_unref(c) ({ ao2_ref(c, -1); (NULL); })
273
274 /*!
275  * \brief Adds a known callid to thread storage of the calling thread
276  *
277  * \retval 0 - success
278  * \retval non-zero - failure
279  */
280 int ast_callid_threadassoc_add(struct ast_callid *callid);
281
282 /*
283  * May need a function to clean the threadstorage if we want to repurpose a thread.
284  */
285
286 /*!
287  * \brief Send a log message to a dynamically registered log level
288  * \param level The log level to send the message to
289  *
290  * Like ast_log, the log message may include printf-style formats, and
291  * the data for these must be provided as additional parameters after
292  * the log message.
293  *
294  * \return nothing
295  * \since 1.8
296  */
297
298 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
299
300 /*!
301  * \brief Log a DEBUG message
302  * \param level The minimum value of option_debug for this message
303  *        to get logged
304  */
305 #define ast_debug(level, ...) do {       \
306         if (option_debug >= (level) || (ast_opt_dbg_module && ast_debug_get_by_module(AST_MODULE) >= (level)) ) \
307                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
308 } while (0)
309
310 #define ast_verb(level, ...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, __VA_ARGS__)
311
312 #ifndef _LOGGER_BACKTRACE_H
313 #define _LOGGER_BACKTRACE_H
314 #ifdef HAVE_BKTR
315 #define AST_MAX_BT_FRAMES 32
316 /* \brief
317  *
318  * A structure to hold backtrace information. This structure provides an easy means to
319  * store backtrace information or pass backtraces to other functions.
320  */
321 struct ast_bt {
322         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
323         void *addresses[AST_MAX_BT_FRAMES];
324         /*! The number of stack frames in the backtrace */
325         int num_frames;
326         /*! Tells if the ast_bt structure was dynamically allocated */
327         unsigned int alloced:1;
328 };
329
330 /* \brief
331  * Allocates memory for an ast_bt and stores addresses and symbols.
332  *
333  * \return Returns NULL on failure, or the allocated ast_bt on success
334  * \since 1.6.1
335  */
336 struct ast_bt *ast_bt_create(void);
337
338 /* \brief
339  * Fill an allocated ast_bt with addresses
340  *
341  * \retval 0 Success
342  * \retval -1 Failure
343  * \since 1.6.1
344  */
345 int ast_bt_get_addresses(struct ast_bt *bt);
346
347 /* \brief
348  *
349  * Free dynamically allocated portions of an ast_bt
350  *
351  * \retval NULL.
352  * \since 1.6.1
353  */
354 void *ast_bt_destroy(struct ast_bt *bt);
355
356 /* \brief Retrieve symbols for a set of backtrace addresses
357  *
358  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
359  * \param num_frames Number of addresses in the addresses list
360  * \retval NULL Unable to allocate memory
361  * \return List of strings
362  * \since 1.6.2.16
363  */
364 char **ast_bt_get_symbols(void **addresses, size_t num_frames);
365
366 #endif /* HAVE_BKTR */
367 #endif /* _LOGGER_BACKTRACE_H */
368
369 #if defined(__cplusplus) || defined(c_plusplus)
370 }
371 #endif
372
373 #endif /* _ASTERISK_LOGGER_H */