MySQL 8.0.39
Source Code Documentation
|
Primitives for services to interact with the structured logger: functions pertaining to log_line and log_item data. More...
#include <log_builtins_imp.h>
Static Public Member Functions | |
static int | wellknown_by_type (log_item_type t) noexcept |
See whether a type is wellknown. More... | |
static int | wellknown_by_name (const char *key, size_t length) noexcept |
See whether a string is a wellknown field name. More... | |
static log_item_type | wellknown_get_type (uint i) noexcept |
Accessor: from a record describing a wellknown key, get its type. More... | |
static const char * | wellknown_get_name (uint i) noexcept |
Accessor: from a record describing a wellknown key, get its name. More... | |
static int | item_inconsistent (log_item *li) noexcept |
Sanity check an item. More... | |
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. More... | |
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). More... | |
static bool | item_numeric_class (log_item_class c) noexcept |
Predicate used to determine whether a class is a numeric class (integer or float). More... | |
static bool | item_set_int (log_item_data *lid, longlong i) noexcept |
Set an integer value on a log_item. More... | |
static bool | item_set_float (log_item_data *lid, double f) noexcept |
Set a floating point value on a log_item. More... | |
static bool | item_set_lexstring (log_item_data *lid, const char *s, size_t s_len) noexcept |
static bool | item_set_cstring (log_item_data *lid, const char *s) noexcept |
Set a string value on a log_item. More... | |
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). More... | |
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_type t. More... | |
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_log_item_free). More... | |
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". More... | |
static log_line * | line_init () noexcept |
Dynamically allocate and initialize a log_line. More... | |
static void | line_exit (log_line *ll) noexcept |
Release a log_line allocated with line_init() More... | |
static int | line_item_count (log_line *ll) noexcept |
How many items are currently set on the given log_line? More... | |
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. More... | |
static log_item * | line_get_output_buffer (log_line *ll) noexcept |
Get log-line's output buffer. More... | |
static log_item_iter * | line_item_iter_acquire (log_line *ll) noexcept |
Get an iterator for the items in a log_line. More... | |
static void | line_item_iter_release (log_item_iter *it) noexcept |
Release an iterator for the items in a log_line. More... | |
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. More... | |
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. More... | |
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. More... | |
static int | line_submit (log_line *ll) noexcept |
Complete, filter, and write submitted log items. More... | |
static int | message (int log_type,...) noexcept |
Submit a log-message for log "log_type". More... | |
static int | sanitize (log_item *li) noexcept |
static const char * | errmsg_by_errcode (int mysql_errcode) noexcept |
Return MySQL error message for a given error code. More... | |
static longlong | errcode_by_errsymbol (const char *sym) noexcept |
Return MySQL error code for a given error symbol. More... | |
static const char * | label_from_prio (int prio) noexcept |
Convenience function: Derive a log label ("error", "warning", "information") from a severity. More... | |
static ulonglong | parse_iso8601_timestamp (const char *timestamp, size_t len) noexcept |
Parse a ISO8601 timestamp and return the number of microseconds since the epoch. More... | |
static log_service_error | open_errstream (const char *file, void **my_errstream) noexcept |
Open an error log file. More... | |
static log_service_error | write_errstream (void *my_errstream, const char *buffer, size_t length) noexcept |
Write to an error log file previously opened with open_errstream(). More... | |
static int | dedicated_errstream (void *my_errstream) noexcept |
Are we writing to a dedicated errstream, or are we sharing it? More... | |
static log_service_error | close_errstream (void **my_errstream) noexcept |
Close an error log file previously opened with open_errstream() (wrapper for the component system). More... | |
static log_service_error | reopen_errstream (const char *file, void **my_errstream) noexcept |
Re-open an error log file (primarily to facilitate flush/log-rotation) More... | |
Primitives for services to interact with the structured logger: functions pertaining to log_line and log_item data.
|
staticnoexcept |
Close an error log file previously opened with open_errstream() (wrapper for the component system).
my_errstream | a handle describing the log file |
|
staticnoexcept |
Are we writing to a dedicated errstream, or are we sharing it?
my_errstream | a handle describing the log file |
<0 | error |
0 | not dedicated (multiplexed, stderr, ...) |
1 | dedicated |
|
staticnoexcept |
Return MySQL error code for a given error symbol.
sym | the symbol to look up |
-1 | failure |
>=0 | the MySQL error code |
|
staticnoexcept |
Return MySQL error message for a given error code.
mysql_errcode | the error code the message for which to look up |
the | message (a printf-style format string) |
|
staticnoexcept |
Predicate used to determine whether a type is generic (generic string, generic float, generic integer) rather than a well-known type.
t | log item type to examine |
true | if generic type |
false | if wellknown type |
|
staticnoexcept |
Sanity check an item.
Certain log sinks have very low requirements with regard to the data they receive; they write keys as strings, and then data according to the item's class (string, integer, or float), formatted to the sink's standards (e.g. JSON, XML, ...). Code that has higher requirements can use this check to see whether the given item is of a known type (whether generic or wellknown), whether the given type and class agree, and whether in case of a well-known type, the given key is correct for that type. If your code generates items that don't pass this check, you should probably go meditate on it.
li | the log_item to check |
0 | no problems |
-2 | unknown item type |
-3 | item_class derived from type isn't what's set on the item |
-4 | class not generic, so key should match wellknown |
|
staticnoexcept |
Predicate used to determine whether a class is a numeric class (integer or float).
c | log item class to examine |
true | if of a numeric class |
false | if not of a numeric class |
|
staticnoexcept |
As log_item_set_with_key(), except that the key is automatically derived from the wellknown log_item_type t.
Create new log item with type "t". Will return a pointer to the item's log_item_data struct for convenience. This is mostly interesting for filters and other services that create items that are not part of a log_line; sources etc. that intend to create an item for a log_line (the more common case) should usually use the below line_item_set_with_key() which creates an item (like this function does), but also correctly inserts it into a log_line.
The allocation of this item will be LOG_ITEM_FREE_NONE; specifically, any pre-existing value will be clobbered. It is therefore WRONG a) to use this on a log_item that already has a key; it should only be used on freshly init'd log_items; b) to use this on a log_item that already has a value (specifically, an allocated one); the correct order is to init a log_item, then set up type and key, and finally to set the value. If said value is an allocated string, the log_item's alloc should be bitwise or'd with LOG_ITEM_FREE_VALUE.
li | the log_item to work on |
t | the item-type |
a | pointer to the log_item's log_data, for easy chaining: log_item_set_with_key(...)->data_integer= 1; |
|
staticnoexcept |
Set a string value on a log_item.
Fails gracefully if no log_item_data is supplied, so it can safely wrap log_line_item_set[_with_key]().
lid | log_item_data struct to set the value on |
s | pointer to NTBS |
true | lid was nullptr (possibly: OOM, could not set up log_item) |
false | all's well |
|
staticnoexcept |
Set a floating point value on a log_item.
Fails gracefully if no log_item_data is supplied, so it can safely wrap log_line_item_set[_with_key]().
lid | log_item_data struct to set the value on |
f | float to set |
true | lid was nullptr (possibly: OOM, could not set up log_item) |
false | all's well |
|
staticnoexcept |
Set an integer value on a log_item.
Fails gracefully if no log_item_data is supplied, so it can safely wrap log_line_item_set[_with_key]().
lid | log_item_data struct to set the value on |
i | integer to set |
true | lid was nullptr (possibly: OOM, could not set up log_item) |
false | all's well |
|
staticnoexcept |
|
staticnoexcept |
Create new log item with key name "key", and allocation flags of "alloc" (see enum_log_item_free).
Will return a pointer to the item's log_item_data struct for convenience. This is mostly interesting for filters and other services that create items that are not part of a log_line; sources etc. that intend to create an item for a log_line (the more common case) should usually use the below line_item_set_with_key() which creates an item (like this function does), but also correctly inserts it into a log_line.
li | the log_item to work on |
t | the item-type |
key | the key to set on the item. ignored for non-generic types (may pass nullptr for those) see alloc |
alloc | LOG_ITEM_FREE_KEY if key was allocated by caller LOG_ITEM_FREE_NONE if key was not allocated Allocated keys will automatically free()d when the log_item is. The log_item's alloc flags will be set to the submitted value; specifically, any pre-existing value will be clobbered. It is therefore WRONG a) to use this on a log_item that already has a key; it should only be used on freshly init'd log_items; b) to use this on a log_item that already has a value (specifically, an allocated one); the correct order is to init a log_item, then set up type and key, and finally to set the value. If said value is an allocated string, the log_item's alloc should be bitwise or'd with LOG_ITEM_FREE_VALUE. |
a | pointer to the log_item's log_data, for easy chaining: log_item_set_with_key(...)->data_integer= 1; |
|
staticnoexcept |
Predicate used to determine whether a class is a string class (C-string or Lex-string).
c | log item class to examine |
true | if of a string class |
false | if not of a string class |
|
staticnoexcept |
Convenience function: Derive a log label ("error", "warning", "information") from a severity.
prio | the severity/prio in question |
Error | for prio of ERROR_LEVEL or higher |
Warning | for prio of WARNING_LEVEL |
Note | otherwise |
|
staticnoexcept |
Release a log_line allocated with line_init()
ll | a log_line previously allocated with line_init() |
Get log-line's output buffer.
If the logger core provides this buffer, the log-service may use it to assemble its output therein and implicitly return it to the core. Participation is required for services that support populating performance_schema.error_log, and optional for all others.
ll | the log_line to examine |
nullptr | success, an output buffer is available |
otherwise | failure, no output buffer is available |
|
staticnoexcept |
Dynamically allocate and initialize a log_line.
nullptr | could not set up buffer (too small?) |
other | address of the newly initialized log_line |
|
staticnoexcept |
How many items are currently set on the given log_line?
ll | the log-line to examine |
the | number of items set |
|
staticnoexcept |
Get an iterator for the items in a log_line.
For now, only one iterator may exist per log_line.
ll | the log_line to examine |
a | log_item_iter, or nullptr on failure |
|
staticnoexcept |
Use the log_line iterator to get the current item from the set.
it | the iterator to use |
pointer | to the current log_item in the collection, or nullptr |
|
staticnoexcept |
Use the log_line iterator to get the first item from the set.
it | the iterator to use |
pointer | to the first log_item in the collection, or nullptr |
|
staticnoexcept |
Use the log_line iterator to get the next item from the set.
it | the iterator to use |
pointer | to the next log_item in the collection, or nullptr |
|
staticnoexcept |
Release an iterator for the items in a log_line.
it | the iterator to release |
|
staticnoexcept |
Create a new log item of well-known type "t" in log line "ll".
On success, the number of registered items on the log line is increased, the item's type is added to the log_line's "seen" property, and a pointer to the item's log_item_data struct is returned for convenience.
The allocation of this item will be LOG_ITEM_FREE_NONE; specifically, any pre-existing value will be clobbered. It is therefore WRONG a) to use this on a log_item that already has a key; it should only be used on freshly init'd log_items; b) to use this on a log_item that already has a value (specifically, an allocated one); the correct order is to init a log_item, then set up type and key, and finally to set the value. If said value is an allocated string, the log_item's alloc should be bitwise or'd with LOG_ITEM_FREE_VALUE.
ll | the log_line to work on |
t | the item-type |
!nullptr | a pointer to the log_item's log_data, for easy chaining: line_item_set(...)->data_integer= 1; |
nullptr | could not create a log_item in given log_line |
|
staticnoexcept |
Create new log item in log line "ll", with key name "key", and allocation flags of "alloc" (see enum_log_item_free).
On success, the number of registered items on the log line is increased, the item's type is added to the log_line's "seen" property, and a pointer to the item's log_item_data struct is returned for convenience.
ll | the log_line to work on |
t | the item-type |
key | the key to set on the item. ignored for non-generic types (may pass nullptr for those) see alloc |
alloc | LOG_ITEM_FREE_KEY if key was allocated by caller LOG_ITEM_FREE_NONE if key was not allocated Allocated keys will automatically free()d when the log_item is. The log_item's alloc flags will be set to the submitted value; specifically, any pre-existing value will be clobbered. It is therefore WRONG a) to use this on a log_item that already has a key; it should only be used on freshly init'd log_items; b) to use this on a log_item that already has a value (specifically, an allocated one); the correct order is to init a log_item, then set up type and key, and finally to set the value. If said value is an allocated string, the log_item's alloc should be bitwise or'd with LOG_ITEM_FREE_VALUE. |
!nullptr | a pointer to the log_item's log_data, for easy chaining: line_item_set_with_key(...)->data_integer= 1; |
nullptr | could not create a log_item in given log_line |
|
staticnoexcept |
Test whether a given type is presumed present on the log line.
ll | the log_line to examine |
m | the log_type to test for |
0 | not present |
!=0 | present |
|
staticnoexcept |
Complete, filter, and write submitted log items.
This expects a log_line collection of log-related key/value pairs, e.g. from log_message().
Where missing, timestamp, priority, thread-ID (if any) and so forth are added.
Log item source services, log item filters, and log item sinks are then called; then all applicable resources are freed.
This interface is intended to facilitate the building of submission interfaces other than the variadic message() one below. See the example fluent C++ LogEvent() wrapper for an example of how to leverage it.
ll | key/value pairs describing info to log |
int | number of fields in created log line |
|
staticnoexcept |
Submit a log-message for log "log_type".
Variadic convenience function for logging.
This fills in the array that is used by the filter and log-writer services. Where missing, timestamp, priority, and thread-ID (if any) are added. Log item source services, log item filters, and log item writers are called.
The variadic list accepts a list of "assignments" of the form
As its last item, the list should have
an element of type LOG_ITEM_LOG_MESSAGE, containing a printf-style format string, followed by all variables necessary to satisfy the substitutions in that string
OR
an element of type LOG_ITEM_LOG_LOOKUP, containing a MySQL error code, which will be looked up in the list or regular error messages, followed by all variables necessary to satisfy the substitutions in that string
OR
see log_vmessage() for more information.
log_type | what log should this go to? |
... | fields: LOG_ITEM_* tag, [[key], value] |
int | return value of log_vmessage() |
|
staticnoexcept |
Open an error log file.
name_or_ext | if beginning with '.': @global.log_error, except with this extension otherwise: use this as file name in the same location as @global.log_error |
Value may not contain folder separators!
[out] | my_errstream | an error log handle, or nullptr on failure |
LOG_SERVICE_SUCCESS | success |
LOG_SERVICE_INVALID_ARGUMENT | no my_errstream, or bad log name |
LOG_SERVICE_OUT_OF_MEMORY | could not allocate file handle |
LOG_SERVICE_LOCK_ERROR | couldn't lock lock |
LOG_SERVICE_UNABLE_TO_WRITE | couldn't write to given location |
LOG_SERVICE_COULD_NOT_MAKE_LOG_NAME | could not make log name |
|
staticnoexcept |
Parse a ISO8601 timestamp and return the number of microseconds since the epoch.
Heeds +/- timezone info if present.
timestamp | an ASCII string containing an ISO8601 timestamp |
len | Length in bytes of the aforementioned string |
|
staticnoexcept |
Re-open an error log file (primarily to facilitate flush/log-rotation)
The semantics here are, if we can open the file by name (again), we close the original file (handle), and replace the old handle with the new one in our stream-descriptor; if we can't, we'll leave the existing stream as it is (e.g. it remains open so we can go on logging, but we don't change over to a new log if log-rotation happened). This is different from libc reopen semantics.
name_or_ext | if beginning with '.': @global.log_error, except with this extension otherwise: use this as file name in the same location as @global.log_error |
Value may not contain folder separators!
In the general case, the caller will be a log-writer, the log-writer will just pass its preferred file extension, and the resulting file name and path will therefore be the same as for the original log file.
[in,out] | my_errstream | an error log handle |
|
staticnoexcept |
|
staticnoexcept |
See whether a string is a wellknown field name.
key | potential key starts here |
length | length of the string to examine |
LOG_ITEM_TYPE_RESERVED | reserved, but not "wellknown" key |
LOG_ITEM_TYPE_NOT_FOUND | key not found |
>0 | index in array of wellknowns |
|
staticnoexcept |
See whether a type is wellknown.
t | log item type to examine |
LOG_ITEM_TYPE_NOT_FOUND | key not found |
>0 | index in array of wellknowns |
|
staticnoexcept |
Accessor: from a record describing a wellknown key, get its name.
i | index in array of wellknowns, see log_item_wellknown_by_...() |
name | (NTBS) |
|
staticnoexcept |
Accessor: from a record describing a wellknown key, get its type.
i | index in array of wellknowns, see log_item_wellknown_by_...() |
the | log item type for the wellknown key |
|
staticnoexcept |
Write to an error log file previously opened with open_errstream().
my_errstream | a handle describing the log file |
buffer | pointer to the string to write |
length | length of the string to write |
LOG_SERVICE_SUCCESS | success |
otherwise | failure |