log_shared.h File Reference

#include <mysql/mysql_lex_string.h>
#include "my_basename.h"
#include "my_inttypes.h"
#include "mysql/my_loglevel.h"

Go to the source code of this file.

Classes
union	_log_item_data
struct	_log_item

Macros
#define	LOG_TAG_DIAG   "DIAGNOSTICS"
	DIAGNOSTICS: for da->message_text() More...
#define	LOG_TAG_AUX   "AUX"
	AUX: supplementary data not fitting any of the wellknown keys. More...
#define	LOG_BUFF_MAX   8192
	advisory. More...
#define	ER_SERVER_RANGE_START   10000
	index of first server error message: messages with this index or higher are intended for the error log; messages below this index are intended for the client More...

Typedefs
typedef struct MYSQL_LEX_CSTRING	LEX_CSTRING
	fallback: includer may not have set this to something sensible. More...
typedef enum enum_log_item_type	log_item_type
	item_type – what to log More...
typedef enum enum_log_line_flags	log_line_flags
	Log line flags. More...
typedef enum enum_log_item_class	log_item_class
typedef union _log_item_data	log_item_data
typedef const char *	log_item_key
typedef struct _log_item	log_item
typedef enum enum_log_item_error	log_item_error
typedef uint64	log_item_type_mask
	a bit mask of log_types. More...
typedef struct _log_line	log_line
	log line: a collection of log items More...
typedef struct _log_item_iter	log_item_iter
	log iter: an iterator over the collection of log items in a log line More...
typedef uint64	log_line_flags_mask
	a bit mask with flags describing a log line More...

Enumerations
enum	enum_log_type {   LOG_TYPE_UNDEF = 0 , LOG_TYPE_ERROR = 1 , LOG_TYPE_GENERAL = 2 , LOG_TYPE_SLOW = 4 ,   LOG_TYPE_AUDIT = 8 , LOG_TYPE_MISC = 16 }
	log_type – which log to send data to check vs enum_log_table_type and LOG_FILE/LOG_TABLE/LOG_NONE More...
enum	enum_log_item_type {   LOG_ITEM_END = 0 , LOG_ITEM_LOG_TYPE = 1 << 0 , LOG_ITEM_SQL_ERRCODE = 1 << 1 , LOG_ITEM_SQL_ERRSYMBOL = 1 << 2 ,   LOG_ITEM_SQL_STATE = 1 << 3 , LOG_ITEM_SYS_ERRNO = 1 << 4 , LOG_ITEM_SYS_STRERROR = 1 << 5 , LOG_ITEM_SRC_FILE = 1 << 6 ,   LOG_ITEM_SRC_LINE = 1 << 7 , LOG_ITEM_SRC_FUNC = 1 << 8 , LOG_ITEM_SRV_SUBSYS = 1 << 9 , LOG_ITEM_SRV_COMPONENT = 1 << 10 ,   LOG_ITEM_MSC_USER = 1 << 11 , LOG_ITEM_MSC_HOST = 1 << 12 , LOG_ITEM_SRV_THREAD = 1 << 13 , LOG_ITEM_SQL_QUERY_ID = 1 << 14 ,   LOG_ITEM_SQL_TABLE_NAME = 1 << 15 , LOG_ITEM_LOG_PRIO = 1 << 16 , LOG_ITEM_LOG_LABEL = 1 << 17 , LOG_ITEM_LOG_VERBATIM = 1 << 18 ,   LOG_ITEM_LOG_MESSAGE = 1 << 19 , LOG_ITEM_LOG_LOOKUP = 1 << 20 , LOG_ITEM_LOG_TIMESTAMP = 1 << 21 , LOG_ITEM_LOG_TS = 1 << 22 ,   LOG_ITEM_LOG_BUFFERED = 1 << 23 , LOG_ITEM_LOG_SUPPRESSED = 1 << 24 , LOG_ITEM_GEN_FLOAT = 1 << 25 , LOG_ITEM_GEN_INTEGER = 1 << 26 ,   LOG_ITEM_GEN_LEX_STRING = 1 << 27 , LOG_ITEM_GEN_CSTRING = 1 << 28 , LOG_ITEM_GEN_BUFFER = 1 << 29 , LOG_ITEM_RET_BUFFER = 1 << 30 }
	item_type – what to log More...
enum	enum_log_line_flags { LOG_LINE_EMIT_TELEMETRY = 1 << 0 }
	Log line flags. More...
enum	enum_log_item_class {   LOG_UNTYPED = 0 , LOG_CSTRING = 1 , LOG_INTEGER = 2 , LOG_FLOAT = 3 ,   LOG_LEX_STRING = 4 , LOG_BUFFER = 5 }
enum	enum_log_item_free { LOG_ITEM_FREE_NONE = 0 , LOG_ITEM_FREE_KEY = 1 , LOG_ITEM_FREE_VALUE = 2 }
enum	enum_log_item_error {   LOG_ITEM_OK = 0 , LOG_ITEM_TYPE_NOT_FOUND = -1 , LOG_ITEM_TYPE_RESERVED = -2 , LOG_ITEM_CLASS_MISMATCH = -3 ,   LOG_ITEM_KEY_MISMATCH = -4 , LOG_ITEM_STRING_NULL = -5 , LOG_ITEM_KEY_NULL = -6 }

