MySQL  8.0.19
Source Code Documentation
log_builtins_imp Class Reference

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
 Set a string value on a log_item. More...
 
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_dataitem_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_dataitem_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_dataline_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_dataline_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_lineline_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_iterline_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_itemline_item_iter_first (log_item_iter *it) noexcept
 Use the log_line iterator to get the first item from the set. More...
 
static log_itemline_item_iter_next (log_item_iter *it) noexcept
 Use the log_line iterator to get the next item from the set. More...
 
static log_itemline_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 int open_errstream (const char *file, void **my_errstream) noexcept
 open an error log file More...
 
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() More...
 
static int dedicated_errstream (void *my_errstream) noexcept
 are we writing to a dedicated errstream, or are we sharing it? More...
 
static int close_errstream (void **my_errstream) noexcept
 close an error log file previously opened with open_errstream() More...
 

Detailed Description

Primitives for services to interact with the structured logger: functions pertaining to log_line and log_item data.

Member Function Documentation

◆ close_errstream()

int log_builtins_imp::close_errstream ( void **  my_errstream)
staticnoexcept

close an error log file previously opened with open_errstream()

Parameters
my_errstreama handle describing the log file
Return values
0success
!0failure

◆ dedicated_errstream()

int log_builtins_imp::dedicated_errstream ( void *  my_errstream)
staticnoexcept

are we writing to a dedicated errstream, or are we sharing it?

Parameters
my_errstreama handle describing the log file
Return values
<0error
0not dedicated (multiplexed, stderr, ...)
1dedicated

◆ errcode_by_errsymbol()

longlong log_builtins_imp::errcode_by_errsymbol ( const char *  sym)
staticnoexcept

Return MySQL error code for a given error symbol.

Parameters
symthe symbol to look up
Return values
-1failure
>=0the MySQL error code

◆ errmsg_by_errcode()

const char * log_builtins_imp::errmsg_by_errcode ( int  mysql_errcode)
staticnoexcept

Return MySQL error message for a given error code.

Parameters
mysql_errcodethe error code the message for which to look up
Return values
themessage (a printf-style format string)

◆ item_generic_type()

bool log_builtins_imp::item_generic_type ( log_item_type  t)
staticnoexcept

Predicate used to determine whether a type is generic (generic string, generic float, generic integer) rather than a well-known type.

Parameters
tlog item type to examine
Return values
trueif generic type
falseif wellknown type

◆ item_inconsistent()

int log_builtins_imp::item_inconsistent ( log_item li)
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.

Parameters
lithe log_item to check
Return values
0no problems
-2unknown item type
-3item_class derived from type isn't what's set on the item
-4class not generic, so key should match wellknown

◆ item_numeric_class()

bool log_builtins_imp::item_numeric_class ( log_item_class  c)
staticnoexcept

Predicate used to determine whether a class is a numeric class (integer or float).

Parameters
clog item class to examine
Return values
trueif of a numeric class
falseif not of a numeric class

◆ item_set()

log_item_data * log_builtins_imp::item_set ( log_item li,
log_item_type  t 
)
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.

Parameters
lithe log_item to work on
tthe item-type
Return values
apointer to the log_item's log_data, for easy chaining: log_item_set_with_key(...)->data_integer= 1;

◆ item_set_cstring()

bool log_builtins_imp::item_set_cstring ( log_item_data lid,
const char *  s 
)
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]().

Parameters
lidlog_item_data struct to set the value on
spointer to NTBS
Return values
truelid was nullptr (possibly: OOM, could not set up log_item)
falseall's well

◆ item_set_float()

bool log_builtins_imp::item_set_float ( log_item_data lid,
double  f 
)
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]().

Parameters
lidlog_item_data struct to set the value on
ffloat to set
Return values
truelid was nullptr (possibly: OOM, could not set up log_item)
falseall's well

◆ item_set_int()

bool log_builtins_imp::item_set_int ( log_item_data lid,
longlong  i 
)
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]().

