MySQL  8.0.17
Source Code Documentation
log_shared.h File Reference
#include <mysql/mysql_lex_string.h>
#include "my_basename.h"
#include "my_inttypes.h"
#include "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_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...
 

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_BUFFERED = 1 << 22,
  LOG_ITEM_LOG_SUPPRESSED = 1 << 23, LOG_ITEM_GEN_FLOAT = 1 << 24, LOG_ITEM_GEN_INTEGER = 1 << 25, LOG_ITEM_GEN_LEX_STRING = 1 << 26,
  LOG_ITEM_GEN_CSTRING = 1 << 27
}
 item_type – what to log More...
 
enum  enum_log_item_class {
  LOG_UNTYPED = 0, LOG_CSTRING = 1, LOG_INTEGER = 2, LOG_FLOAT = 3,
  LOG_LEX_STRING = 4
}
 
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
 26 for regular timestamp, plus 7 (".123456") when using micro-seconds 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

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

(The legacy calls sql_print_(error|warning|information) have now been defined to use log_message().)

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(), sql_print_*()) as well as the lower level services using the log_line structure.

◆ log_item

typedef struct _log_item log_item

◆ log_item_class

◆ log_item_data

◆ 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

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

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

Enumeration Type Documentation

◆ 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 (char *, size_t)

◆ 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

Enumerator
LOG_ITEM_FREE_NONE 
LOG_ITEM_FREE_KEY 
LOG_ITEM_FREE_VALUE 

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

◆ 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

26 for regular timestamp, plus 7 (".123456") when using micro-seconds