Variables
static const int	iso8601_size = 33
	size of a full ISO 8601 timestamp: More...

Macro Definition Documentation

ER_SERVER_RANGE_START

#define ER_SERVER_RANGE_START   10000

index of first server error message: messages with this index or higher are intended for the error log; messages below this index are intended for the client

LOG_BUFF_MAX

#define LOG_BUFF_MAX   8192

advisory.

components must not rely on others using the same value.

LOG_TAG_AUX

#define LOG_TAG_AUX   "AUX"

AUX: supplementary data not fitting any of the wellknown keys.

LOG_TAG_DIAG

#define LOG_TAG_DIAG   "DIAGNOSTICS"

DIAGNOSTICS: for da->message_text()

Typedef Documentation

LEX_CSTRING

typedef struct MYSQL_LEX_CSTRING LEX_CSTRING

fallback: includer may not have set this to something sensible.

The logging sub-system internally uses the log_line structure to pass data around. This header primarily the specifics and symbols of that structure.

Within the server, those interfaces may be used, but it is usually preferable to use the fluent C++ convenience class LogErr() instead where possible (and the variadic convenience function log_message() where it is not). (see sql/log.h).

Finally, this header defines log types (error log etc.) as well as log item types (timestamp, message, ...) used by the logging components; these are shared between the variadic convenience functions (log_message() etc.) as well as the lower level services using the log_line structure.

log_item

typedef struct _log_item log_item

log_item_class

typedef enum enum_log_item_class log_item_class

log_item_data

typedef union _log_item_data log_item_data

log_item_error

typedef enum enum_log_item_error log_item_error

log_item_iter

typedef struct _log_item_iter log_item_iter

log iter: an iterator over the collection of log items in a log line

log_item_key

typedef const char* log_item_key

log_item_type

typedef enum enum_log_item_type log_item_type

item_type – what to log

Used by variadic convenience interface log_message(), legacy sql_print_*(), legacy my_plugin_log_message(). Also available via the log_builtins service as message().

(Wherever possible, use the fluent C++ wrapper LogErr() (see log_builtins.h) instead, though.)

LOG_ITEM_GEN_CSTRING lets the caller submit a \0 terminated, C-style string for convenience; it will be converted to lex style (char *, size_t) on submission.

LOG_ITEM_END should not be used in the variadic interface as submitting a log line without an actual message is discouraged. Instead LOG_ITEM_LOG_MESSAGE or LOG_ITEM_LOG_LOOKUP should be used as the last LOG_ITEM_* key-value pairs:

• LOG_ITEM_LOG_MESSAGE can be used to submit an ad hoc message directly while debugging.
• LOG_ITEM_LOG_LOOKUP asks for the given error number to be replaced by the associated error message (i.e. the error message for the error number will be looked up, and the LOOKUP item will be replaced by a MESSAGE one).

In variadic submission, both ad hoc and well-known error messages are considered printf()-style format strings, and should be followed by any arguments/variables required by that format string.

In some situations, the variadic interface will automatically generate some items ("If you cannot afford a timestamp, one will be provided for you."). If an item of the required type already exists, the submission interface should not generate another.

Old-style plug-ins using my_plugin_log_message() will automatically be tagged with a default LOG_ITEM_MSC_COMPONENT of their plug-in name.

Non-variadic interface

In non-variadic submission (i.e. all functions accepting a log_line), LOG_ITEM_LOG_LOOKUP and LOG_ITEM_GEN_CSTRING are not valid item types, while LOG_ITEM_LOG_MESSAGE must already be a string literal (i.e. any substitutions must already have taken place).

log_item_type_mask

typedef uint64 log_item_type_mask

a bit mask of log_types.

standardizing the width to 64 bit.

log_line

typedef struct _log_line log_line

log line: a collection of log items

log_line_flags

typedef enum enum_log_line_flags log_line_flags

Log line flags.

log_line_flags_mask

typedef uint64 log_line_flags_mask

a bit mask with flags describing a log line

Enumeration Type Documentation

enum_log_item_class

enum enum_log_item_class

Enumerator
LOG_UNTYPED	undefined
LOG_CSTRING	string (char * + \0; variadic API only)
LOG_INTEGER	integer (long long)
LOG_FLOAT	float (double)
LOG_LEX_STRING	string (const char *, size_t)
LOG_BUFFER	string (char *, size_t)

enum_log_item_error

enum enum_log_item_error

Enumerator
LOG_ITEM_OK
LOG_ITEM_TYPE_NOT_FOUND
LOG_ITEM_TYPE_RESERVED
LOG_ITEM_CLASS_MISMATCH
LOG_ITEM_KEY_MISMATCH
LOG_ITEM_STRING_NULL
LOG_ITEM_KEY_NULL

enum_log_item_free

