MySQL  8.0.19
Source Code Documentation
log_builtins_imp.h File Reference

Go to the source code of this file.

Classes

struct  _log_item_iter
 Iterator over the key/value pairs of a log_line. More...
 
struct  _log_line
 log_line ("log event") More...
 
class  log_builtins_imp
 Primitives for services to interact with the structured logger: functions pertaining to log_line and log_item data. More...
 
class  log_builtins_string_imp
 String primitives for logging services. More...
 
class  log_builtins_tmp_imp
 Temporary primitives for logging services. More...
 
class  log_builtins_syseventlog_imp
 Syslog/Eventlog functions for logging services. More...
 

Macros

#define LOG_BUILTINS_FILTER   "log_filter_internal"
 Name of internal filtering engine (so we may recognize it when the user refers to it by name in log_error_services). More...
 
#define LOG_BUILTINS_SINK   "log_sink_internal"
 Name of internal log writer (so we may recognize it when the user refers to it by name in log_error_services). More...
 
#define LOG_BUILTINS_BUFFER   "log_sink_buffer"
 Name of buffered log writer. More...
 
#define LOG_ERROR_SERVICES_DEFAULT   LOG_BUILTINS_FILTER "; " LOG_BUILTINS_SINK
 Default services pipeline for log_builtins_error_stack(). More...
 
#define LOG_ITEM_MAX   64
 Maximum number of key/value pairs in a log event. More...
 

Typedefs

typedef struct _log_item_iter log_item_iter
 Iterator over the key/value pairs of a log_line. More...
 
typedef struct _log_line log_line
 log_line ("log event") More...
 

Enumerations

enum  log_sink_buffer_flush_mode { LOG_BUFFER_DISCARD_ONLY, LOG_BUFFER_PROCESS_AND_DISCARD, LOG_BUFFER_REPORT_AND_KEEP }
 This defines built-in functions for use by logging services. More...
 
enum  log_error_stage {
  LOG_ERROR_STAGE_BUFFERING_EARLY, LOG_ERROR_STAGE_BUFFERING_UNIPLEX, LOG_ERROR_STAGE_BUFFERING_MULTIPLEX, LOG_ERROR_STAGE_EXTERNAL_SERVICES_AVAILABLE,
  LOG_ERROR_STAGE_SHUTTING_DOWN
}
 

Functions

void log_error_stage_set (enum log_error_stage les)
 Set error-logging stage hint (e.g. are loadable services available yet?). More...
 
enum log_error_stage log_error_stage_get (void)
 What mode is error-logging in (e.g. are loadable services available yet)? More...
 
void log_sink_buffer_flush (enum log_sink_buffer_flush_mode mode)
 Release all buffered log-events (discard_error_log_messages()), optionally after running them through the error log stack first (flush_error_log_messages()). More...
 

Macro Definition Documentation

◆ LOG_BUILTINS_BUFFER

#define LOG_BUILTINS_BUFFER   "log_sink_buffer"

Name of buffered log writer.

This sink is used internally during start-up until we know where to write and how to filter, and have all the components to do so. While we don't let the DBA add this sink to the logging pipeline once we're out of start-up, we have a name for this to be able to correctly tag its record in the service-cache.

◆ LOG_BUILTINS_FILTER

#define LOG_BUILTINS_FILTER   "log_filter_internal"

Name of internal filtering engine (so we may recognize it when the user refers to it by name in log_error_services).

◆ LOG_BUILTINS_SINK

#define LOG_BUILTINS_SINK   "log_sink_internal"

Name of internal log writer (so we may recognize it when the user refers to it by name in log_error_services).

◆ LOG_ERROR_SERVICES_DEFAULT

#define LOG_ERROR_SERVICES_DEFAULT   LOG_BUILTINS_FILTER "; " LOG_BUILTINS_SINK

Default services pipeline for log_builtins_error_stack().

◆ LOG_ITEM_MAX

