Modular logger: fluid API. More...

#include <log_builtins.h>

Public Member Functions
	~LogEvent ()
	Destructor automatically sends the event on. More...

	LogEvent ()
	"Full customization" constructor. More...

void	steal (log_line **save_to)

LogEvent &	type (enum_log_type val)
	Set log type. More...

LogEvent &	errcode (longlong val)
	Append a numeric error code. More...

LogEvent &	errsymbol (const char *val)
	Append a (string) error symbol. More...

LogEvent &	sqlstate (const char *val)
	Append a (string) SQL state. More...

LogEvent &	os_errno (longlong val)
	Append a numeric (operating system, as opposed to MySQL) error number. More...

LogEvent &	os_errmsg (const char *val)
	Append a textual (operating system, as opposed to MySQL) error message, vulgo, strerror() More...

LogEvent &	source_file (const char *val)
	Which source file was the problem detected in? More...

LogEvent &	source_line (longlong val)
	Which line in the source file was the problem detected on? More...

LogEvent &	function (const char *val)
	Which function in the source was the problem detected in? More...

LogEvent &	subsys (const char *val)
	Which subsystem in the source was the problem detected in? ("Repl"/"InnoDB"/"Server") More...

LogEvent &	component (const char *val)
	Which component in the source was the problem detected in? This should be the same string that is given to the component/service framework. More...

LogEvent &	user (LEX_CSTRING val)
	What user were we working for at the time of the issue? More...

LogEvent &	user (const char *val)
	What user were we working for at the time of the issue? More...

LogEvent &	host (LEX_CSTRING val)
	Whose session did the issue appear in? More...

LogEvent &	host (const char *val)
	Whose session did the issue appear in? More...

LogEvent &	thread_id (longlong val)
	What thread / "connection ID" was the issue detected in? More...

LogEvent &	query_id (longlong val)
	What query apparently caused the issue? More...

LogEvent &	table_name (const char *val)
	What table were we working on? More...

LogEvent &	prio (longlong val)
	Set error message priority. More...

LogEvent &	label (const char *val)
	Set a label (usually "warning"/"error"/"information"). More...