enum enum_log_item_free

Enumerator
LOG_ITEM_FREE_NONE
LOG_ITEM_FREE_KEY
LOG_ITEM_FREE_VALUE

enum_log_item_type

enum enum_log_item_type

item_type – what to log

Used by variadic convenience interface log_message(), legacy sql_print_*(), legacy my_plugin_log_message(). Also available via the log_builtins service as message().

(Wherever possible, use the fluent C++ wrapper LogErr() (see log_builtins.h) instead, though.)

LOG_ITEM_GEN_CSTRING lets the caller submit a \0 terminated, C-style string for convenience; it will be converted to lex style (char *, size_t) on submission.

LOG_ITEM_END should not be used in the variadic interface as submitting a log line without an actual message is discouraged. Instead LOG_ITEM_LOG_MESSAGE or LOG_ITEM_LOG_LOOKUP should be used as the last LOG_ITEM_* key-value pairs:

• LOG_ITEM_LOG_MESSAGE can be used to submit an ad hoc message directly while debugging.
• LOG_ITEM_LOG_LOOKUP asks for the given error number to be replaced by the associated error message (i.e. the error message for the error number will be looked up, and the LOOKUP item will be replaced by a MESSAGE one).

In variadic submission, both ad hoc and well-known error messages are considered printf()-style format strings, and should be followed by any arguments/variables required by that format string.

In some situations, the variadic interface will automatically generate some items ("If you cannot afford a timestamp, one will be provided for you."). If an item of the required type already exists, the submission interface should not generate another.

Old-style plug-ins using my_plugin_log_message() will automatically be tagged with a default LOG_ITEM_MSC_COMPONENT of their plug-in name.

Non-variadic interface

In non-variadic submission (i.e. all functions accepting a log_line), LOG_ITEM_LOG_LOOKUP and LOG_ITEM_GEN_CSTRING are not valid item types, while LOG_ITEM_LOG_MESSAGE must already be a string literal (i.e. any substitutions must already have taken place).

Enumerator
LOG_ITEM_END	end of list, see above
LOG_ITEM_LOG_TYPE	error log, etc.
LOG_ITEM_SQL_ERRCODE	mysql error code (numeric)
LOG_ITEM_SQL_ERRSYMBOL	mysql error code (symbolic)
LOG_ITEM_SQL_STATE	SQL state.
LOG_ITEM_SYS_ERRNO	OS errno.
LOG_ITEM_SYS_STRERROR	OS strerror()
LOG_ITEM_SRC_FILE	log called from file ...
LOG_ITEM_SRC_LINE	log called from line ...
LOG_ITEM_SRC_FUNC	log called from function ...
LOG_ITEM_SRV_SUBSYS	log called from subsystem ...
LOG_ITEM_SRV_COMPONENT	log called from component ...
LOG_ITEM_MSC_USER	offending thread owned by ...
LOG_ITEM_MSC_HOST	responsible user on host ...
LOG_ITEM_SRV_THREAD	connection ID
LOG_ITEM_SQL_QUERY_ID	query ID
LOG_ITEM_SQL_TABLE_NAME	table name
LOG_ITEM_LOG_PRIO	log priority (error, warn, ...)
LOG_ITEM_LOG_LABEL	label, unless auto-derived
LOG_ITEM_LOG_VERBATIM	the message, no % substitutions
LOG_ITEM_LOG_MESSAGE	the message, format string
LOG_ITEM_LOG_LOOKUP	insert message by error-code
LOG_ITEM_LOG_TIMESTAMP	ISO8601 timestamp.
LOG_ITEM_LOG_TS	millisecs since epoch
LOG_ITEM_LOG_BUFFERED	integer timestamp if/when buffered
LOG_ITEM_LOG_SUPPRESSED	"and ... more" throttled
LOG_ITEM_GEN_FLOAT	float not otherwise specified
LOG_ITEM_GEN_INTEGER	integer not otherwise specified
LOG_ITEM_GEN_LEX_STRING	lex string not otherwise specified
LOG_ITEM_GEN_CSTRING	C-string not otherwise specified.
LOG_ITEM_GEN_BUFFER	optional buffer; set type on use
LOG_ITEM_RET_BUFFER	sink's output to pfs table

enum_log_line_flags

enum enum_log_line_flags

Log line flags.

Enumerator
LOG_LINE_EMIT_TELEMETRY	emit log line as telemetry record

enum_log_type

enum enum_log_type

log_type – which log to send data to check vs enum_log_table_type and LOG_FILE/LOG_TABLE/LOG_NONE

Enumerator
LOG_TYPE_UNDEF
LOG_TYPE_ERROR
LOG_TYPE_GENERAL
LOG_TYPE_SLOW
LOG_TYPE_AUDIT
LOG_TYPE_MISC

Variable Documentation

iso8601_size

const int iso8601_size = 33

static

size of a full ISO 8601 timestamp:

• 19 for date/time 2022-02-22T12:34:56
• 7 for microsecond part .123456
• 6 for tzinfo tail +14:30
• 1 for terminator \0