MySQL  8.0.18
Source Code Documentation
log_shared.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_SHARED_H
24 #define LOG_SHARED_H
25 
26 #include <mysql/mysql_lex_string.h>
27 
28 #include "my_basename.h"
29 #include "my_inttypes.h"
30 #include "my_loglevel.h"
31 
32 /** fallback: includer may not have set this to something sensible. */
33 #ifndef LOG_SUBSYSTEM_TAG
34 #define LOG_SUBSYSTEM_TAG NULL
35 #endif
36 
37 /**
38  The logging sub-system internally uses the log_line structure to pass
39  data around. This header primarily the specifics and symbols of that
40  structure.
41 
42  Within the server, those interfaces may be used, but it is usually
43  preferable to use the fluent C++ convenience class LogErr() instead
44  where possible (and the variadic convenience function log_message()
45  where it is not). (see sql/log.h).
46 
47  (The legacy calls sql_print_(error|warning|information) have now
48  been defined to use log_message().)
49 
50  Finally, this header defines log types (error log etc.) as well
51  as log item types (timestamp, message, ...) used by the logging
52  components; these are shared between the variadic convenience
53  functions (log_message(), sql_print_*()) as well as the lower
54  level services using the log_line structure.
55 */
56 
57 /*
58  By historical convention in the lex context,
59  CSTRING means "constant lex string (char * + size_t)",
60  not "C-style string" (char *, \0 terminated)!
61 */
63 
64 /**
65  log_type -- which log to send data to
66  check vs enum_log_table_type and LOG_FILE/LOG_TABLE/LOG_NONE
67 */
75 };
76 
77 /**
78  item_type -- what to log
79 
80 
81  Used by variadic convenience interface
82  log_message(), legacy sql_print_*(), legacy my_plugin_log_message().
83  Also available via the log_builtins service as message().
84 
85  (Wherever possible, use the fluent C++ wrapper LogErr() (see
86  log_builtins.h) instead, though.)
87 
88  LOG_ITEM_GEN_CSTRING lets the caller submit a \0 terminated,
89  C-style string for convenience; it will be converted to
90  lex style (char *, size_t) on submission.
91 
92  LOG_ITEM_END should not be used in the variadic interface
93  as submitting a log line without an actual message is discouraged.
94  Instead LOG_ITEM_LOG_MESSAGE or LOG_ITEM_LOG_LOOKUP should be used
95  as the last LOG_ITEM_* key-value pairs:
96 
97  - LOG_ITEM_LOG_MESSAGE can be used to submit an ad hoc message
98  directly while debugging.
99 
100  - LOG_ITEM_LOG_LOOKUP asks for the given error number to be
101  replaced by the associated error message (i.e. the error message
102  for the error number will be looked up, and the LOOKUP item will
103  be replaced by a MESSAGE one).
104 
105  In variadic submission, both ad hoc and well-known error messages
106  are considered printf()-style format strings, and should be followed
107  by any arguments/variables required by that format string.
108 
109  In some situations, the variadic interface will automatically
110  generate some items ("If you cannot afford a timestamp, one will
111  be provided for you."). If an item of the required type already
112  exists, the submission interface should not generate another.
113 
114  Old-style plug-ins using my_plugin_log_message() will automatically
115  be tagged with a default LOG_ITEM_MSC_COMPONENT of their plug-in name.
116 
117 
118 
119  Non-variadic interface
120 
121  In non-variadic submission (i.e. all functions accepting a log_line),
122  LOG_ITEM_LOG_LOOKUP and LOG_ITEM_GEN_CSTRING are not valid item types,
123  while LOG_ITEM_LOG_MESSAGE must already be a string literal (i.e. any
124  substitutions must already have taken place).
125 */
126 typedef enum enum_log_item_type {
127  LOG_ITEM_END = 0, /**< end of list, see above */
128  LOG_ITEM_LOG_TYPE = 1 << 0, /**< error log, etc. */
129  LOG_ITEM_SQL_ERRCODE = 1 << 1, /**< mysql error code (numeric) */
130  LOG_ITEM_SQL_ERRSYMBOL = 1 << 2, /**< mysql error code (symbolic) */
131  LOG_ITEM_SQL_STATE = 1 << 3, /**< SQL state */
132  LOG_ITEM_SYS_ERRNO = 1 << 4, /**< OS errno */
133  LOG_ITEM_SYS_STRERROR = 1 << 5, /**< OS strerror() */
134  LOG_ITEM_SRC_FILE = 1 << 6, /**< log called from file ... */
135  LOG_ITEM_SRC_LINE = 1 << 7, /**< log called from line ... */
136  LOG_ITEM_SRC_FUNC = 1 << 8, /**< log called from function ... */
137  LOG_ITEM_SRV_SUBSYS = 1 << 9, /**< log called from subsystem ... */
138  LOG_ITEM_SRV_COMPONENT = 1 << 10, /**< log called from component ... */
139  LOG_ITEM_MSC_USER = 1 << 11, /**< offending thread owned by ... */
140  LOG_ITEM_MSC_HOST = 1 << 12, /**< responsible user on host ... */
141  LOG_ITEM_SRV_THREAD = 1 << 13, /**< connection ID */
142  LOG_ITEM_SQL_QUERY_ID = 1 << 14, /**< query ID */
143  LOG_ITEM_SQL_TABLE_NAME = 1 << 15, /**< table name */
144  LOG_ITEM_LOG_PRIO = 1 << 16, /**< log priority (error, warn, ...) */
145  LOG_ITEM_LOG_LABEL = 1 << 17, /**< label, unless auto-derived */
146  LOG_ITEM_LOG_VERBATIM = 1 << 18, /**< the message, no % substitutions */
147  LOG_ITEM_LOG_MESSAGE = 1 << 19, /**< the message, format string */
148  LOG_ITEM_LOG_LOOKUP = 1 << 20, /**< insert message by error-code */
149  LOG_ITEM_LOG_TIMESTAMP = 1 << 21, /**< ISO8601 timestamp */
150  LOG_ITEM_LOG_BUFFERED = 1 << 22, /**< integer timestamp if/when buffered */
151  LOG_ITEM_LOG_SUPPRESSED = 1 << 23, /**< "and ... more" throttled */
152  LOG_ITEM_GEN_FLOAT = 1 << 24, /**< float not otherwise specified */
153  LOG_ITEM_GEN_INTEGER = 1 << 25, /**< integer not otherwise specified */
154  LOG_ITEM_GEN_LEX_STRING = 1 << 26, /**< lex string not otherwise specified */
155  LOG_ITEM_GEN_CSTRING = 1 << 27 /**< C-string not otherwise specified */
156 } log_item_type;
157 
158 /* some suggested keys for generic items */
159 
160 /** DIAGNOSTICS: for da->message_text() */
161 #define LOG_TAG_DIAG "DIAGNOSTICS"
162 
163 /** AUX: supplementary data not fitting any of the wellknown keys */
164 #define LOG_TAG_AUX "AUX"
165 
166 /* data type */
167 typedef enum enum_log_item_class {
168  LOG_UNTYPED = 0, /**< undefined */
169  LOG_CSTRING = 1, /**< string (char * + \0; variadic API only) */
170  LOG_INTEGER = 2, /**< integer (long long) */
171  LOG_FLOAT = 3, /**< float (double) */
172  LOG_LEX_STRING = 4 /**< string (char *, size_t) */
174 
175 /* do we need to release any parts of the item after use? */
180 };
181 
182 /* union: payload */
183 typedef union _log_item_data {
185  double data_float;
187 } log_item_data;
188 
189 /* item key: for now, a C-string */
190 typedef const char *log_item_key;
191 
192 /* log item: key/value */
193 typedef struct _log_item {
199 } log_item;
200 
201 /* service helpers */
202 typedef enum enum_log_item_error {
211 
212 /** a bit mask of log_types. standardizing the width to 64 bit. */
214 
215 /** log line: a collection of log items */
216 typedef struct _log_line log_line;
217 
218 /** log iter: an iterator over the collection of log items in a log line */
220 
221 /** advisory. components must not rely on others using the same value. */
222 #define LOG_BUFF_MAX 8192
223 
224 /** 26 for regular timestamp, plus 7 (".123456") when using micro-seconds */
225 static const int iso8601_size = 33;
226 
227 /**
228  index of first server error message: messages with this index or
229  higher are intended for the error log; messages below this index
230  are intended for the client
231 */
232 #define ER_SERVER_RANGE_START 10000
233 
234 #endif
connection ID
Definition: log_shared.h:141
Definition: log_shared.h:177
Definition: log_shared.h:73
enum_log_item_type
item_type – what to log
Definition: log_shared.h:126
Definition: log_shared.h:71
log called from component ...
Definition: log_shared.h:138
enum enum_log_item_error log_item_error
responsible user on host ...
Definition: log_shared.h:140
uint32 alloc
Definition: log_shared.h:198
offending thread owned by ...
Definition: log_shared.h:139
enum_log_type
log_type – which log to send data to check vs enum_log_table_type and LOG_FILE/LOG_TABLE/LOG_NONE ...
Definition: log_shared.h:68
Some integer typedefs for easier portability.
the message, no % substitutions
Definition: log_shared.h:146
Definition: log_shared.h:183
enum enum_log_item_type log_item_type
item_type – what to log
Definition: log_shared.h:179
struct _log_item log_item
integer not otherwise specified
Definition: log_shared.h:153
Definition: mysql_lex_string.h:39
label, unless auto-derived
Definition: log_shared.h:145
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
SQL state.
Definition: log_shared.h:131
double data_float
Definition: log_shared.h:185
Definition: log_shared.h:205
string (char *, size_t)
Definition: log_shared.h:172
Definition: log_shared.h:70
Definition: log_shared.h:208
log called from file ...
Definition: log_shared.h:134
insert message by error-code
Definition: log_shared.h:148
mysql error code (symbolic)
Definition: log_shared.h:130
log_item_class item_class
Definition: log_shared.h:195
Definition: log_shared.h:74
Definition: log_shared.h:204
static const int iso8601_size
26 for regular timestamp, plus 7 (".123456") when using micro-seconds
Definition: log_shared.h:225
"and ... more" throttled
Definition: log_shared.h:151
A macro that gives FILE without the directory name (e.g.
float not otherwise specified
Definition: log_shared.h:152
ISO8601 timestamp.
Definition: log_shared.h:149
LEX_CSTRING data_string
Definition: log_shared.h:186
long long int longlong
Definition: my_inttypes.h:54
log called from function ...
Definition: log_shared.h:136
union _log_item_data log_item_data
uint32_t uint32
Definition: my_inttypes.h:66
Definition: log_shared.h:178
mysql error code (numeric)
Definition: log_shared.h:129
log called from line ...
Definition: log_shared.h:135
Definition of the global "loglevel" enumeration.
log_item_type type
Definition: log_shared.h:194
lex string not otherwise specified
Definition: log_shared.h:154
Definition: log_shared.h:209
end of list, see above
Definition: log_shared.h:127
undefined
Definition: log_shared.h:168
query ID
Definition: log_shared.h:142
log_item_key key
Definition: log_shared.h:196
C-string not otherwise specified.
Definition: log_shared.h:155
string (char * + \0; variadic API only)
Definition: log_shared.h:169
Definition: log_shared.h:193
Definition: log_shared.h:206
OS strerror()
Definition: log_shared.h:133
Definition: log_shared.h:203
Definition: log_shared.h:207
OS errno.
Definition: log_shared.h:132
Iterator over the key/value pairs of a log_line.
Definition: log_builtins_imp.h:118
longlong data_integer
Definition: log_shared.h:184
integer (long long)
Definition: log_shared.h:170
the message, format string
Definition: log_shared.h:147
enum_log_item_error
Definition: log_shared.h:202
table name
Definition: log_shared.h:143
integer timestamp if/when buffered
Definition: log_shared.h:150
float (double)
Definition: log_shared.h:171
enum_log_item_class
Definition: log_shared.h:167
error log, etc.
Definition: log_shared.h:128
Definition: log_shared.h:69
uint64_t uint64
Definition: my_inttypes.h:68
log priority (error, warn, ...)
Definition: log_shared.h:144
enum enum_log_item_class log_item_class
Definition: log_shared.h:72
log_item_data data
Definition: log_shared.h:197
log called from subsystem ...
Definition: log_shared.h:137
enum_log_item_free
Definition: log_shared.h:176
const char * log_item_key
Definition: log_shared.h:190