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...

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()

log_service_error log_builtins_imp::close_errstream ( void ** my_errstream )

staticnoexcept

Close an error log file previously opened with open_errstream() (wrapper for the component system).

Parameters

my_errstream a handle describing the log file

Returns: LOG_SERVICE_SUCCESS on success

◆ 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_errstream a handle describing the log file

Return values

<0	error
0	not dedicated (multiplexed, stderr, ...)
1	dedicated

◆ errcode_by_errsymbol()

longlong log_builtins_imp::errcode_by_errsymbol ( const char * sym )

staticnoexcept

Return MySQL error code for a given error symbol.

Parameters

sym	the symbol to look up

Return values

-1	failure
>=0	the 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_errcode the error code the message for which to look up

Return values

the	message (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

t	log item type to examine

Return values

true	if generic type
false	if 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

li	the log_item to check

Return values

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

◆ 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

c	log item class to examine

Return values

true	if of a numeric class
false	if 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

li	the log_item to work on
t	the item-type

Return values

a	pointer 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

lid	log_item_data struct to set the value on
s	pointer to NTBS

Return values

true	lid was nullptr (possibly: OOM, could not set up log_item)
false	all'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

lid	log_item_data struct to set the value on
f	float to set

Return values

true	lid was nullptr (possibly: OOM, could not set up log_item)
false	all'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

lid	log_item_data struct to set the value on
i	integer to set

Return values

true	lid was nullptr (possibly: OOM, could not set up log_item)
false	all's well

◆ item_set_lexstring()

bool log_builtins_imp::item_set_lexstring	(	log_item_data *	lid,
		const char *	s,
		size_t	s_len
	)

staticnoexcept

◆ 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

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.

Return values

a	pointer 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

c	log item class to examine

Return values

true	if of a string class
false	if 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

prio	the severity/prio in question

Returns: a label corresponding to that priority.

Return values

Error	for prio of ERROR_LEVEL or higher
Warning	for prio of WARNING_LEVEL
Note	otherwise

◆ line_exit()

void log_builtins_imp::line_exit ( log_line * ll )

staticnoexcept

Release a log_line allocated with line_init()

Parameters

ll	a log_line previously allocated with line_init()

◆ line_get_output_buffer()

log_item * log_builtins_imp::line_get_output_buffer ( log_line * ll )

staticnoexcept

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.

Parameters

ll	the log_line to examine

Return values

nullptr	success, an output buffer is available
otherwise	failure, no output buffer is available

◆ line_init()

log_line * log_builtins_imp::line_init ( )

staticnoexcept

Dynamically allocate and initialize a log_line.

Return values

nullptr	could not set up buffer (too small?)
other	address 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

ll	the log-line to examine

Return values

the	number 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

ll	the log_line to examine

Return values

a	log_item_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

it	the iterator to use

Return values

pointer to 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

it	the iterator to use

Return values

pointer to 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

it	the iterator to use

Return values

pointer to 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

it	the 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

ll	the log_line to work on
t	the item-type

Return values

!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

◆ 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

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.

Return values

!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

◆ 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

ll	the log_line to examine
m	the log_type to test for

Return values

0	not present
!=0	present

◆ 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

ll	key/value pairs describing info to log

Return values

int	number 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_type	what log should this go to?
...	fields: LOG_ITEM_* tag, [[key], value]

Return values

int	return value of log_vmessage()

◆ open_errstream()

log_service_error log_builtins_imp::open_errstream	(	const char *	name_or_ext,
		void **	my_errstream
	)

staticnoexcept

Open an error log file.

Parameters

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!

Parameters

[out] my_errstream an error log handle, or nullptr on failure

Return values

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

◆ parse_iso8601_timestamp()

ulonglong log_builtins_imp::parse_iso8601_timestamp	(	const char *	timestamp,
		size_t	len
	)

staticnoexcept

Parse a ISO8601 timestamp and return the number of microseconds since the epoch.

Heeds +/- timezone info if present.

See also: make_iso8601_timestamp()

Parameters

timestamp	an ASCII string containing an ISO8601 timestamp
len	Length in bytes of the aforementioned string

Returns: microseconds since the epoch

◆ reopen_errstream()

log_service_error log_builtins_imp::reopen_errstream	(	const char *	name_or_ext,
		void **	my_errstream
	)

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.

Parameters

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.

Parameters

[in,out] my_errstream an error log handle

Returns: LOG_SERVICE_INVALID_ARGUMENT, or the result of open_errstream()

◆ 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

key	potential key starts here
length	length of the string to examine

Return values

LOG_ITEM_TYPE_RESERVED	reserved, but not "wellknown" key
LOG_ITEM_TYPE_NOT_FOUND	key not found
>0	index 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

t	log item type to examine

Return values

LOG_ITEM_TYPE_NOT_FOUND	key not found
>0	index 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

i	index 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

i	index in array of wellknowns, see log_item_wellknown_by_...()

Return values

the	log item type for the wellknown key

◆ write_errstream()

log_service_error 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_errstream	a handle describing the log file
buffer	pointer to the string to write
length	length of the string to write

Return values

LOG_SERVICE_SUCCESS	success
otherwise	failure

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

sql/server_component/log_builtins_imp.h
sql/server_component/log_builtins.cc

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ close_errstream()

◆ dedicated_errstream()

◆ errcode_by_errsymbol()

◆ errmsg_by_errcode()

◆ item_generic_type()

◆ item_inconsistent()

◆ item_numeric_class()

◆ item_set()

◆ item_set_cstring()

◆ item_set_float()

◆ item_set_int()

◆ item_set_lexstring()

◆ item_set_with_key()

◆ item_string_class()

◆ label_from_prio()

◆ line_exit()

◆ line_get_output_buffer()

◆ line_init()

◆ line_item_count()

◆ line_item_iter_acquire()

◆ line_item_iter_current()

◆ line_item_iter_first()

◆ line_item_iter_next()

◆ line_item_iter_release()

◆ line_item_set()

◆ line_item_set_with_key()

◆ line_item_types_seen()

◆ line_submit()

◆ message()

◆ open_errstream()

◆ parse_iso8601_timestamp()

◆ reopen_errstream()

◆ sanitize()

◆ wellknown_by_name()

◆ wellknown_by_type()

◆ wellknown_get_name()

◆ wellknown_get_type()

◆ write_errstream()