LogEvent &	verbatim (const char *msg_arg)
	Add a message to the event, verbatim (i.e. More...

LogEvent &	messagev (const char *fmt, va_list ap)
	Fill in a format string by substituting the % with the given arguments, then add the result as the event's message. More...

LogEvent &	message (const char *fmt,...)
	Fill in a format string by substituting the % with the given arguments, then add the result as the event's message. More...

LogEvent &	message_quoted (const char tag, const char fmt,...)
	Fill in a format string by substituting the % with the given arguments and tag, then add the result as the event's message. More...

LogEvent &	lookup (longlong errcode,...)
	Find an error message by its MySQL error code. More...

LogEvent &	lookupv (longlong errcode, va_list args)
	Find an error message by its MySQL error code. More...

LogEvent &	lookup_quoted (longlong errcode, const char *tag,...)

LogEvent &	lookup_quotedv (longlong errcode, const char *tag, va_list vl)

LogEvent &	int_value (const char *key, longlong val)
	Add a ad hoc integer value with the given key. More...

LogEvent &	float_value (const char *key, double val)
	Add a ad hoc (not "well-known") float value with the given key. More...

LogEvent &	string_value (const char key, const char val, size_t len)
	Add a ad hoc string value with the given key. More...

LogEvent &	string_value (const char key, const char val)
	Add a ad hoc string value with the given key. More...

LogEvent &	no_telemetry ()
	Mark log line to skip being additionally emitted as a telemetry log record. More...

Private Member Functions
bool	set_errcode (longlong errcode)
	Set MySQL error-code if none has been set yet. More...

void	set_message (const char *fmt, va_list ap)
	Set the error message. More...

void	set_message_by_errcode (longlong errcode, va_list ap)
	Set the error message (by MySQL error code). More...

Private Attributes
log_line *	ll

char *	msg

const char *	msg_tag

bool	have_msg

Detailed Description

Modular logger: fluid API.

Server-internal. Lets you use safe and expressive syntax, like so:

LogEvent(LOG_TYPE_ERROR).prio(INFORMATION_LEVEL).message("Meow! %d", 4711);

Constructor & Destructor Documentation

◆ ~LogEvent()

LogEvent::~LogEvent ( )

inline

Destructor automatically sends the event on.

It is auto-free()d after processing.

◆ LogEvent()

LogEvent::LogEvent ( )

inline

"Full customization" constructor.

Use one of the LogErr() macro where possible; it's there to help you remember the minimum set of particles and their data-types. Be prepared for stern looks from your reviewers if you use this constructor except for external (loadable) services that have no error messages registered with the server, and therefore need to submit them free-form.

Member Function Documentation

◆ component()

LogEvent & LogEvent::component ( const char * val )

inline

Which component in the source was the problem detected in? This should be the same string that is given to the component/service framework.

Parameters

val	the component. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ errcode()

LogEvent & LogEvent::errcode ( longlong val )

inline

Append a numeric error code.

Parameters

val	the MySQL error code (not operating system errno!).

Return values

the	LogEvent, for easy fluent-style chaining.

◆ errsymbol()

LogEvent & LogEvent::errsymbol ( const char * val )

inline

Append a (string) error symbol.

Parameters

val	error symbol. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ float_value()

LogEvent & LogEvent::float_value	(	const char *	key,
		double	val
	)

inline

Add a ad hoc (not "well-known") float value with the given key.

Parameters

key	user-defined key (i.e. not wellknown). NTBS.
val	value.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ function()

LogEvent & LogEvent::function ( const char * val )

inline

Which function in the source was the problem detected in?

Parameters

val	the function's name. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ host() [1/2]

LogEvent & LogEvent::host ( const char * val )

inline

Whose session did the issue appear in?

Parameters

val	the host part (of "user@host"). NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ host() [2/2]

LogEvent & LogEvent::host ( LEX_CSTRING val )

inline

Whose session did the issue appear in?

Parameters

val	the host part (of "user@host"). LEX_CSTRING.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ int_value()

LogEvent & LogEvent::int_value	(	const char *	key,
		longlong	val
	)

inline

Add a ad hoc integer value with the given key.

Parameters

key	user-defined key (i.e. not wellknown). NTBS.
val	value.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ label()

LogEvent & LogEvent::label ( const char * val )

inline

Set a label (usually "warning"/"error"/"information").

Will be derived from prio if not set explicitly. Some log services may ignore custom labels.

Parameters

val	the (custom) label to set

Return values

the	LogEvent, for easy fluent-style chaining.

◆ lookup()

LogEvent & LogEvent::lookup	(	longlong	errcode,
			...
	)

inline

Find an error message by its MySQL error code.

Substitute the % in that message with the given arguments, then add the result as the event's message.

Parameters

errcode	MySQL error code for the message in question, e.g. ER_STARTUP
...	varargs to satisfy any % in the message

Return values

the	LogEvent, for easy fluent-style chaining.

◆ lookup_quoted()

LogEvent & LogEvent::lookup_quoted	(	longlong	errcode,
		const char *	tag,
			...
	)

inline

◆ lookup_quotedv()

LogEvent & LogEvent::lookup_quotedv	(	longlong	errcode,
		const char *	tag,
		va_list	vl
	)

inline

◆ lookupv()

LogEvent & LogEvent::lookupv	(	longlong	errcode,
		va_list	args
	)

inline

Find an error message by its MySQL error code.

Substitute the % in that message with the given arguments list, then add the result as the event's message.

Parameters

errcode	MySQL error code for the message in question, e.g. ER_STARTUP
args	varargs to satisfy any % in the message

Return values

the	LogEvent, for easy fluent-style chaining.

◆ message()

LogEvent & LogEvent::message	(	const char *	fmt,
			...
	)

inline

Fill in a format string by substituting the % with the given arguments, then add the result as the event's message.

If you use this in a context other than an external service that has no messages registered with the server, your reviewers will say unkind things about you. Use registered messages and their error codes wherever possible!

Parameters

fmt	message (treated as a printf-style format-string, so % substitution will happen)
...	varargs to satisfy any % in the message

Return values

the	LogEvent, for easy fluent-style chaining.

◆ message_quoted()

LogEvent & LogEvent::message_quoted	(	const char *	tag,
		const char *	fmt,
			...
	)

inline

Fill in a format string by substituting the % with the given arguments and tag, then add the result as the event's message.

Parameters

tag	Tag to prefix to message.
fmt	message (treated as a printf-style format-string, so % substitution will happen)
...	varargs to satisfy any % in the message

Return values

the	LogEvent, for easy fluent-style chaining.

◆ messagev()

LogEvent & LogEvent::messagev	(	const char *	fmt,
		va_list	ap
	)

inline

Fill in a format string by substituting the % with the given arguments, then add the result as the event's message.

This should be used very sparingly; use registered messages and their error codes wherever possible!

Parameters

fmt	message (treated as a printf-style format-string, so % substitution will happen)
ap	valist to satisfy any % in the message

Return values

the	LogEvent, for easy fluent-style chaining.

◆ no_telemetry()

LogEvent & LogEvent::no_telemetry ( )

inline

Mark log line to skip being additionally emitted as a telemetry log record.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ os_errmsg()

LogEvent & LogEvent::os_errmsg ( const char * val )

inline

Append a textual (operating system, as opposed to MySQL) error message, vulgo, strerror()

Parameters

val	the error message returned by the operating system. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ os_errno()

LogEvent & LogEvent::os_errno ( longlong val )

inline

Append a numeric (operating system, as opposed to MySQL) error number.

Parameters

val	the operating system errno.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ prio()

LogEvent & LogEvent::prio ( longlong val )

inline

Set error message priority.

Assign one of ERROR_LEVEL, WARNING_LEVEL, INFORMATION_LEVEL. log-writers and other sinks should use this value (rather than that of LOG_ITEM_LOG_EPRIO):

file writers should use the value to determine what label to write (perhaps by submitting it to label_from_prio())
sinks that submit the event data to a sub-system outside of the MySQL server (such as syslog, EventLog, systemd journal, etc.) should translate this value into a priority/log level understood by that target subsystem.

Parameters

val	The priority for this LogEvent.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ query_id()

LogEvent & LogEvent::query_id ( longlong val )

inline

What query apparently caused the issue?

Parameters

val	the query_ID of the offending query

Return values

the	LogEvent, for easy fluent-style chaining.

◆ set_errcode()

bool LogEvent::set_errcode ( longlong errcode )

inlineprivate

Set MySQL error-code if none has been set yet.

Parameters

errcode the error code (not operating system errno!)

Return values

true	an error occurred, value not set (OOM?)
false	value was set without incident, or did not need to be set

◆ set_message()

void LogEvent::set_message	(	const char *	fmt,
		va_list	ap
	)

inlineprivate

Set the error message.

Parameters

fmt	format string. % substitution will be performed.
ap	va_list of the arguments for % substitution.

◆ set_message_by_errcode()

void LogEvent::set_message_by_errcode	(	longlong	errcode,
		va_list	ap
	)

inlineprivate

Set the error message (by MySQL error code).

The actual message will be looked up using this errcode. As the message is a printf-style format string, % substitution will be performed.

Parameters

errcode	MySQL error code to fetch the message string for
ap	va_list of the arguments for % substitution.

◆ source_file()

LogEvent & LogEvent::source_file ( const char * val )

inline

Which source file was the problem detected in?

Parameters

val	the source file's name. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ source_line()

LogEvent & LogEvent::source_line ( longlong val )

inline

Which line in the source file was the problem detected on?

Parameters

val	the line number.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ sqlstate()

LogEvent & LogEvent::sqlstate ( const char * val )

inline

Append a (string) SQL state.

Parameters

val	the SQLstate. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ steal()

void LogEvent::steal ( log_line ** save_to )

inline

Save the log-event allocated by LogEvent().

LogEvent() internally represents the log-event in a log_line
structure it allocates. steal() saves this pointer to the
method's argument. The pointer in the LogEvent() is then
cleared to prevent the destructor from freeing the log_line.
Freeing allocated memory is now the caller's responsibility:

  log_line *ll;
  LogEvent().prio(SYSTEM_LEVEL).message("Hi %s!", user).steal(&ll);

Do some things with the event ...

  log_line_item_free_all(ll);
  log_line_exit(ll);

If a message was set, the message buffer pointed to by `msg`
becomes part of the log_line and is released on
log_line_item_free_all() (or equivalent).

If no message was set, the message buffer is released when
the LogEvent's destructor is called.

Note that verbatim() does NOT copy its argument to the
LogEvent's internal allocation `msg`.
Hence the life-cycle management of verbatim()'s argument
would be up to the developer. When using steal(), using it
with one of the set_message() wrappers is generally preferable:

  LogEvent().message("%s", my_verbatim_string).steal(&ll);

@param  save_to  where to save the pointer to the log-event

◆ string_value() [1/2]

LogEvent & LogEvent::string_value	(	const char *	key,
		const char *	val
	)

inline

Add a ad hoc string value with the given key.

Parameters

key	user-defined key (i.e. not wellknown). NTBS.
val	value. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ string_value() [2/2]

LogEvent & LogEvent::string_value	(	const char *	key,
		const char *	val,
		size_t	len
	)

inline

Add a ad hoc string value with the given key.

Parameters

key	user-defined key (i.e. not wellknown). NTBS.
val	value.
len	length in bytes of the value.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ subsys()

LogEvent & LogEvent::subsys ( const char * val )

inline

Which subsystem in the source was the problem detected in? ("Repl"/"InnoDB"/"Server")

Parameters

val	the subsystem. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ table_name()

LogEvent & LogEvent::table_name ( const char * val )

inline

What table were we working on?

Parameters

val	the table's name/alias. NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ thread_id()

LogEvent & LogEvent::thread_id ( longlong val )

inline

What thread / "connection ID" was the issue detected in?

Parameters

val	the thread_ID of the session the issue appeared in

Return values

the	LogEvent, for easy fluent-style chaining.

◆ type()

LogEvent & LogEvent::type ( enum_log_type val )

inline

Set log type.

Parameters

val	the log type (LOG_TYPE_ERROR)

Return values

the	LogEvent, for easy fluent-style chaining.

◆ user() [1/2]

LogEvent & LogEvent::user ( const char * val )

inline

What user were we working for at the time of the issue?

Parameters

val	the user part (of "user@host"). NTBS.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ user() [2/2]

LogEvent & LogEvent::user ( LEX_CSTRING val )

inline

What user were we working for at the time of the issue?

Parameters

val	the user part (of "user@host"). LEX_CSTRING.

Return values

the	LogEvent, for easy fluent-style chaining.

◆ verbatim()

LogEvent & LogEvent::verbatim ( const char * msg_arg )

inline

Add a message to the event, verbatim (i.e.

with no % substitutions). This is an analog of message("%s", message); it can be used when message may contain user input or a message from another subsystem that could contain % that must not be interpreted as an invitation to do % substitutions.

If you use this in a context other than an external service that has no messages registered with the server, your reviewers will say unkind things about you. Use registered messages and their error codes wherever possible!

Combining verbatim() with steal() is discouraged as it burdens the developer with the life-cycle management of verbatim's argument. This is a result of verbatim() using its argument verbatim, rather than setting it up in the LogEvent's internal allocation msg using set_message(). Hence, the LogEvent has no copy of the message, which is an optimization for the common, non-steal() case.

Parameters

msg_arg the message. % substitution will not happen.

Return values

the	LogEvent, for easy fluent-style chaining.

Member Data Documentation

◆ have_msg

bool LogEvent::have_msg

private

◆ ll

log_line* LogEvent::ll

private

◆ msg

char* LogEvent::msg

private

◆ msg_tag

const char* LogEvent::msg_tag

private

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

include/mysql/components/services/log_builtins.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~LogEvent()

◆ LogEvent()

Member Function Documentation

◆ component()

◆ errcode()

◆ errsymbol()

◆ float_value()

◆ function()

◆ host() [1/2]

◆ host() [2/2]

◆ int_value()

◆ label()

◆ lookup()

◆ lookup_quoted()

◆ lookup_quotedv()

◆ lookupv()

◆ message()

◆ message_quoted()

◆ messagev()

◆ no_telemetry()

◆ os_errmsg()

◆ os_errno()

◆ prio()

◆ query_id()

◆ set_errcode()

◆ set_message()

◆ set_message_by_errcode()

◆ source_file()

◆ source_line()

◆ sqlstate()

◆ steal()

◆ string_value() [1/2]

◆ string_value() [2/2]

◆ subsys()

◆ table_name()

◆ thread_id()

◆ type()

◆ user() [1/2]

◆ user() [2/2]

◆ verbatim()

Member Data Documentation

◆ have_msg

◆ ll

◆ msg

◆ msg_tag