Parameters
lidlog_item_data struct to set the value on
iinteger to set
Return values
truelid was nullptr (possibly: OOM, could not set up log_item)
falseall's well

◆ item_set_lexstring()

bool log_builtins_imp::item_set_lexstring ( log_item_data lid,
const char *  s,
size_t  s_len 
)
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]().

Parameters
lidlog_item_data struct to set the value on
spointer to string
s_lenlength of string
Return values
truelid was nullptr (possibly: OOM, could not set up log_item)
falseall's well

◆ item_set_with_key()

log_item_data * log_builtins_imp::item_set_with_key ( log_item li,
log_item_type  t,
const char *  key,
uint32  alloc 
)
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.

Parameters
lithe log_item to work on
tthe item-type
keythe key to set on the item. ignored for non-generic types (may pass nullptr for those) see alloc
allocLOG_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.
Return values
apointer to the log_item's log_data, for easy chaining: log_item_set_with_key(...)->data_integer= 1;

◆ item_string_class()

bool log_builtins_imp::item_string_class ( log_item_class  c)
staticnoexcept

Predicate used to determine whether a class is a string class (C-string or Lex-string).

Parameters
clog item class to examine
Return values
trueif of a string class
falseif not of a string class

◆ label_from_prio()

const char * log_builtins_imp::label_from_prio ( int  prio)
staticnoexcept

Convenience function: Derive a log label ("error", "warning", "information") from a severity.

Parameters
priothe severity/prio in question
Returns
a label corresponding to that priority.
Return values
Errorfor prio of ERROR_LEVEL or higher
Warningfor prio of WARNING_LEVEL
Noteotherwise

◆ line_exit()

void log_builtins_imp::line_exit ( log_line ll)
staticnoexcept

Release a log_line allocated with line_init()

Parameters
lla log_line previously allocated with line_init()

◆ line_init()

log_line * log_builtins_imp::line_init ( )
staticnoexcept

Dynamically allocate and initialize a log_line.

Return values
nullptrcould not set up buffer (too small?)
otheraddress of the newly initialized log_line

◆ line_item_count()

int log_builtins_imp::line_item_count ( log_line ll)
staticnoexcept

How many items are currently set on the given log_line?

Parameters
llthe log-line to examine
Return values
thenumber of items set

◆ line_item_iter_acquire()

log_item_iter * log_builtins_imp::line_item_iter_acquire ( log_line ll)
staticnoexcept

Get an iterator for the items in a log_line.

For now, only one iterator may exist per log_line.

Parameters
llthe log_line to examine
Return values
alog_iterm_iter, or nullptr on failure

◆ line_item_iter_current()

log_item * log_builtins_imp::line_item_iter_current ( log_item_iter it)
staticnoexcept

Use the log_line iterator to get the current item from the set.

Parameters
itthe iterator to use
Return values
pointerto the current log_item in the collection, or nullptr

◆ line_item_iter_first()

log_item * log_builtins_imp::line_item_iter_first ( log_item_iter it)
staticnoexcept

Use the log_line iterator to get the first item from the set.

Parameters
itthe iterator to use
Return values
pointerto the first log_item in the collection, or nullptr

◆ line_item_iter_next()

log_item * log_builtins_imp::line_item_iter_next ( log_item_iter it)
staticnoexcept

Use the log_line iterator to get the next item from the set.

Parameters
itthe iterator to use
Return values
pointerto the next log_item in the collection, or nullptr

◆ line_item_iter_release()

void log_builtins_imp::line_item_iter_release ( log_item_iter it)
staticnoexcept

Release an iterator for the items in a log_line.

Parameters
itthe iterator to release

◆ line_item_set()

log_item_data * log_builtins_imp::line_item_set ( log_line ll,
log_item_type  t 
)
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.

Parameters
llthe log_line to work on
tthe item-type
Return values
!nullptra pointer to the log_item's log_data, for easy chaining: line_item_set(...)->data_integer= 1;
nullptrcould not create a log_item in given log_line

◆ line_item_set_with_key()

log_item_data * log_builtins_imp::line_item_set_with_key ( log_line ll,
log_item_type  t,
const char *  key,
uint32  alloc 
)
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.

Parameters
llthe log_line to work on
tthe item-type
keythe key to set on the item. ignored for non-generic types (may pass nullptr for those) see alloc
allocLOG_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.
Return values
!nullptra pointer to the log_item's log_data, for easy chaining: line_item_set_with_key(...)->data_integer= 1;
nullptrcould not create a log_item in given log_line

◆ line_item_types_seen()

log_item_type_mask log_builtins_imp::line_item_types_seen ( log_line ll,
log_item_type_mask  m 
)
staticnoexcept

Test whether a given type is presumed present on the log line.

Parameters
llthe log_line to examine
mthe log_type to test for
Return values
0not present
!=0present

◆ line_submit()

int log_builtins_imp::line_submit ( log_line ll)
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.

Parameters
llkey/value pairs describing info to log
Return values
intnumber of fields in created log line

◆ message()

int log_builtins_imp::message ( int  log_type,
  ... 
)
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

  • log_item_type, value, for well-known types, and
  • log_item_type, key, value, for ad-hoc types (LOG_ITEM_GEN_*)

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

  • an element of type LOG_ITEM_LOG_VERBATIM, containing a string that will be used directly, with no % substitutions

see log_vmessage() for more information.

Parameters
log_typewhat log should this go to?
...fields: LOG_ITEM_* tag, [[key], value]
Return values
intreturn value of log_vmessage()

◆ open_errstream()

int log_builtins_imp::open_errstream ( const char *  file,
void **  my_errstream 
)
staticnoexcept

open an error log file

Parameters
fileif 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!

Parameters
[out]my_errstreaman error log handle, or nullptr on failure
Return values
0success
-1EINVAL: my_errstream is NULL
-2EINVAL: invalid file name / extension
-3OOM: could not allocate file handle
-4couldn't lock lock
-5couldn't write to given location

◆ sanitize()

int log_builtins_imp::sanitize ( log_item li)
staticnoexcept

◆ wellknown_by_name()

int log_builtins_imp::wellknown_by_name ( const char *  key,
size_t  length 
)
staticnoexcept

See whether a string is a wellknown field name.

Parameters
keypotential key starts here
lengthlength of the string to examine
Return values
LOG_ITEM_TYPE_RESERVEDreserved, but not "wellknown" key
LOG_ITEM_TYPE_NOT_FOUNDkey not found
>0index in array of wellknowns

◆ wellknown_by_type()

int log_builtins_imp::wellknown_by_type ( log_item_type  t)
staticnoexcept

See whether a type is wellknown.

Parameters
tlog item type to examine
Return values
LOG_ITEM_TYPE_NOT_FOUNDkey not found
>0index in array of wellknowns

◆ wellknown_get_name()

const char * log_builtins_imp::wellknown_get_name ( uint  i)
staticnoexcept

Accessor: from a record describing a wellknown key, get its name.

Parameters
iindex in array of wellknowns, see log_item_wellknown_by_...()
Return values
name(NTBS)

◆ wellknown_get_type()

log_item_type log_builtins_imp::wellknown_get_type ( uint  i)
staticnoexcept

Accessor: from a record describing a wellknown key, get its type.

Parameters
iindex in array of wellknowns, see log_item_wellknown_by_...()
Return values
thelog item type for the wellknown key

◆ write_errstream()

int log_builtins_imp::write_errstream ( void *  my_errstream,
const char *  buffer,
size_t  length 
)
staticnoexcept

write to an error log file previously opened with open_errstream()

Parameters
my_errstreama handle describing the log file
bufferpointer to the string to write
lengthlength of the string to write
Return values
0success
!0failure

The documentation for this class was generated from the following files: