MySQL 8.2.0
Source Code Documentation
handler.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2017, 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#ifndef MYSQL_HARNESS_LOGGER_HANDLER_INCLUDED
26#define MYSQL_HARNESS_LOGGER_HANDLER_INCLUDED
27
28#include "harness_export.h"
30
31#include <fstream>
32#include <iostream>
33#include <mutex>
34#include <string>
35
36namespace mysql_harness {
37
38namespace logging {
39
40/**
41 * Base class for log message handler.
42 *
43 * This class is used to implement a log message handler. You need
44 * to implement the `do_log` primitive to process the log
45 * record. If, for some reason, the implementation is unable to log
46 * the record, and exception can be thrown that will be caught by
47 * the harness.
48 */
49class HARNESS_EXPORT Handler {
50 public:
51 /**
52 * Default identifier
53 *
54 * Every handler provides a default name which could be used as key in
55 * registry to uniquely identify it. There is no obligation to use it, it
56 * is only supplied for convenience. In case of many instances of the same
57 * handler, using a key derived from this default (such as
58 * "my_handler:instance1") is suggested.
59 *
60 * This field should be set in derived classes
61 */
62 static constexpr const char *kDefaultName = nullptr;
63
64 explicit Handler() = default;
65 explicit Handler(const Handler &) = default;
66 Handler &operator=(const Handler &) = default;
67
68 virtual ~Handler() = default;
69
70 void handle(const Record &record);
71
72 void set_level(LogLevel level) { level_ = level; }
73 LogLevel get_level() const { return level_; }
75 precision_ = precision;
76 }
77
78 /**
79 * Request to reopen underlying log sink. Should be no-op for handlers NOT
80 * writing to a file. Useful for log rotation, when the logger got the
81 * signal with the request to reopen the file. Provide a destination filename
82 * for the old file for file based handlers.
83 */
84 virtual void reopen(const std::string dst = "") = 0;
85
86 /**
87 * check if the handler has logged at least one record.
88 *
89 * @retval true if at least one record was logged
90 * @retval false if no record has been logged yet.
91 */
92 bool has_logged() const { return has_logged_; }
93
94 protected:
95 std::string format(const Record &record) const;
96
97 explicit Handler(bool format_messages, LogLevel level,
98 LogTimestampPrecision timestamp_precision);
99
100 void has_logged(bool v) { has_logged_ = v; }
101
102 private:
103 /**
104 * Log message handler primitive.
105 *
106 * This member function is implemented by subclasses to properly log
107 * a record wherever it need to be logged. If it is not possible to
108 * log the message properly, an exception should be thrown and will
109 * be caught by the caller.
110 *
111 * @param record Record containing information about the message.
112 */
113 virtual void do_log(const Record &record) = 0;
114
115 /**
116 * Flags if log messages should be formatted (prefixed with log level,
117 * timestamp, etc) before logging.
118 */
120
121 /**
122 * Log level set for the handler.
123 */
125
126 /**
127 * Timestamp precision for logging
128 */
130
131 bool has_logged_{false};
132};
133
134/**
135 * Handler to write to an output stream.
136 *
137 * @code
138 * Logger logger("my_module");
139 * ...
140 * logger.add_handler(StreamHandler(std::clog));
141 * @endcode
142 */
143class HARNESS_EXPORT StreamHandler : public Handler {
144 public:
145 static constexpr const char *kDefaultName = "stream";
146
147 explicit StreamHandler(std::ostream &stream, bool format_messages = true,
149 LogTimestampPrecision timestamp_precision =
151
152 // for the stream handler there is nothing to do
153 void reopen(const std::string /*dst*/) override {}
154
155 protected:
156 std::ostream &stream_;
157 std::mutex stream_mutex_;
158
159 private:
160 void do_log(const Record &record) override;
161};
162
163/**
164 * Handler to write to a null device such as /dev/null (unix) or NUL (windows).
165 *
166 * This handler produces no output.
167 *
168 * @code
169 * Logger logger("my_module");
170 * ...
171 * logger.add_handler(NullHandler());
172 * @endcode
173 */
174class HARNESS_EXPORT NullHandler : public Handler {
175 public:
176 static constexpr const char *kDefaultName = "null";
177
178 explicit NullHandler(bool format_messages = true,
180 LogTimestampPrecision timestamp_precision =
182
183 // for the null handler there is nothing to do
184 void reopen(const std::string /*dst*/) override {}
185
186 private:
187 void do_log(const Record &record) override;
188};
189
190/**
191 * Handler that writes to a file.
192 *
193 * @code
194 * Logger logger("my_module");
195 * ...
196 * logger.add_handler(FileHandler("/var/log/router.log"));
197 * @endcode
198 */
199class HARNESS_EXPORT FileHandler : public StreamHandler {
200 public:
201 static constexpr const char *kDefaultName = "file";
202
203 explicit FileHandler(const Path &path, bool format_messages = true,
205 LogTimestampPrecision timestamp_precision =
207 ~FileHandler() override;
208
209 void reopen(const std::string dst = "") override;
210
211 private:
212 void do_log(const Record &record) override;
213
215 std::ofstream fstream_;
216};
217
218} // namespace logging
219
220} // namespace mysql_harness
221
222#endif /* MYSQL_HARNESS_LOGGER_HANDLER_INCLUDED */
Class representing a path in a file system.
Definition: filesystem.h:62
Handler that writes to a file.
Definition: handler.h:199
std::ofstream fstream_
Definition: handler.h:215
const Path file_path_
Definition: handler.h:214
Base class for log message handler.
Definition: handler.h:49
void set_timestamp_precision(LogTimestampPrecision precision)
Definition: handler.h:74
void has_logged(bool v)
Definition: handler.h:100
virtual void do_log(const Record &record)=0
Log message handler primitive.
virtual void reopen(const std::string dst="")=0
Request to reopen underlying log sink.
LogTimestampPrecision precision_
Timestamp precision for logging.
Definition: handler.h:129
LogLevel level_
Log level set for the handler.
Definition: handler.h:124
bool format_messages_
Flags if log messages should be formatted (prefixed with log level, timestamp, etc) before logging.
Definition: handler.h:119
Handler(const Handler &)=default
LogLevel get_level() const
Definition: handler.h:73
void set_level(LogLevel level)
Definition: handler.h:72
Handler & operator=(const Handler &)=default
bool has_logged() const
check if the handler has logged at least one record.
Definition: handler.h:92
Handler to write to a null device such as /dev/null (unix) or NUL (windows).
Definition: handler.h:174
void reopen(const std::string) override
Request to reopen underlying log sink.
Definition: handler.h:184
Handler to write to an output stream.
Definition: handler.h:143
void reopen(const std::string) override
Request to reopen underlying log sink.
Definition: handler.h:153
std::ostream & stream_
Definition: handler.h:156
std::mutex stream_mutex_
Definition: handler.h:157
Logging interface for using and extending the logging subsystem.
static char * path
Definition: mysqldump.cc:148
static int record
Definition: mysqltest.cc:194
LogLevel
Log level values.
Definition: logging.h:95
LogTimestampPrecision
Log timestamp precision values.
Definition: logging.h:160
Definition: common.h:41
static int handle(int sql_errno, const char *sqlstate, const char *message, void *state)
Bridge function between the C++ API offered by this module and the C API of the parser service.
Definition: services.cc:63
Log record containing information collected by the logging system.
Definition: logging.h:182