MySQL  8.0.17
Source Code Documentation
LogEvent Class Reference

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...
 
LogEventtype (enum_log_type val)
 Set log type. More...
 
LogEventerrcode (longlong val)
 Append a numeric error code. More...
 
LogEventerrsymbol (const char *val)
 Append a (string) error symbol. More...
 
LogEventsqlstate (const char *val)
 Append a (string) SQL state. More...
 
LogEventos_errno (longlong val)
 Append a numeric (operating system, as opposed to MySQL) error number. More...
 
LogEventos_errmsg (const char *val)
 Append a textual (operating system, as opposed to MySQL) error message, vulgo, strerror() More...
 
LogEventsource_file (const char *val)
 Which source file was the problem detected in? More...
 
LogEventsource_line (longlong val)
 Which line in the source file was the problem detected on? More...
 
LogEventfunction (const char *val)
 Which function in the source was the problem detected in? More...
 
LogEventsubsys (const char *val)
 Which subsystem in the source was the problem detected in? ("Repl"/"InnoDB"/"Server") More...
 
LogEventcomponent (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...
 
LogEventuser (LEX_CSTRING val)
 What user were we working for at the time of the issue? More...
 
LogEventuser (const char *val)
 What user were we working for at the time of the issue? More...
 
LogEventhost (LEX_CSTRING val)
 Whose session did the issue appear in? More...
 
LogEventhost (const char *val)
 Whose session did the issue appear in? More...
 
LogEventthread_id (longlong val)
 What thread / "connection ID" was the issue detected in? More...
 
LogEventquery_id (longlong val)
 What query apparently caused the issue? More...
 
LogEventtable_name (const char *val)
 What table were we working on? More...
 
LogEventprio (longlong val)
 Set error message priority. More...
 
LogEventlabel (const char *val)
 Set a label (usually "warning"/"error"/"information"). More...
 
LogEventverbatim (const char *msg_arg)
 Add a message to the event, verbatim (i.e. More...
 
LogEventmessagev (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...
 
LogEventmessage (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...
 
LogEventmessage_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...
 
LogEventlookup (longlong errcode,...)
 Find an error message by its MySQL error code. More...
 
LogEventlookupv (longlong errcode, va_list args)
 Find an error message by its MySQL error code. More...
 
LogEventlookup_quoted (longlong errcode, const char *tag,...)
 
LogEventlookup_quotedv (longlong errcode, const char *tag, va_list vl)
 
LogEventint_value (const char *key, longlong val)
 Add a ad hoc integer value with the given key. More...
 
LogEventfloat_value (const char *key, double val)
 Add a ad hoc (not "well-known") float value with the given key. More...
 
LogEventstring_value (const char *key, const char *val, size_t len)
 Add a ad hoc string value with the given key. More...
 
LogEventstring_value (const char *key, const char *val)
 Add a ad hoc string value with the given key. 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_linell
 
char * msg
 
const char * msg_tag
 

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
valthe component. NTBS.
Return values
theLogEvent, for easy fluent-style chaining.

◆ errcode()

LogEvent& LogEvent::errcode ( longlong  val)
inline

Append a numeric error code.

Parameters
valthe MySQL error code (not operating system errno!).
Return values
theLogEvent, for easy fluent-style chaining.

◆ errsymbol()

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

Append a (string) error symbol.

Parameters
valerror symbol. NTBS.
Return values
theLogEvent, 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
keyuser-defined key (i.e. not wellknown). NTBS.
valvalue.
Return values
theLogEvent, for easy fluent-style chaining.

◆ function()

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

Which function in the source was the problem detected in?

Parameters
valthe function's name. NTBS.
Return values
theLogEvent, for easy fluent-style chaining.

◆ host() [1/2]

LogEvent& LogEvent::host ( LEX_CSTRING  val)
inline

Whose session did the issue appear in?

Parameters
valthe host part (of "user@host"). LEX_CSTRING.
Return values
theLogEvent, for easy fluent-style chaining.

◆ host() [2/2]

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

Whose session did the issue appear in?

Parameters
valthe host part (of "user@host"). NTBS.
Return values
theLogEvent, 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
keyuser-defined key (i.e. not wellknown). NTBS.
valvalue.
Return values
theLogEvent, 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
valthe (custom) label to set
Return values
theLogEvent, 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
errcodeMySQL error code for the message in question, e.g. ER_STARTUP
...varargs to satisfy any % in the message
Return values
theLogEvent, 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
errcodeMySQL error code for the message in question, e.g. ER_STARTUP
argsvarargs to satisfy any % in the message
Return values
theLogEvent, 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
fmtmessage (treated as a printf-style format-string, so % substitution will happen)
...varargs to satisfy any % in the message
Return values
theLogEvent, 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
tagTag to prefix to message.
fmtmessage (treated as a printf-style format-string, so % substitution will happen)
...varargs to satisfy any % in the message
Return values
theLogEvent, 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
fmtmessage (treated as a printf-style format-string, so % substitution will happen)
apvalist to satisfy any % in the message
Return values
theLogEvent, 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
valthe error message returned by the operating system. NTBS.
Return values
theLogEvent, 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
valthe operating system errno.
Return values
theLogEvent, 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
valThe priority for this LogEvent.
Return values
theLogEvent, for easy fluent-style chaining.

◆ query_id()

LogEvent& LogEvent::query_id ( longlong  val)
inline

What query apparently caused the issue?

Parameters
valthe query_ID of the offending query
Return values
theLogEvent, 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
errcodethe error code (not operating system errno!)
Return values
truean error occurred, value not set (OOM?)
falsevalue 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
fmtformat string. % substitution will be performed.
apva_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
errcodeMySQL error code to fetch the message string for
apva_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
valthe source file's name. NTBS.
Return values
theLogEvent, 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
valthe line number.
Return values
theLogEvent, for easy fluent-style chaining.

◆ sqlstate()

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

Append a (string) SQL state.

Parameters
valthe SQLstate. NTBS.
Return values
theLogEvent, for easy fluent-style chaining.

◆ string_value() [1/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
keyuser-defined key (i.e. not wellknown). NTBS.
valvalue.
lenlength in bytes of the value.
Return values
theLogEvent, for easy fluent-style chaining.

◆ string_value() [2/2]

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

Add a ad hoc string value with the given key.

Parameters
keyuser-defined key (i.e. not wellknown). NTBS.
valvalue. NTBS.
Return values
theLogEvent, 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
valthe subsystem. NTBS.
Return values
theLogEvent, for easy fluent-style chaining.

◆ table_name()

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

What table were we working on?

Parameters
valthe table's name/alias. NTBS.
Return values
theLogEvent, for easy fluent-style chaining.

◆ thread_id()

LogEvent& LogEvent::thread_id ( longlong  val)
inline

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

Parameters
valthe thread_ID of the session the issue appeared in
Return values
theLogEvent, for easy fluent-style chaining.

◆ type()

LogEvent& LogEvent::type ( enum_log_type  val)
inline

Set log type.

Parameters
valthe log type (LOG_TYPE_ERROR)
Return values
theLogEvent, for easy fluent-style chaining.

◆ user() [1/2]

LogEvent& LogEvent::user ( LEX_CSTRING  val)
inline

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

Parameters
valthe user part (of "user@host"). LEX_CSTRING.
Return values
theLogEvent, for easy fluent-style chaining.

◆ user() [2/2]

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

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

Parameters
valthe user part (of "user@host"). NTBS.
Return values
theLogEvent, 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!

Parameters
msg_argthe message. % substitution will not happen.
Return values
theLogEvent, for easy fluent-style chaining.

Member Data Documentation

◆ 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: