MySQL  8.0.18
Source Code Documentation
log_builtins_imp.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
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 also distributed 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 included with MySQL.
13 
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18 
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef LOG_BUILTINS_IMP_H
24 #define LOG_BUILTINS_IMP_H
25 
26 #include <stdarg.h>
27 
28 #ifdef IN_DOXYGEN
30 #endif
31 
32 /**
33  This defines built-in functions for use by logging services.
34  These helpers are organized into a number of APIs grouping
35  related functionality.
36 
37  This file defines internals; to use the logger from a service,
38  include log_builtins.h instead.
39 
40  For documentation of the individual functions, see log_builtins.cc
41 */
42 
44 
49 };
50 
52  LOG_ERROR_STAGE_BUFFERING_EARLY, ///< no log-destination yet
53  LOG_ERROR_STAGE_BUFFERING_UNIPLEX, ///< 1 sink, or individual files
54  LOG_ERROR_STAGE_BUFFERING_MULTIPLEX, ///< 2+ sinks writing to stderr
55  LOG_ERROR_STAGE_EXTERNAL_SERVICES_AVAILABLE, ///< external services available
56  LOG_ERROR_STAGE_SHUTTING_DOWN ///< no external components
57 };
58 
59 /// Set error-logging stage hint (e.g. are loadable services available yet?).
61 
62 /// What mode is error-logging in (e.g. are loadable services available yet)?
64 
65 /**
66  Name of internal filtering engine (so we may recognize it when the
67  user refers to it by name in log_error_services).
68 */
69 #define LOG_BUILTINS_FILTER "log_filter_internal"
70 
71 /**
72  Name of internal log writer (so we may recognize it when the user
73  refers to it by name in log_error_services).
74 */
75 #define LOG_BUILTINS_SINK "log_sink_internal"
76 
77 /**
78  Name of buffered log writer. This sink is used internally during
79  start-up until we know where to write and how to filter, and have
80  all the components to do so. While we don't let the DBA add this
81  sink to the logging pipeline once we're out of start-up, we have
82  a name for this to be able to correctly tag its record in the
83  service-cache.
84 */
85 #define LOG_BUILTINS_BUFFER "log_sink_buffer"
86 
87 /**
88  Default services pipeline for log_builtins_error_stack().
89 */
90 #define LOG_ERROR_SERVICES_DEFAULT LOG_BUILTINS_FILTER "; " LOG_BUILTINS_SINK
91 
92 /**
93  Release all buffered log-events (discard_error_log_messages()),
94  optionally after running them through the error log stack first
95  (flush_error_log_messages()). Safe to call repeatedly (though
96  subsequent calls will only output anything if further events
97  occurred after the previous flush).
98 
99  @param mode LOG_BUFFER_DISCARD_ONLY (to just
100  throw away the buffered events), or
101  LOG_BUFFER_PROCESS_AND_DISCARD to
102  filter/print them first, or
103  LOG_BUFFER_REPORT_AND_KEEP to print
104  an intermediate report on time-out
105 */
107 
108 /**
109  Maximum number of key/value pairs in a log event.
110  May be changed or abolished later.
111 */
112 #define LOG_ITEM_MAX 64
113 
114 /**
115  Iterator over the key/value pairs of a log_line.
116  At present, only one iter may exist per log_line.
117 */
118 typedef struct _log_item_iter {
119  struct _log_line *ll; ///< log_line this is the iter for
120  int index; ///< index of current key/value pair
121 } log_item_iter;
122 
123 /**
124  log_line ("log event")
125 */
126 typedef struct _log_line {
127  log_item_type_mask seen; ///< bit field flagging item-types contained
128  log_item_iter iter; ///< iterator over key/value pairs
129  int count; ///< number of key/value pairs ("log items")
130  log_item item[LOG_ITEM_MAX]; ///< log items
131 } log_line;
132 
133 // see include/mysql/components/services/log_builtins.h
134 
135 /**
136  Primitives for services to interact with the structured logger:
137  functions pertaining to log_line and log_item data
138 */
140  public: /* Service Implementations */
142  static DEFINE_METHOD(int, wellknown_by_name,
143  (const char *key, size_t length));
145  static DEFINE_METHOD(const char *, wellknown_get_name, (uint i));
146 
147  static DEFINE_METHOD(int, item_inconsistent, (log_item * li));
148  static DEFINE_METHOD(bool, item_generic_type, (log_item_type t));
151 
152  static DEFINE_METHOD(bool, item_set_int, (log_item_data * lid, longlong i));
153  static DEFINE_METHOD(bool, item_set_float, (log_item_data * lid, double f));
154  static DEFINE_METHOD(bool, item_set_lexstring,
155  (log_item_data * lid, const char *s, size_t s_len));
156  static DEFINE_METHOD(bool, item_set_cstring,
157  (log_item_data * lid, const char *s));
158 
160  (log_item * li, log_item_type t, const char *key,
161  uint32 alloc));
163  (log_item * li, log_item_type t));
164 
166  (log_line * ll, log_item_type t, const char *key,
167  uint32 alloc));
169  (log_line * ll, log_item_type t));
170 
171  static DEFINE_METHOD(log_line *, line_init, ());
172  static DEFINE_METHOD(void, line_exit, (log_line * ll));
173  static DEFINE_METHOD(int, line_item_count, (log_line * ll));
174 
176  (log_line * ll, log_item_type_mask m));
177 
179  (log_line * ll));
180  static DEFINE_METHOD(void, line_item_iter_release, (log_item_iter * it));
184  (log_item_iter * it));
185 
186  static DEFINE_METHOD(int, line_submit, (log_line * ll));
187 
188  static DEFINE_METHOD(int, message, (int log_type, ...));
189 
190  static DEFINE_METHOD(int, sanitize, (log_item * li));
191 
192  static DEFINE_METHOD(const char *, errmsg_by_errcode, (int mysql_errcode));
193 
194  static DEFINE_METHOD(longlong, errcode_by_errsymbol, (const char *sym));
195 
196  static DEFINE_METHOD(const char *, label_from_prio, (int prio));
197 
198  static DEFINE_METHOD(int, open_errstream,
199  (const char *file, void **my_errstream));
200 
201  static DEFINE_METHOD(int, write_errstream,
202  (void *my_errstream, const char *buffer, size_t length));
203 
204  static DEFINE_METHOD(int, dedicated_errstream, (void *my_errstream));
205 
206  static DEFINE_METHOD(int, close_errstream, (void **my_errstream));
207 };
208 
209 /**
210  String primitives for logging services.
211 */
213  public: /* Service Implementations */
214  static DEFINE_METHOD(void *, malloc, (size_t len));
215  static DEFINE_METHOD(char *, strndup, (const char *fm, size_t len));
216  static DEFINE_METHOD(void, free, (void *ptr));
217  static DEFINE_METHOD(size_t, length, (const char *s));
218  static DEFINE_METHOD(char *, find_first, (const char *s, int c));
219  static DEFINE_METHOD(char *, find_last, (const char *s, int c));
220 
221  static DEFINE_METHOD(int, compare,
222  (const char *a, const char *b, size_t len,
223  bool case_insensitive));
224 
225  static DEFINE_METHOD(size_t, substitutev,
226  (char *to, size_t n, const char *fmt, va_list ap))
227  MY_ATTRIBUTE((format(printf, 3, 0)));
228 
229  static DEFINE_METHOD(size_t, substitute,
230  (char *to, size_t n, const char *fmt, ...))
231  MY_ATTRIBUTE((format(printf, 3, 4)));
232 };
233 
234 /**
235  Temporary primitives for logging services.
236 */
238  public: /* Service Implementations */
239  static DEFINE_METHOD(size_t, notify_client,
240  (void *thd, uint severity, uint code, char *to, size_t n,
241  const char *format, ...))
242  MY_ATTRIBUTE((format(printf, 6, 7)));
243 };
244 
245 /**
246  Syslog/Eventlog functions for logging services.
247 */
249  public: /* Service Implementations */
250  static DEFINE_METHOD(int, open, (const char *name, int option, int facility));
251  static DEFINE_METHOD(int, write, (enum loglevel level, const char *msg));
252  static DEFINE_METHOD(int, close, (void));
253 };
254 
255 #endif /* LOG_BUILTINS_IMP_H */
static bool item_string_class(log_item_class c) noexcept
Predicate used to determine whether a class is a string class (C-string or Lex-string).
Definition: log_builtins.cc:2766
void log_sink_buffer_flush(enum log_sink_buffer_flush_mode mode)
Release all buffered log-events (discard_error_log_messages()), optionally after running them through...
Definition: log_builtins.cc:1584
static int wellknown_by_type(log_item_type t) noexcept
See whether a type is wellknown.
Definition: log_builtins.cc:2678
struct _log_line log_line
log_line ("log event")
static int write(enum loglevel level, const char *msg) noexcept
Wrapper for mysys&#39; my_syslog.
Definition: log_builtins.cc:3666
no external components
Definition: log_builtins_imp.h:56
static log_item_type wellknown_get_type(uint i) noexcept
Accessor: from a record describing a wellknown key, get its type.
Definition: log_builtins.cc:2704
static log_item * line_item_iter_first(log_item_iter *it) noexcept
Use the log_line iterator to get the first item from the set.
Definition: log_builtins.cc:3080
const string name("\ame\)
char buffer[STRING_BUFFER]
Definition: test_sql_9_sessions.cc:57
log_sink_buffer_flush_mode
This defines built-in functions for use by logging services.
Definition: log_builtins_imp.h:45
log_item_type_mask seen
bit field flagging item-types contained
Definition: log_builtins_imp.h:127
Definition: log_shared.h:183
static void free(void *ptr) noexcept
Wrapper for my_free() - free allocated memory.
Definition: log_builtins.cc:3511
Definition: log_builtins_imp.h:47
static size_t substitutev(char *to, size_t n, const char *fmt, va_list ap) noexcept
Wrapper for vsnprintf() Replace all % in format string with variables from list.
Definition: log_builtins.cc:3578
enum enum_log_item_type log_item_type
item_type – what to log
static void line_item_iter_release(log_item_iter *it) noexcept
Release an iterator for the items in a log_line.
Definition: log_builtins.cc:3065
static char * find_first(const char *s, int c) noexcept
Wrapper for strchr() - find character in string, from the left.
Definition: log_builtins.cc:3526
uint64 log_item_type_mask
a bit mask of log_types.
Definition: log_shared.h:213
log_line ("log event")
Definition: log_builtins_imp.h:126
enum log_error_stage log_error_stage_get(void)
What mode is error-logging in (e.g. are loadable services available yet)?
Definition: log_builtins.cc:242
static bool item_numeric_class(log_item_class c) noexcept
Predicate used to determine whether a class is a numeric class (integer or float).
Definition: log_builtins.cc:2779
static int line_item_count(log_line *ll) noexcept
How many items are currently set on the given log_line?
Definition: log_builtins.cc:3020
static int open(const char *name, int option, int facility) noexcept
Wrapper for mysys&#39; my_openlog.
Definition: log_builtins.cc:3643
static log_item_data * item_set_with_key(log_item *li, log_item_type t, const char *key, uint32 alloc) noexcept
Create new log item with key name "key", and allocation flags of "alloc" (see enum_log_item_free).
Definition: log_builtins.cc:2884
static size_t substitute(char *to, size_t n, const char *fmt,...) noexcept
Wrapper for vsnprintf() Replace all % in format string with variables from list.
Definition: log_builtins.cc:3587
static int sanitize(log_item *li) noexcept
Definition: log_builtins.cc:3208
#define DEFINE_METHOD(retval, name, args)
int index
index of current key/value pair
Definition: log_builtins_imp.h:120
static char * find_last(const char *s, int c) noexcept
Wrapper for strrchr() - find character in string, from the right.
Definition: log_builtins.cc:3534
Definition: log_builtins_imp.h:48
static int message(int log_type,...) noexcept
Submit a log-message for log "log_type".
Definition: log_builtins.cc:3188
static int compare(const char *a, const char *b, size_t len, bool case_insensitive) noexcept
Compare two NUL-terminated byte strings.
Definition: log_builtins.cc:3562
static bool item_set_int(log_item_data *lid, longlong i) noexcept
Set an integer value on a log_item.
Definition: log_builtins.cc:2795
Syslog/Eventlog functions for logging services.
Definition: log_builtins_imp.h:248
structure to define some default "config_option" option settings
Definition: innodb_config.h:180
static int open_errstream(const char *file, void **my_errstream) noexcept
open an error log file
Definition: log_builtins.cc:3333
static const char * label_from_prio(int prio) noexcept
Convenience function: Derive a log label ("error", "warning", "information") from a severity...
Definition: log_builtins.cc:3308
static char * strndup(const char *fm, size_t len) noexcept
Wrapper for my_strndup()
Definition: log_builtins.cc:3504
static void * malloc(size_t len) noexcept
Wrapper for my_malloc()
Definition: log_builtins.cc:3490
static bool item_generic_type(log_item_type t) noexcept
Predicate used to determine whether a type is generic (generic string, generic float, generic integer) rather than a well-known type.
Definition: log_builtins.cc:2753
log_item item[LOG_ITEM_MAX]
log items
Definition: log_builtins_imp.h:130
static log_item_data * line_item_set(log_line *ll, log_item_type t) noexcept
Create a new log item of well-known type "t" in log line "ll".
Definition: log_builtins.cc:2990
static log_item * line_item_iter_next(log_item_iter *it) noexcept
Use the log_line iterator to get the next item from the set.
Definition: log_builtins.cc:3098
unsigned int uint
Definition: uca-dump.cc:29
1 sink, or individual files
Definition: log_builtins_imp.h:53
static log_item_data * item_set(log_item *li, log_item_type t) noexcept
As log_item_set_with_key(), except that the key is automatically derived from the wellknown log_item_...
Definition: log_builtins.cc:2920
long long int longlong
Definition: my_inttypes.h:54
int count
number of key/value pairs ("log items")
Definition: log_builtins_imp.h:129
uint32_t uint32
Definition: my_inttypes.h:66
Temporary primitives for logging services.
Definition: log_builtins_imp.h:237
char msg[1024]
Definition: test_sql_9_sessions.cc:281
static const char * key
Definition: suite_stubs.c:14
int n
Definition: xcom_base.c:425
static size_t length(const char *s) noexcept
Wrapper for strlen() - length of a nul-terminated byte string.
Definition: log_builtins.cc:3518
static void line_exit(log_line *ll) noexcept
Release a log_line allocated with line_init()
Definition: log_builtins.cc:3009
static int item_inconsistent(log_item *li) noexcept
Sanity check an item.
Definition: log_builtins.cc:2739
String primitives for logging services.
Definition: log_builtins_imp.h:212
static longlong errcode_by_errsymbol(const char *sym) noexcept
Return MySQL error code for a given error symbol.
Definition: log_builtins.cc:3293
static const char * wellknown_get_name(uint i) noexcept
Accessor: from a record describing a wellknown key, get its name.
Definition: log_builtins.cc:2715
static int line_submit(log_line *ll) noexcept
Complete, filter, and write submitted log items.
Definition: log_builtins.cc:3149
#define LOG_ITEM_MAX
Maximum number of key/value pairs in a log event.
Definition: log_builtins_imp.h:112
static int close_errstream(void **my_errstream) noexcept
close an error log file previously opened with open_errstream()
Definition: log_builtins.cc:3453
Definition: log_shared.h:193
static log_item_type_mask line_item_types_seen(log_line *ll, log_item_type_mask m) noexcept
Test whether a given type is presumed present on the log line.
Definition: log_builtins.cc:3034
no log-destination yet
Definition: log_builtins_imp.h:52
static int close(void) noexcept
Wrapper for mysys&#39; my_closelog.
Definition: log_builtins.cc:3683
external services available
Definition: log_builtins_imp.h:55
static int wellknown_by_name(const char *key, size_t length) noexcept
See whether a string is a wellknown field name.
Definition: log_builtins.cc:2693
Primitives for services to interact with the structured logger: functions pertaining to log_line and ...
Definition: log_builtins_imp.h:139
static log_item_iter * line_item_iter_acquire(log_line *ll) noexcept
Get an iterator for the items in a log_line.
Definition: log_builtins.cc:3047
loglevel
Definition: my_loglevel.h:32
Iterator over the key/value pairs of a log_line.
Definition: log_builtins_imp.h:118
struct _log_line * ll
log_line this is the iter for
Definition: log_builtins_imp.h:119
static bool item_set_cstring(log_item_data *lid, const char *s) noexcept
Set a string value on a log_item.
Definition: log_builtins.cc:2844
static bool item_set_float(log_item_data *lid, double f) noexcept
Set a floating point value on a log_item.
Definition: log_builtins.cc:2811
static int write_errstream(void *my_errstream, const char *buffer, size_t length) noexcept
write to an error log file previously opened with open_errstream()
Definition: log_builtins.cc:3412
static log_item_data * line_item_set_with_key(log_line *ll, log_item_type t, const char *key, uint32 alloc) noexcept
Create new log item in log line "ll", with key name "key", and allocation flags of "alloc" (see enum_...
Definition: log_builtins.cc:2959
static int dedicated_errstream(void *my_errstream) noexcept
are we writing to a dedicated errstream, or are we sharing it?
Definition: log_builtins.cc:3437
Definition: log_builtins_imp.h:46
static log_line * line_init() noexcept
Dynamically allocate and initialize a log_line.
Definition: log_builtins.cc:3000
static log_item * line_item_iter_current(log_item_iter *it) noexcept
Use the log_line iterator to get the current item from the set.
Definition: log_builtins.cc:3118
static bool item_set_lexstring(log_item_data *lid, const char *s, size_t s_len) noexcept
Set a string value on a log_item.
Definition: log_builtins.cc:2828
struct _log_item_iter log_item_iter
Iterator over the key/value pairs of a log_line.
log_error_stage
Definition: log_builtins_imp.h:51
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:75
void log_error_stage_set(enum log_error_stage les)
Set error-logging stage hint (e.g. are loadable services available yet?).
Definition: log_builtins.cc:237
enum enum_log_item_class log_item_class
static size_t notify_client(void *thd, uint severity, uint code, char *to, size_t n, const char *format,...) noexcept
Definition: log_builtins.cc:3604
static int log_type
Definition: mi_log.cc:46
log_item_iter iter
iterator over key/value pairs
Definition: log_builtins_imp.h:128
2+ sinks writing to stderr
Definition: log_builtins_imp.h:54
static const char * errmsg_by_errcode(int mysql_errcode) noexcept
Return MySQL error message for a given error code.
Definition: log_builtins.cc:3280