MySQL 8.2.0
Source Code Documentation
logging.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2016, 2023, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is also distributed with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have included with MySQL.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23*/
24
25/**
26 * @file
27 * @brief Logging interface for using and extending the logging subsystem.
28 */
29
30#ifndef MYSQL_HARNESS_LOGGING_INCLUDED
31#define MYSQL_HARNESS_LOGGING_INCLUDED
32
33#include "harness_export.h"
37
38#include <chrono>
39#include <cstdarg>
40#include <fstream>
41#include <list>
42#include <mutex>
43#include <string>
44
45namespace mysql_harness {
46
47namespace logging {
48
49/**
50 * Max message length that can be logged; if message is longer,
51 * it will be truncated to this length.
52 */
53const size_t kLogMessageMaxSize = 4096;
54
55/**
56 * Section name and option name used in config file (and later in configuration
57 * object) to specify log level, best explained by example:
58 *
59 * v----------------------- kConfigSectionLogger
60 * [logger]
61 * v------------------------ kConfigOptionLogLevel
62 * level = DEBUG
63 * v------------------------ kConfigOptionLogFilename
64 * filename = foo.log
65 * v------------------------ kConfigOptionLogTimestampPrecision
66 * timestamp_precision = second|sec|s|millisecond|msec|ms|
67 * microsecond|usec|us|nanosecond|nsec|ns
68 */
69constexpr char kConfigOptionLogFilename[] = "filename";
70constexpr char kConfigOptionLogDestination[] = "destination";
71constexpr char kConfigOptionLogLevel[] = "level";
72constexpr char kConfigOptionLogTimestampPrecision[] = "timestamp_precision";
73constexpr char kConfigSectionLogger[] = "logger";
74
75constexpr char kNone[] = "";
76/**
77 * Special names reserved for "main" program logger. It will use one of the
78 * two handlers, depending on whether logging_folder is empty or not.
79 */
80constexpr char kMainLogger[] = "main";
81constexpr char kMainLogHandler[] = "main_log_handler";
82constexpr char kMainConsoleHandler[] = "main_console_handler";
83
84constexpr char kSqlLogger[] = "sql";
85/**
86 * Default log filename
87 */
88constexpr char kDefaultLogFilename[] = "mysqlrouter.log";
89/**
90 * Log level values.
91 *
92 * Log levels are ordered numerically from most important (lowest
93 * value) to least important (highest value).
94 */
95enum class LogLevel {
96 /** Fatal failure. Router usually exits after logging this. */
97 kFatal,
98
99 /**
100 * System message. These messages are always logged, such as state changes
101 * during startup and shutdown.
102 */
103 kSystem,
104
105 /**
106 * Error message. indicate that something is not working properly and
107 * actions need to be taken. However, the router continue
108 * operating but the particular thread issuing the error message
109 * might terminate.
110 */
111 kError,
112
113 /**
114 * Warning message. Indicate a potential problem that could require
115 * actions, but does not cause a problem for the continuous operation
116 * of the router.
117 */
118 kWarning,
119
120 /**
121 * Informational message. Information that can be useful to check
122 * the behaviour of the router during normal operation.
123 */
124 kInfo,
125
126 /**
127 * Note level contains additional information over the normal informational
128 * messages.
129 */
130 kNote,
131
132 /**
133 * Debug message. Message contain internal details that can be
134 * useful for debugging problematic situations, especially regarding
135 * the router itself.
136 */
137 kDebug,
138
139 kNotSet // Always higher than all other log messages
140};
141
142/**
143 * Default log level used by the router.
144 */
146
147/**
148 * Log level name for the default log level used by the router
149 */
150const char *const kDefaultLogLevelName = "warning";
151
152/**
153 * Log level name used in raw logging mode
154 */
155const char *const kRawLogLevelName = "info";
156
157/**
158 * Log timestamp precision values.
159 */
161 // Second
162 kSec = 0,
163
164 // Millisecond
165 kMilliSec = 3,
166
167 // Microsecond
168 kMicroSec = 6,
169
170 // Nanosecond
171 kNanoSec = 9,
172
173 kNotSet // Always higher than all other log precisions
174};
175
176/**
177 * Log record containing information collected by the logging
178 * system.
179 *
180 * The log record is passed to the handlers together with message.
181 */
182struct Record {
185 std::chrono::time_point<std::chrono::system_clock> created;
186 std::string domain;
187 std::string message;
188};
189
190/**
191 * Log message for the domain.
192 *
193 * This will log an error, warning, informational, or debug message
194 * for the given domain. The domain have to be be registered before
195 * anything is being logged. The `Loader` uses the plugin name as the
196 * domain name, so normally you should provide the plugin name as the
197 * first argument to this function.
198 *
199 * @param name Domain name to use when logging message.
200 *
201 * @param fmt `printf`-style format string, with arguments following.
202 */
203/** @{ */
204#ifdef __cplusplus
205extern "C" {
206#endif
207
208/**
209 * Pre-processor symbol containing the name of the log domain. If not
210 * defined explicitly when compiling, it will be an empty string, which
211 * means that it logs to the top log domain.
212 */
213
214#ifndef MYSQL_ROUTER_LOG_DOMAIN
215#define MYSQL_ROUTER_LOG_DOMAIN ""
216#endif
217
218/*
219 * We need to declare these first, because __attribute__ can only be used in
220 * declarations.
221 */
222static inline void log_system(const char *fmt, ...)
223 ATTRIBUTE_GCC_FORMAT(printf, 1, 2);
224static inline void log_error(const char *fmt, ...)
225 ATTRIBUTE_GCC_FORMAT(printf, 1, 2);
226static inline void log_warning(const char *fmt, ...)
227 ATTRIBUTE_GCC_FORMAT(printf, 1, 2);
228static inline void log_info(const char *fmt, ...)
229 ATTRIBUTE_GCC_FORMAT(printf, 1, 2);
230static inline void log_note(const char *fmt, ...)
231 ATTRIBUTE_GCC_FORMAT(printf, 1, 2);
232static inline void log_debug(const char *fmt, ...)
233 ATTRIBUTE_GCC_FORMAT(printf, 1, 2);
234static inline void log_custom(const LogLevel log_level, const char *fmt, ...)
235 ATTRIBUTE_GCC_FORMAT(printf, 2, 3);
236
237/*
238 * Define inline functions that pick up the log domain defined for the module.
239 */
240
241static inline void log_system(const char *fmt, ...) {
242 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
243 const char *fmt, va_list ap);
244 va_list ap;
245 va_start(ap, fmt);
247 va_end(ap);
248}
249
250static inline void log_error(const char *fmt, ...) {
251 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
252 const char *fmt, va_list ap);
253 va_list ap;
254 va_start(ap, fmt);
256 va_end(ap);
257}
258
259static inline void log_warning(const char *fmt, ...) {
260 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
261 const char *fmt, va_list ap);
262 va_list ap;
263 va_start(ap, fmt);
265 va_end(ap);
266}
267
268static inline void log_info(const char *fmt, ...) {
269 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
270 const char *fmt, va_list ap);
271 va_list ap;
272 va_start(ap, fmt);
274 va_end(ap);
275}
276
277static inline void log_note(const char *fmt, ...) {
278 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
279 const char *fmt, va_list ap);
280 va_list ap;
281 va_start(ap, fmt);
283 va_end(ap);
284}
285
286static inline void log_debug(const char *fmt, ...) {
287 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
288 const char *fmt, va_list ap);
289 va_list ap;
290 va_start(ap, fmt);
292 va_end(ap);
293}
294
295static inline void log_custom(const LogLevel log_level, const char *fmt, ...) {
296 extern void HARNESS_EXPORT log_message(LogLevel level, const char *module,
297 const char *fmt, va_list ap);
298 va_list ap;
299 va_start(ap, fmt);
300 log_message(log_level, MYSQL_ROUTER_LOG_DOMAIN, fmt, ap);
301 va_end(ap);
302}
303
304/** @} */
305
306#ifdef __cplusplus
307}
308#endif
309
310HARNESS_EXPORT bool log_level_is_handled(LogLevel level, const char *domain);
311
312static inline bool log_level_is_handled(LogLevel level) {
314}
315
316} // namespace logging
317
318} // namespace mysql_harness
319
320/**
321 * convenience macro to avoid common boilerplate
322 */
323#define IMPORT_LOG_FUNCTIONS() \
324 using mysql_harness::logging::log_system; \
325 using mysql_harness::logging::log_error; \
326 using mysql_harness::logging::log_warning; \
327 using mysql_harness::logging::log_info; \
328 using mysql_harness::logging::log_note; \
329 using mysql_harness::logging::log_debug; \
330 using mysql_harness::logging::log_custom;
331
332#endif // MYSQL_HARNESS_LOGGING_INCLUDED
#define ATTRIBUTE_GCC_FORMAT(style, fmt_pos, arg_pos)
Definition: compiler_attributes.h:32
#define MYSQL_ROUTER_LOG_DOMAIN
Log message for the domain.
Definition: logging.h:215
const size_t kLogMessageMaxSize
Max message length that can be logged; if message is longer, it will be truncated to this length.
Definition: logging.h:53
constexpr char kConfigOptionLogLevel[]
Definition: logging.h:71
const char *const kDefaultLogLevelName
Log level name for the default log level used by the router.
Definition: logging.h:150
constexpr char kDefaultLogFilename[]
Default log filename.
Definition: logging.h:88
constexpr char kConfigOptionLogTimestampPrecision[]
Definition: logging.h:72
constexpr char kSqlLogger[]
Definition: logging.h:84
const LogLevel kDefaultLogLevel
Default log level used by the router.
Definition: logging.h:145
LogLevel
Log level values.
Definition: logging.h:95
@ kInfo
Informational message.
@ kNote
Note level contains additional information over the normal informational messages.
constexpr char kMainLogger[]
Special names reserved for "main" program logger.
Definition: logging.h:80
constexpr char kNone[]
Definition: logging.h:75
static void static void static void static void static void static void static void log_custom(const LogLevel log_level, const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:295
static void static void log_error(const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:250
constexpr char kMainConsoleHandler[]
Definition: logging.h:82
constexpr char kConfigOptionLogFilename[]
Section name and option name used in config file (and later in configuration object) to specify log l...
Definition: logging.h:69
static void static void static void static void static void log_note(const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:277
const char *const kRawLogLevelName
Log level name used in raw logging mode.
Definition: logging.h:155
static void log_system(const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:241
static void static void static void static void log_info(const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:268
static void static void static void static void static void static void log_debug(const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:286
static void static void static void log_warning(const char *fmt,...) ATTRIBUTE_GCC_FORMAT(printf
Definition: logging.h:259
LogTimestampPrecision
Log timestamp precision values.
Definition: logging.h:160
constexpr char kMainLogHandler[]
Definition: logging.h:81
constexpr char kConfigSectionLogger[]
Definition: logging.h:73
constexpr char kConfigOptionLogDestination[]
Definition: logging.h:70
HARNESS_EXPORT bool log_level_is_handled(LogLevel level, const char *domain)
Definition: registry.cc:494
Definition: common.h:41
pid_t pid_type
Definition: process.h:44
void HARNESS_EXPORT log_message(LogLevel level, const char *module, const char *fmt, va_list ap)
Definition: registry.cc:535
Log record containing information collected by the logging system.
Definition: logging.h:182
stdx::this_process::pid_type process_id
Definition: logging.h:184
LogLevel level
Definition: logging.h:183
std::string message
Definition: logging.h:187
std::string domain
Definition: logging.h:186
std::chrono::time_point< std::chrono::system_clock > created
Definition: logging.h:185