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