![[first]](../icons/first.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[last]](../icons/last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[bottom]](../icons/bottom.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * Copyright 2004-2024 the Pacemaker project contributors
3 *
4 * The version control history for this file may have further details.
5 *
6 * This source code is licensed under the GNU General Public License version 2
7 * or later (GPLv2+) WITHOUT ANY WARRANTY.
8 */
9
10 #ifndef PCMK__CRM_COMMON_LOGGING__H
11 #define PCMK__CRM_COMMON_LOGGING__H
12
13 #include <stdio.h>
14 #include <stdint.h> // uint8_t, uint32_t
15 #include <glib.h>
16 #include <qb/qblog.h>
17 #include <libxml/tree.h>
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /**
24 * \file
25 * \brief Wrappers for and extensions to libqb logging
26 * \ingroup core
27 */
28
29
30 /* Define custom log priorities.
31 *
32 * syslog(3) uses int for priorities, but libqb's struct qb_log_callsite uses
33 * uint8_t, so make sure they fit in the latter.
34 */
35
36 // Define something even less desired than debug
37 #ifndef LOG_TRACE
38 #define LOG_TRACE (LOG_DEBUG+1)
39 #endif
40
41 // Print message to stdout instead of logging it
42 #ifndef LOG_STDOUT
43 #define LOG_STDOUT 254
44 #endif
45
46 // Don't send message anywhere
47 #ifndef LOG_NEVER
48 #define LOG_NEVER 255
49 #endif
50
51 /* "Extended information" logging support */
52 #ifdef QB_XS
53 #define CRM_XS QB_XS
54 #define crm_extended_logging(t, e) qb_log_ctl((t), QB_LOG_CONF_EXTENDED, (e))
55 #else
56 #define CRM_XS "|"
57
58 /* A caller might want to check the return value, so we can't define this as a
59 * no-op, and we can't simply define it to be 0 because gcc will then complain
60 * when the value isn't checked.
61 */
62 static inline int
63 crm_extended_logging(int t, int e)
/* ![[next]](../icons/right.png)
![[first]](../icons/n_first.png)
![[top]](../icons/top.png)
*/
64 {
65 return 0;
66 }
67 #endif
68
69 // @COMPAT Make internal when we can break API backward compatibility
70 //! \deprecated Do not use
71 extern unsigned int crm_log_level;
72
73 // @COMPAT Make internal when we can break API backward compatibility
74 //! \deprecated Do not use
75 extern unsigned int crm_trace_nonlog;
76
77 /*! \deprecated Pacemaker library functions set this when a configuration
78 * error is found, which turns on extra messages at the end of
79 * processing. It should not be used directly and will be removed
80 * from the public C API in a future release.
81 */
82 extern gboolean crm_config_error;
83
84 /*! \deprecated Pacemaker library functions set this when a configuration
85 * warning is found, which turns on extra messages at the end of
86 * processing. It should not be used directly and will be removed
87 * from the public C API in a future release.
88 */
89 extern gboolean crm_config_warning;
90
91 void crm_enable_blackbox(int nsig);
92 void crm_disable_blackbox(int nsig);
93 void crm_write_blackbox(int nsig, const struct qb_log_callsite *callsite);
94
95 void crm_update_callsites(void);
96
97 void crm_log_deinit(void);
98
99 /*!
100 * \brief Initializes the logging system and defaults to the least verbose output level
101 *
102 * \param[in] entity If not NULL, will be used as the identity for logging purposes
103 * \param[in] argc The number of command line parameters
104 * \param[in] argv The command line parameter values
105 */
106 void crm_log_preinit(const char *entity, int argc, char *const *argv);
107 gboolean crm_log_init(const char *entity, uint8_t level, gboolean daemon,
108 gboolean to_stderr, int argc, char **argv, gboolean quiet);
109
110 void crm_log_args(int argc, char **argv);
111 void crm_log_output_fn(const char *file, const char *function, int line, int level,
112 const char *prefix, const char *output);
113
114 // Log a block of text line by line
115 #define crm_log_output(level, prefix, output) \
116 crm_log_output_fn(__FILE__, __func__, __LINE__, level, prefix, output)
117
118 void crm_bump_log_level(int argc, char **argv);
119
120 void crm_enable_stderr(int enable);
121
122 gboolean crm_is_callsite_active(struct qb_log_callsite *cs, uint8_t level, uint32_t tags);
123
124 // NOTE: sbd (as of at least 1.5.2) uses this
125 /* returns the old value */
126 unsigned int set_crm_log_level(unsigned int level);
127
128 unsigned int get_crm_log_level(void);
129
130 void pcmk_log_xml_as(const char *file, const char *function, uint32_t line,
131 uint32_t tags, uint8_t level, const char *text,
132 const xmlNode *xml);
133
134 /*
135 * Throughout the macros below, note the leading, pre-comma, space in the
136 * various ' , ##args' occurrences to aid portability across versions of 'gcc'.
137 * https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html#Variadic-Macros
138 */
139 #if defined(__clang__)
140 #define CRM_TRACE_INIT_DATA(name)
141 #else
142 #include <assert.h> // required by QB_LOG_INIT_DATA() macro
143 #define CRM_TRACE_INIT_DATA(name) QB_LOG_INIT_DATA(name)
144 #endif
145
146 /*!
147 * \internal
148 * \brief Clip log_level to \p uint8_t range
149 *
150 * \param[in] level Log level to clip
151 *
152 * \return 0 if \p level is less than 0, \p UINT8_MAX if \p level is greater
153 * than \p UINT8_MAX, or \p level otherwise
154 */
155 /* @COMPAT: Make this function internal at a compatibility break. It's used in
156 * public macros for now.
157 */
158 static inline uint8_t
159 pcmk__clip_log_level(int level)
/* ![[previous]](../icons/left.png)
![[last]](../icons/n_last.png)
*/
160 {
161 if (level <= 0) {
162 return 0;
163 }
164 if (level >= UINT8_MAX) {
165 return UINT8_MAX;
166 }
167 return level;
168 }
169
170 /* Using "switch" instead of "if" in these macro definitions keeps
171 * static analysis from complaining about constant evaluations
172 */
173
174 /*!
175 * \brief Log a message
176 *
177 * \param[in] level Priority at which to log the message
178 * \param[in] fmt printf-style format string literal for message
179 * \param[in] args Any arguments needed by format string
180 */
181 #define do_crm_log(level, fmt, args...) do { \
182 uint8_t _level = pcmk__clip_log_level(level); \
183 \
184 switch (_level) { \
185 case LOG_STDOUT: \
186 printf(fmt "\n" , ##args); \
187 break; \
188 case LOG_NEVER: \
189 break; \
190 default: \
191 qb_log_from_external_source(__func__, __FILE__, fmt, \
192 _level, __LINE__, 0 , ##args); \
193 break; \
194 } \
195 } while (0)
196
197 /*!
198 * \brief Log a message that is likely to be filtered out
199 *
200 * \param[in] level Priority at which to log the message
201 * \param[in] fmt printf-style format string for message
202 * \param[in] args Any arguments needed by format string
203 *
204 * \note This does nothing when level is \p LOG_STDOUT.
205 */
206 #define do_crm_log_unlikely(level, fmt, args...) do { \
207 uint8_t _level = pcmk__clip_log_level(level); \
208 \
209 switch (_level) { \
210 case LOG_STDOUT: case LOG_NEVER: \
211 break; \
212 default: { \
213 static struct qb_log_callsite *trace_cs = NULL; \
214 if (trace_cs == NULL) { \
215 trace_cs = qb_log_callsite_get(__func__, __FILE__, fmt, \
216 _level, __LINE__, 0); \
217 } \
218 if (crm_is_callsite_active(trace_cs, _level, 0)) { \
219 qb_log_from_external_source(__func__, __FILE__, fmt, \
220 _level, __LINE__, 0 , \
221 ##args); \
222 } \
223 } \
224 break; \
225 } \
226 } while (0)
227
228 #define CRM_LOG_ASSERT(expr) do { \
229 if (!(expr)) { \
230 static struct qb_log_callsite *core_cs = NULL; \
231 if(core_cs == NULL) { \
232 core_cs = qb_log_callsite_get(__func__, __FILE__, \
233 "log-assert", LOG_TRACE, \
234 __LINE__, 0); \
235 } \
236 crm_abort(__FILE__, __func__, __LINE__, #expr, \
237 core_cs?core_cs->targets:FALSE, TRUE); \
238 } \
239 } while(0)
240
241 // NOTE: sbd (as of at least 1.5.2) uses this
242 /* 'failure_action' MUST NOT be 'continue' as it will apply to the
243 * macro's do-while loop
244 */
245 #define CRM_CHECK(expr, failure_action) do { \
246 if (!(expr)) { \
247 static struct qb_log_callsite *core_cs = NULL; \
248 if (core_cs == NULL) { \
249 core_cs = qb_log_callsite_get(__func__, __FILE__, \
250 "check-assert", \
251 LOG_TRACE, __LINE__, 0); \
252 } \
253 crm_abort(__FILE__, __func__, __LINE__, #expr, \
254 (core_cs? core_cs->targets: FALSE), TRUE); \
255 failure_action; \
256 } \
257 } while(0)
258
259 /*!
260 * \brief Log XML line-by-line in a formatted fashion
261 *
262 * \param[in] level Priority at which to log the messages
263 * \param[in] text Prefix for each line
264 * \param[in] xml XML to log
265 *
266 * \note This does nothing when \p level is \p LOG_STDOUT.
267 */
268 #define do_crm_log_xml(level, text, xml) do { \
269 uint8_t _level = pcmk__clip_log_level(level); \
270 static struct qb_log_callsite *xml_cs = NULL; \
271 \
272 switch (_level) { \
273 case LOG_STDOUT: \
274 case LOG_NEVER: \
275 break; \
276 default: \
277 if (xml_cs == NULL) { \
278 xml_cs = qb_log_callsite_get(__func__, __FILE__, \
279 "xml-blob", _level, \
280 __LINE__, 0); \
281 } \
282 if (crm_is_callsite_active(xml_cs, _level, 0)) { \
283 pcmk_log_xml_as(__FILE__, __func__, __LINE__, 0, \
284 _level, text, (xml)); \
285 } \
286 break; \
287 } \
288 } while(0)
289
290 /*!
291 * \brief Log a message as if it came from a different code location
292 *
293 * \param[in] level Priority at which to log the message
294 * \param[in] file Source file name to use instead of __FILE__
295 * \param[in] function Source function name to use instead of __func__
296 * \param[in] line Source line number to use instead of __line__
297 * \param[in] fmt printf-style format string literal for message
298 * \param[in] args Any arguments needed by format string
299 */
300 #define do_crm_log_alias(level, file, function, line, fmt, args...) do { \
301 uint8_t _level = pcmk__clip_log_level(level); \
302 \
303 switch (_level) { \
304 case LOG_STDOUT: \
305 printf(fmt "\n" , ##args); \
306 break; \
307 case LOG_NEVER: \
308 break; \
309 default: \
310 qb_log_from_external_source(function, file, fmt, _level, \
311 line, 0 , ##args); \
312 break; \
313 } \
314 } while (0)
315
316 // NOTE: sbd (as of at least 1.5.2) uses this
317 /*!
318 * \brief Send a system error message to both the log and stderr
319 *
320 * \param[in] level Priority at which to log the message
321 * \param[in] fmt printf-style format string for message
322 * \param[in] args Any arguments needed by format string
323 *
324 * \deprecated One of the other logging functions should be used with
325 * pcmk_strerror() instead.
326 * \note This is a macro, and \p level may be evaluated more than once.
327 * \note Because crm_perror() adds the system error message and error number
328 * onto the end of fmt, that information will become extended information
329 * if CRM_XS is used inside fmt and will not show up in syslog.
330 */
331 #define crm_perror(level, fmt, args...) do { \
332 uint8_t _level = pcmk__clip_log_level(level); \
333 \
334 switch (_level) { \
335 case LOG_NEVER: \
336 break; \
337 default: { \
338 const char *err = strerror(errno); \
339 if (_level <= crm_log_level) { \
340 fprintf(stderr, fmt ": %s (%d)\n" , ##args, err, \
341 errno); \
342 } \
343 /* Pass original level arg since do_crm_log() also declares \
344 * _level \
345 */ \
346 do_crm_log((level), fmt ": %s (%d)" , ##args, err, errno); \
347 } \
348 break; \
349 } \
350 } while (0)
351
352 /*!
353 * \brief Log a message with a tag (for use with PCMK_trace_tags)
354 *
355 * \param[in] level Priority at which to log the message
356 * \param[in] tag String to tag message with
357 * \param[in] fmt printf-style format string for message
358 * \param[in] args Any arguments needed by format string
359 *
360 * \note This does nothing when level is LOG_STDOUT.
361 */
362 #define crm_log_tag(level, tag, fmt, args...) do { \
363 uint8_t _level = pcmk__clip_log_level(level); \
364 \
365 switch (_level) { \
366 case LOG_STDOUT: case LOG_NEVER: \
367 break; \
368 default: { \
369 static struct qb_log_callsite *trace_tag_cs = NULL; \
370 int converted_tag = g_quark_try_string(tag); \
371 if (trace_tag_cs == NULL) { \
372 trace_tag_cs = qb_log_callsite_get(__func__, __FILE__, \
373 fmt, _level, \
374 __LINE__, \
375 converted_tag); \
376 } \
377 if (crm_is_callsite_active(trace_tag_cs, _level, \
378 converted_tag)) { \
379 qb_log_from_external_source(__func__, __FILE__, fmt, \
380 _level, __LINE__, \
381 converted_tag , ##args); \
382 } \
383 } \
384 } \
385 } while (0)
386
387 #define crm_emerg(fmt, args...) qb_log(LOG_EMERG, fmt , ##args)
388 #define crm_crit(fmt, args...) qb_logt(LOG_CRIT, 0, fmt , ##args)
389
390 // NOTE: sbd (as of at least 1.5.2) uses this
391 #define crm_err(fmt, args...) qb_logt(LOG_ERR, 0, fmt , ##args)
392
393 // NOTE: sbd (as of at least 1.5.2) uses this
394 #define crm_warn(fmt, args...) qb_logt(LOG_WARNING, 0, fmt , ##args)
395
396 // NOTE: sbd (as of at least 1.5.2) uses this
397 #define crm_notice(fmt, args...) qb_logt(LOG_NOTICE, 0, fmt , ##args)
398
399 #define crm_info(fmt, args...) qb_logt(LOG_INFO, 0, fmt , ##args)
400 //
401 // NOTE: sbd (as of at least 1.5.2) uses this
402 #define crm_debug(fmt, args...) do_crm_log_unlikely(LOG_DEBUG, fmt , ##args)
403
404 #define crm_trace(fmt, args...) do_crm_log_unlikely(LOG_TRACE, fmt , ##args)
405
406 #define crm_log_xml_crit(xml, text) do_crm_log_xml(LOG_CRIT, text, xml)
407 #define crm_log_xml_err(xml, text) do_crm_log_xml(LOG_ERR, text, xml)
408 #define crm_log_xml_warn(xml, text) do_crm_log_xml(LOG_WARNING, text, xml)
409 #define crm_log_xml_notice(xml, text) do_crm_log_xml(LOG_NOTICE, text, xml)
410 #define crm_log_xml_info(xml, text) do_crm_log_xml(LOG_INFO, text, xml)
411 #define crm_log_xml_debug(xml, text) do_crm_log_xml(LOG_DEBUG, text, xml)
412 #define crm_log_xml_trace(xml, text) do_crm_log_xml(LOG_TRACE, text, xml)
413
414 #define crm_log_xml_explicit(xml, text) do { \
415 static struct qb_log_callsite *digest_cs = NULL; \
416 digest_cs = qb_log_callsite_get( \
417 __func__, __FILE__, text, LOG_TRACE, __LINE__, \
418 crm_trace_nonlog); \
419 if (digest_cs && digest_cs->targets) { \
420 do_crm_log_xml(LOG_TRACE, text, xml); \
421 } \
422 } while(0)
423
424 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
425 #include <crm/common/logging_compat.h>
426 #endif
427
428 #ifdef __cplusplus
429 }
430 #endif
431
432 #endif
![[bottom]](../icons/n_bottom.png){kind=icon}
*/