Debian Codegraph @

src/basic/log-context.h

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 #pragma once
3
4 #include "basic-forward.h"
5 #include "list.h"
6
7 /*
8 * The log context allows attaching extra metadata to log messages written to the journal via log.h. We keep
9 * track of a thread local log context onto which we can push extra metadata fields that should be logged.
10 *
11 * LOG_CONTEXT_PUSH() will add the provided field to the log context and will remove it again when the
12 * current block ends. LOG_CONTEXT_PUSH_STRV() will do the same but for all fields in the given strv.
13 * LOG_CONTEXT_PUSHF() is like LOG_CONTEXT_PUSH() but takes a format string and arguments.
14 *
15 * Using the macros is as simple as putting them anywhere inside a block to add a field to all following log
16 * messages logged from inside that block.
17 *
18 * void myfunction(...) {
19 * ...
20 *
21 * LOG_CONTEXT_PUSHF("MYMETADATA=%s", "abc");
22 *
23 * // Every journal message logged will now have the MYMETADATA=abc
24 * // field included.
25 * }
26 *
27 * One special case to note is async code, where we use callbacks that are invoked to continue processing
28 * when some event occurs. For async code, there's usually an associated "userdata" struct containing all the
29 * information associated with the async operation. In this "userdata" struct, we can store a log context
30 * allocated with log_context_new() and freed with log_context_free(). We can then add and remove fields to
31 * the `fields` member of the log context object and all those fields will be logged along with each log
32 * message.
33 */
34
35 typedef struct LogContext {
36 unsigned n_ref;
37 /* Depending on which destructor is used (log_context_free() or log_context_detach()) the memory
38 * referenced by this is freed or not */
39 char **fields;
40 struct iovec *input_iovec;
41 size_t n_input_iovec;
42 char *key;
43 char *value;
44 bool owned;
45 LIST_FIELDS(struct LogContext, ll);
46 } LogContext;
47
48 bool log_context_enabled(void);
49
50 LogContext* log_context_new(const char *key, const char *value);
51 LogContext* log_context_new_strv(char **fields, bool owned);
52 LogContext* log_context_new_iov(struct iovec *input_iovec, size_t n_input_iovec, bool owned);
53
54 /* Same as log_context_new(), but frees the given fields strv/iovec on failure. */
55 LogContext* log_context_new_strv_consume(char **fields);
56 LogContext* log_context_new_iov_consume(struct iovec *input_iovec, size_t n_input_iovec);
57
58 DECLARE_TRIVIAL_REF_UNREF_FUNC(LogContext, log_context);
59
60 DEFINE_TRIVIAL_CLEANUP_FUNC(LogContext*, log_context_unref);
61
62 /* Returns the head of the log context list. */
63 LogContext* log_context_head(void);
64 /* Returns the number of attached log context objects. */
65 size_t log_context_num_contexts(void);
66 /* Returns the number of fields in all attached log contexts. */
67 size_t log_context_num_fields(void);
68
69 void log_context_swap(LogContext **log_context, size_t *num_fields);
70
71 void _reset_log_level(int *saved_log_level);
72
73 #define _LOG_CONTEXT_SET_LOG_LEVEL(level, l) \
74 _cleanup_(_reset_log_level) _unused_ int l = log_set_max_level(level);
75
76 #define LOG_CONTEXT_SET_LOG_LEVEL(level) \
77 _LOG_CONTEXT_SET_LOG_LEVEL(level, UNIQ_T(l, UNIQ))
78
79 #define LOG_CONTEXT_PUSH(...) \
80 LOG_CONTEXT_PUSH_STRV(STRV_MAKE(__VA_ARGS__))
81
82 #define LOG_CONTEXT_PUSHF(...) \
83 LOG_CONTEXT_PUSH(snprintf_ok((char[LINE_MAX]) {}, LINE_MAX, __VA_ARGS__))
84
85 #define _LOG_CONTEXT_PUSH_KEY_VALUE(key, value, c) \
86 _unused_ _cleanup_(log_context_unrefp) LogContext *c = log_context_new(key, value);
87
88 #define LOG_CONTEXT_PUSH_KEY_VALUE(key, value) \
89 _LOG_CONTEXT_PUSH_KEY_VALUE(key, value, UNIQ_T(c, UNIQ))
90
91 #define _LOG_CONTEXT_PUSH_STRV(strv, c) \
92 _unused_ _cleanup_(log_context_unrefp) LogContext *c = log_context_new_strv(strv, /* owned= */ false);
93
94 #define LOG_CONTEXT_PUSH_STRV(strv) \
95 _LOG_CONTEXT_PUSH_STRV(strv, UNIQ_T(c, UNIQ))
96
97 #define _LOG_CONTEXT_PUSH_IOV(input_iovec, n_input_iovec, c) \
98 _unused_ _cleanup_(log_context_unrefp) LogContext *c = log_context_new_iov(input_iovec, n_input_iovec, /* owned= */ false);
99
100 #define LOG_CONTEXT_PUSH_IOV(input_iovec, n_input_iovec) \
101 _LOG_CONTEXT_PUSH_IOV(input_iovec, n_input_iovec, UNIQ_T(c, UNIQ))
102
103 /* LOG_CONTEXT_CONSUME_STR()/LOG_CONTEXT_CONSUME_STRV()/LOG_CONTEXT_CONSUME_IOV() are identical to
104 * LOG_CONTEXT_PUSH_STR()/LOG_CONTEXT_PUSH_STRV()/LOG_CONTEXT_PUSH_IOV() except they take ownership of the
105 * given str/strv argument.
106 */
107
108 #define _LOG_CONTEXT_CONSUME_STR(s, c, strv) \
109 _unused_ _cleanup_strv_free_ strv = strv_new(s); \
110 if (!strv) \
111 free(s); \
112 _unused_ _cleanup_(log_context_unrefp) LogContext *c = log_context_new_strv_consume(TAKE_PTR(strv))
113
114 #define LOG_CONTEXT_CONSUME_STR(s) \
115 _LOG_CONTEXT_CONSUME_STR(s, UNIQ_T(c, UNIQ), UNIQ_T(sv, UNIQ))
116
117 #define _LOG_CONTEXT_CONSUME_STRV(strv, c) \
118 _unused_ _cleanup_(log_context_unrefp) LogContext *c = log_context_new_strv_consume(strv);
119
120 #define LOG_CONTEXT_CONSUME_STRV(strv) \
121 _LOG_CONTEXT_CONSUME_STRV(strv, UNIQ_T(c, UNIQ))
122
123 #define _LOG_CONTEXT_CONSUME_IOV(input_iovec, n_input_iovec, c) \
124 _unused_ _cleanup_(log_context_unrefp) LogContext *c = log_context_new_iov_consume(input_iovec, n_input_iovec);
125
126 #define LOG_CONTEXT_CONSUME_IOV(input_iovec, n_input_iovec) \
127 _LOG_CONTEXT_CONSUME_IOV(input_iovec, n_input_iovec, UNIQ_T(c, UNIQ))