MySQL 9.1.0
Source Code Documentation
gcs_logging.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 2024, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is designed to work with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have either included with
13 the program or referenced in the documentation.
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, version 2.0, 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#ifndef GCS_LOGGING_INCLUDED
25#define GCS_LOGGING_INCLUDED
26
27#include <atomic>
28#include <cstdint>
29#include <string>
30
32
33/**
34 @class Common_interface
35
36 Common interface that is used to define the sink and logger interfaces.
37*/
39 public:
40 /**
41 Define a virtual destructor as instances of this interface can be
42 polymorphically used.
43 */
44
45 virtual ~Common_interface() = default;
46
47 /**
48 The purpose of this method is to initialize resources used by the objects
49 that implement this interface.
50
51 @retval GCS_OK in case everything goes well. Any other value of
52 gcs_error in case of error.
53 */
54
56
57 /**
58 The purpose of this method is to free any resources used by the objects
59 that implement this interface.
60
61 @retval GCS_OK in case everything goes well. Any other value of
62 gcs_error in case of error.
63 */
64
65 virtual enum_gcs_error finalize() = 0;
66};
67
68/**
69 @class Sink_interface
70
71 Common sink that may be shared by the logging and debugging systems.
72*/
73
75 public:
76 /**
77 Define a virtual destructor as instances of this interface can be
78 polymorphically used.
79 */
80
81 ~Sink_interface() override = default;
82
83 /**
84 The purpose of this method is to effectively log the information.
85
86 @param[in] message the message to log
87 */
88
89 virtual void log_event(const std::string &message) = 0;
90
91 /**
92 The purpose of this method is to effectively log the information.
93
94 @param[in] message the message to log
95 @param[in] message_size message size to log
96 */
97
98 virtual void log_event(const char *message, size_t message_size) = 0;
99
100 /**
101 The purpose of this method is to return information on the sink such
102 as its location.
103 */
104
105 virtual const std::string get_information() const = 0;
106};
107
108typedef enum {
114
115static const char *const gcs_log_levels[] = {
116 "[MYSQL_GCS_FATAL] ", "[MYSQL_GCS_ERROR] ", "[MYSQL_GCS_WARN] ",
117 "[MYSQL_GCS_INFO] "};
118
119/**
120 @class Logger_interface
121
122 Logger interface that must be used to define a logger object.
123*/
124
126 public:
127 /**
128 Define a virtual destructor as instances of this interface can be
129 polymorphically used.
130 */
131
132 ~Logger_interface() override = default;
133
134 /**
135 The purpose of this method is to deliver to the logging system any message
136 to be logged.
137
138 @param[in] level logging level of message
139 @param[in] message the message to be logged
140 */
141
142 virtual void log_event(const gcs_log_level_t level,
143 const std::string &message) = 0;
144};
145
146/**
147 @class Gcs_log_manager
148
149 This class sets up and configures the logging infrastructure, storing the
150 logger to be used by the application as a singleton.
151*/
152
154 private:
156
157 public:
158 /**
159 Set the logger object and initialize it by invoking its initialization
160 method.
161
162 This allows any resources needed by the logging system to be initialized,
163 and ensures its usage throughout the lifecycle of the current application,
164 i.e. GCS.
165
166 @param[in] logger logging system
167 @retval GCS_OK in case everything goes well. Any other value of
168 gcs_error in case of error.
169 */
170
172
173 /**
174 Get a reference to the logger object if there is any.
175
176 @return The current logging system.
177
178 */
179
181
182 /**
183 Free any resource used in the logging system.
184
185 @retval GCS_OK in case everything goes well. Any other value of
186 gcs_error in case of error.
187 */
188
189 static enum_gcs_error finalize();
190};
191
192/*
193 These two definitions contain information on the valid debug options. If
194 one wants to add a new option both definitions must be changed.
195
196 Any new option must be added before the GCS_DEBUG_ALL and gaps in the
197 numbers are not allowed. Adding a new debug option, e.g. GCS_DEBUG_THREAD,
198 would result in the following definitions:
199
200 typedef enum
201 {
202 GCS_DEBUG_NONE = 0x00000000,
203 GCS_DEBUG_BASIC = 0x00000001,
204 GCS_DEBUG_TRACE = 0x00000002,
205 XCOM_DEBUG_BASIC = 0x00000004,
206 XCOM_DEBUG_TRACE = 0x00000008,
207 GCS_INVALID_DEBUG = ~(0x7FFFFFFF),
208 GCS_DEBUG_ALL = ~(GCS_DEBUG_NONE)
209 } gcs_xcom_debug_option_t;
210
211
212 static const char* const gcs_xcom_debug_strings[]=
213 {
214 "GCS_DEBUG_BASIC",
215 "GCS_DEBUG_TRACE",
216 "XCOM_DEBUG_BASIC",
217 "XCOM_DEBUG_TRACE",
218 "GCS_DEBUG_ALL",
219 "GCS_DEBUG_NONE"
220 };
221*/
222#if !defined(GCS_XCOM_DEBUG_INFORMATION)
223#define GCS_XCOM_DEBUG_INFORMATION
224/*
225This code is duplicated in the xcom_logger.h file. So if you make any change
226here, remember to update the aforementioned file. Note that XCOM is written
227in C which uses a 32 bit integer as the type for the enumeration and although
228the code is prepared to handle 64 bits, the enumeration in both the GCS (i.e.
229C++) and XCOM (i.e. C) is restricted to 32 bits.
230
231Assuming that we are not using all bits available to define a debug level,
232GCS_INVALID_DEBUG will give us the last possible entry that is not used.
233
234The GCS_DEBUG_NONE, GCS_DEBUG_ALL and GCS_INVALID_DEBUG are options that apply
235to both GCS and XCOM but we don't prefix it with XCOM to avoid big names.
236*/
237typedef enum {
238 GCS_DEBUG_NONE = 0x00000000,
239 GCS_DEBUG_BASIC = 0x00000001,
240 GCS_DEBUG_TRACE = 0x00000002,
241 XCOM_DEBUG_BASIC = 0x00000004,
242 XCOM_DEBUG_TRACE = 0x00000008,
243 GCS_DEBUG_MSG_FLOW = 0x00000010,
245 GCS_INVALID_DEBUG = ~(0x7FFFFFFF),
248
249static const char *const gcs_xcom_debug_strings[] = {
250 "GCS_DEBUG_BASIC", "GCS_DEBUG_TRACE", "XCOM_DEBUG_BASIC",
251 "XCOM_DEBUG_TRACE", "GCS_DEBUG_MSG_FLOW", "XCOM_DEBUG_MSG_FLOW",
252 "GCS_DEBUG_ALL", "GCS_DEBUG_NONE",
253};
254
255/*
256 Assuming that we are not using all bits available to define a debug
257 level, this will give us the last possible entry that is not used.
258*/
259#endif
260
261/**
262 @class Gcs_debug_manager
263
264 This class sets up and configures the debugging infrastructure, storing the
265 debugger to be used by the application as a singleton.
266*/
267
269 private:
270 /**
271 The debug level enabled which is by default GCS_DEBUG_NONE;
272 */
273 static std::atomic<std::int64_t> m_debug_options;
274
275 /**
276 String that represents the GCS_DEBUG_NONE;
277 */
278 static const std::string m_debug_none;
279
280 /**
281 String that represents the GCS_DEBUG_ALL;
282 */
283 static const std::string m_debug_all;
284
285 public:
286 /**
287 Atomically load information on debug options.
288 */
289
290 static inline int64_t load_debug_options() {
291 /*
292 We don't need anything stronger than "memory order relaxed" because
293 we are only interested in reading and updating a single variable
294 atomically.
295 */
296 return m_debug_options.load(std::memory_order_relaxed);
297 }
298
299 /**
300 Atomically store information on debug options.
301 */
302
303 static inline void store_debug_options(int64_t debug_options) {
304 /*
305 We don't need anything stronger than "memory order relaxed" because
306 we are only interested in reading and updating a single variable
307 atomically.
308 */
309 m_debug_options.store(debug_options, std::memory_order_relaxed);
310 }
311
312 /**
313 Verify whether any of the debug options are defined.
314
315 @param debug_options Set of debug options to be verified.
316
317 @retval true if it is, false otherwise.
318 */
319
320 static inline bool test_debug_options(const int64_t debug_options) {
321 return load_debug_options() & debug_options;
322 }
323
324 /**
325 Get the current set of debug options.
326 */
327
328 static int64_t get_current_debug_options();
329
330 /**
331 Get the current set of debug options as an integer value and as a
332 string separated by comma.
333
334 @param[out] res_debug_options String containing the result
335 */
336
337 static int64_t get_current_debug_options(std::string &res_debug_options);
338
339 /**
340 Get the set of valid debug options excluding GCS_DEBUG_NONE and
341 GCS_DEBUG_ALL.
342 */
343
344 static int64_t get_valid_debug_options();
345
346 /**
347 Check whether the set of debug options is valid or not including
348 GCS_DEBUG_NONE and GCS_DEBUG_ALL.
349
350 @param[in] debug_options Set of debug options
351 @retval true if success, false otherwise
352 */
353
354 static bool is_valid_debug_options(const int64_t debug_options);
355
356 /**
357 Check whether the set of debug options is valid or not including
358 GCS_DEBUG_NONE and GCS_DEBUG_ALL.
359
360 @param[in] debug_options Set of debug options
361 @retval false if success, true otherwise.
362 */
363
364 static bool is_valid_debug_options(const std::string &debug_options);
365
366 /**
367 Get the set of debug options passed as parameter as an unsigned integer.
368
369 If there is any invalid debug option in the debug_options parameter, true
370 is returned.
371
372 @param[in] debug_options Set of debug options
373 @param[out] res_debug_options Unsigned integer that contains the result
374 @retval false if success, true otherwise.
375 */
376
377 static bool get_debug_options(const std::string &debug_options,
378 int64_t &res_debug_options);
379
380 /**
381 Get the set of debug options passed as parameter as a string.
382
383 If there is any invalid debug option in the debug_options parameter, true
384 is returned.
385
386 @param[in] debug_options Set of debug options
387 @param[out] res_debug_options String that contains the result
388 @retval false if success, true otherwise.
389 */
390 static bool get_debug_options(const int64_t debug_options,
391 std::string &res_debug_options);
392
393 /**
394 Get the the number of possible debug options.
395 */
396
397 static unsigned int get_number_debug_options();
398
399 /**
400 Extend the current set of debug options with new debug options expressed as
401 an integer parameter.
402
403 If there is any invalid debug option in the debug_options parameter, true
404 is returned and nothing is changed.
405
406 @param[in] debug_options Set of debug options to be added
407 @retval false if success, true otherwise.
408 */
409
410 static bool set_debug_options(const int64_t debug_options);
411
412 /**
413 Change the current set of debug options by the new debug options expressed
414 as an integer parameter.
415
416 If there is any invalid debug option in the debug_options parameter, true
417 is returned and nothing is changed.
418
419 @param[in] debug_options Set of debug options to be defined
420 @retval false if success, true otherwise.
421 */
422
423 static bool force_debug_options(const int64_t debug_options);
424
425 /**
426 Extend the current set of debug options with new debug options expressed
427 as a string.
428
429 If there is any invalid debug option in the debug_options parameter, true
430 is returned and nothing is changed.
431
432 @param[in] debug_options Set of debug options to be added
433 @retval false if success, true otherwise.
434 */
435
436 static bool set_debug_options(const std::string &debug_options);
437
438 /**
439 Changed the current set of debug options by the new debug options expressed
440 as a string.
441
442 If there is any invalid debug option in the debug_options parameter, true
443 is returned and nothing is changed.
444
445 @param[in] debug_options Set of debug options to be defined
446 @retval false if success, true otherwise.
447
448 */
449
450 static bool force_debug_options(const std::string &debug_options);
451
452 /**
453 Reduce the current set of debug options by disabling the debug options
454 expressed as an integer parameter.
455
456 If there is any invalid debug option in the debug_options parameter, true
457 is returned and nothing is changed.
458
459 @param[in] debug_options Set of debug options to be disabled
460 @retval false if success, true otherwise.
461 */
462
463 static bool unset_debug_options(const int64_t debug_options);
464
465 /**
466 Reduce the current set of debug options by disabling the debug options
467 expressed as a string.
468
469 If there is any invalid debug option in the debug_options parameter, true
470 is returned and nothing is changed.
471
472 @param[in] debug_options Set of debug options to be disabled
473 @retval false if success, true otherwise.
474 */
475
476 static bool unset_debug_options(const std::string &debug_options);
477};
478#endif /* GCS_LOGGING_INCLUDED */
Common interface that is used to define the sink and logger interfaces.
Definition: gcs_logging.h:38
virtual ~Common_interface()=default
Define a virtual destructor as instances of this interface can be polymorphically used.
virtual enum_gcs_error finalize()=0
The purpose of this method is to free any resources used by the objects that implement this interface...
virtual enum_gcs_error initialize()=0
The purpose of this method is to initialize resources used by the objects that implement this interfa...
Definition: gcs_logging.h:268
static bool force_debug_options(const int64_t debug_options)
Change the current set of debug options by the new debug options expressed as an integer parameter.
Definition: gcs_logging.cc:203
static unsigned int get_number_debug_options()
Get the the number of possible debug options.
Definition: gcs_logging.cc:183
static const std::string m_debug_all
String that represents the GCS_DEBUG_ALL;.
Definition: gcs_logging.h:283
static bool test_debug_options(const int64_t debug_options)
Verify whether any of the debug options are defined.
Definition: gcs_logging.h:320
static std::atomic< std::int64_t > m_debug_options
The debug level enabled which is by default GCS_DEBUG_NONE;.
Definition: gcs_logging.h:273
static bool is_valid_debug_options(const int64_t debug_options)
Check whether the set of debug options is valid or not including GCS_DEBUG_NONE and GCS_DEBUG_ALL.
Definition: gcs_logging.cc:75
static int64_t load_debug_options()
Atomically load information on debug options.
Definition: gcs_logging.h:290
static int64_t get_valid_debug_options()
Get the set of valid debug options excluding GCS_DEBUG_NONE and GCS_DEBUG_ALL.
Definition: gcs_logging.cc:63
static void store_debug_options(int64_t debug_options)
Atomically store information on debug options.
Definition: gcs_logging.h:303
static const std::string m_debug_none
String that represents the GCS_DEBUG_NONE;.
Definition: gcs_logging.h:278
static int64_t get_current_debug_options()
Get the current set of debug options.
Definition: gcs_logging.cc:88
static bool get_debug_options(const std::string &debug_options, int64_t &res_debug_options)
Get the set of debug options passed as parameter as an unsigned integer.
Definition: gcs_logging.cc:134
static bool unset_debug_options(const int64_t debug_options)
Reduce the current set of debug options by disabling the debug options expressed as an integer parame...
Definition: gcs_logging.cc:227
static bool set_debug_options(const int64_t debug_options)
Extend the current set of debug options with new debug options expressed as an integer parameter.
Definition: gcs_logging.cc:187
This class sets up and configures the logging infrastructure, storing the logger to be used by the ap...
Definition: gcs_logging.h:153
static enum_gcs_error finalize()
Free any resource used in the logging system.
Definition: gcs_logging.cc:44
static Logger_interface * m_logger
Definition: gcs_logging.h:155
static Logger_interface * get_logger()
Get a reference to the logger object if there is any.
Definition: gcs_logging.cc:37
static enum_gcs_error initialize(Logger_interface *logger)
Set the logger object and initialize it by invoking its initialization method.
Definition: gcs_logging.cc:39
Logger interface that must be used to define a logger object.
Definition: gcs_logging.h:125
virtual void log_event(const gcs_log_level_t level, const std::string &message)=0
The purpose of this method is to deliver to the logging system any message to be logged.
~Logger_interface() override=default
Define a virtual destructor as instances of this interface can be polymorphically used.
Common sink that may be shared by the logging and debugging systems.
Definition: gcs_logging.h:74
virtual void log_event(const char *message, size_t message_size)=0
The purpose of this method is to effectively log the information.
~Sink_interface() override=default
Define a virtual destructor as instances of this interface can be polymorphically used.
virtual const std::string get_information() const =0
The purpose of this method is to return information on the sink such as its location.
virtual void log_event(const std::string &message)=0
The purpose of this method is to effectively log the information.
static const char *const gcs_log_levels[]
Definition: gcs_logging.h:115
static const char *const gcs_xcom_debug_strings[]
Definition: gcs_logging.h:249
gcs_xcom_debug_option_t
Definition: gcs_logging.h:237
@ XCOM_DEBUG_TRACE
Definition: gcs_logging.h:242
@ GCS_DEBUG_TRACE
Definition: gcs_logging.h:240
@ GCS_INVALID_DEBUG
Definition: gcs_logging.h:245
@ GCS_DEBUG_MSG_FLOW
Definition: gcs_logging.h:243
@ GCS_DEBUG_ALL
Definition: gcs_logging.h:246
@ XCOM_DEBUG_MSG_FLOW
Definition: gcs_logging.h:244
@ GCS_DEBUG_BASIC
Definition: gcs_logging.h:239
@ XCOM_DEBUG_BASIC
Definition: gcs_logging.h:241
@ GCS_DEBUG_NONE
Definition: gcs_logging.h:238
gcs_log_level_t
Definition: gcs_logging.h:108
@ GCS_FATAL
Definition: gcs_logging.h:109
@ GCS_ERROR
Definition: gcs_logging.h:110
@ GCS_WARN
Definition: gcs_logging.h:111
@ GCS_INFO
Definition: gcs_logging.h:112
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:41
static Logger logger
The "top-level" logger used when no connection context is given.
Definition: test_trace_plugin.cc:296