#define LOG_ITEM_MAX   64

Maximum number of key/value pairs in a log event.

May be changed or abolished later.

Typedef Documentation

◆ log_item_iter

typedef struct _log_item_iter log_item_iter

Iterator over the key/value pairs of a log_line.

At present, only one iter may exist per log_line.

◆ log_line

typedef struct _log_line log_line

log_line ("log event")

Enumeration Type Documentation

◆ log_error_stage

Enumerator
LOG_ERROR_STAGE_BUFFERING_EARLY 

no log-destination yet

LOG_ERROR_STAGE_BUFFERING_UNIPLEX 

1 sink, or individual files

LOG_ERROR_STAGE_BUFFERING_MULTIPLEX 

2+ sinks writing to stderr

LOG_ERROR_STAGE_EXTERNAL_SERVICES_AVAILABLE 

external services available

LOG_ERROR_STAGE_SHUTTING_DOWN 

no external components

◆ log_sink_buffer_flush_mode

This defines built-in functions for use by logging services.

These helpers are organized into a number of APIs grouping related functionality.

This file defines internals; to use the logger from a service, include log_builtins.h instead.

For documentation of the individual functions, see log_builtins.cc

Enumerator
LOG_BUFFER_DISCARD_ONLY 
LOG_BUFFER_PROCESS_AND_DISCARD 
LOG_BUFFER_REPORT_AND_KEEP 

Function Documentation

◆ log_error_stage_get()

enum log_error_stage log_error_stage_get ( void  )

What mode is error-logging in (e.g. are loadable services available yet)?

◆ log_error_stage_set()

void log_error_stage_set ( enum log_error_stage  les)

Set error-logging stage hint (e.g. are loadable services available yet?).

◆ log_sink_buffer_flush()

void log_sink_buffer_flush ( enum log_sink_buffer_flush_mode  mode)

Release all buffered log-events (discard_error_log_messages()), optionally after running them through the error log stack first (flush_error_log_messages()).

Safe to call repeatedly (though subsequent calls will only output anything if further events occurred after the previous flush).

Parameters
modeLOG_BUFFER_DISCARD_ONLY (to just throw away the buffered events), or LOG_BUFFER_PROCESS_AND_DISCARD to filter/print them first, or LOG_BUFFER_REPORT_AND_KEEP to print an intermediate report on time-out

Release all buffered log-events (discard_error_log_messages()), optionally after running them through the error log stack first (flush_error_log_messages()).

LOG_BUFFER_DISCARD_ONLY simply releases all buffered log-events (used when called from discard_error_log_messages()).

LOG_BUFFER_PROCESS_AND_DISCARD sends the events through the configured error log stack first before discarding them. (used when called from flush_error_log_messages()). Must remain safe to call repeatedly (with subsequent calls only outputting any events added after the previous flush).

LOG_BUFFER_REPORT_AND_KEEP is used to show incremental status updates when the start-up takes unusually long. When that happens, we "report" the intermediate state using the built-in sink (as that's the only one we available to us at the time), and "keep" the events around. That way if log sinks other that the built-in one are configured, we can flush all of the buffered events there once initialization completes. (used when log_sink_buffer() detects a time-out, see also: LOG_BUFFERING_TIMEOUT_AFTER, LOG_BUFFERING_TIMEOUT_EVERY)

Parameters
modeLOG_BUFFER_DISCARD_ONLY (to just throw away the buffered events), or LOG_BUFFER_PROCESS_AND_DISCARD to filter/print them first, or LOG_BUFFER_REPORT_AND_KEEP to print an intermediate report on time-out.

To use LOG_BUFFER_REPORT_AND_KEEP in a multi-threaded environment, the caller needs to hold THR_LOCK_log_buffered while calling this; for the other modes, this function will acquire and release the lock as needed; in this second scenario, the lock will not be held while calling log_services (via log_line_submit()).