Message handling using the WT_EVENT_HANDLER

Specific error and other message handling can be configured by passing an implementation of WT_EVENT_HANDLER to wiredtiger_open or WT_CONNECTION::open_session.

For example, both informational and error messages might be passed to an application-specific logging function that added a timestamp and logged the message to a file, and error messages might additionally be output to the stderr file stream.

Additionally, applications will normally handle WT_PANIC as a special case. WiredTiger will always call the error handler callback with WT_PANIC in the case of a fatal error requiring database restart, however, WiredTiger cannot guarantee applications will see an application thread return WT_PANIC from a WiredTiger API call. For this reason, a correctly-written WiredTiger application will likely specify at least an error handler which will immediately exit or otherwise handle fatal errors. Note that no further WiredTiger calls are required after an error handler is called with WT_PANIC (and further calls will themselves immediately fail).

The following is a programmatic example of creating a custom event handler:

/*
 * Create our own event handler structure to allow us to pass context through to event handler
 * callbacks. For this to work the WiredTiger event handler must appear first in our custom event
 * handler structure.
 */
typedef struct {
    WT_EVENT_HANDLER h;
    const char *app_id;
} CUSTOM_EVENT_HANDLER;
 
/*
 * handle_wiredtiger_error --
 *     Function to handle error callbacks from WiredTiger.
 */
int
handle_wiredtiger_error(
  WT_EVENT_HANDLER *handler, WT_SESSION *session, int error, const char *message)
{
    CUSTOM_EVENT_HANDLER *custom_handler;
 
    /* Cast the handler back to our custom handler. */
    custom_handler = (CUSTOM_EVENT_HANDLER *)handler;
 
    /* Report the error on the console. */
    fprintf(stderr, "app_id %s, thread context %p, error %d, message %s\n", custom_handler->app_id,
      (void *)session, error, message);
 
    /* Exit if the database has a fatal error. */
    if (error == WT_PANIC)
        exit(1);
 
    return (0);
}
 
/*
 * handle_wiredtiger_message --
 *     Function to handle message callbacks from WiredTiger.
 */
int
handle_wiredtiger_message(WT_EVENT_HANDLER *handler, WT_SESSION *session, const char *message)
{
    /* Cast the handler back to our custom handler. */
    printf("app id %s, thread context %p, message %s\n", ((CUSTOM_EVENT_HANDLER *)handler)->app_id,
      (void *)session, message);
 
    return (0);
}

The following is a programmatic example of configuring the previously defined custom event handler:

    CUSTOM_EVENT_HANDLER event_handler;
 
    event_handler.h.handle_error = handle_wiredtiger_error;
    event_handler.h.handle_message = handle_wiredtiger_message;
    /* Set handlers to NULL to use the default handler. */
    event_handler.h.handle_progress = NULL;
    event_handler.h.handle_close = NULL;
    event_handler.app_id = "example_event_handler";
 
    error_check(wiredtiger_open(home, (WT_EVENT_HANDLER *)&event_handler, "create", &conn));

Output format of the WT_EVENT_HANDLER

The messages generated by the WT_EVENT_HANDLER can either be encoded in a flat string style format or JSON format.

Flat string format

By default, all the messages going through the WT_EVENT_HANDLER are generated as flat strings. The example below shows a message following the flat string format:

[1637732238:116292][11175:0x123456789012], test_salvage.test_salvage.test_salvage_api(column-fix), file:test_salvage.a.wt, WT_SESSION.salvage: [WT_VERB_SALVAGE_PROGRESS][INFO]: WT_SESSION.salvage

JSON format

When configuring a WiredTiger connection through wiredtiger_open or WT_CONNECTION::reconfigure, it is possible to configure the WT_EVENT_HANDLER interface to produce JSON encoded messages via the json_output configuration option. The json_output option takes a list message categories, where each category represents a method defined by the WT_EVENT_HANDLER interface, i.e. 'message' represents the WT_EVENT_HANDLER::handle_message interface. For instance, to print all messages and error events in JSON format, the following setting needs to be added to the connection configuration:

json_output=(message, error)

See wiredtiger_open for the full list of options that can be assigned to json_output. Any event handler interface that is not specified under the json_output setting will default to using the flat string format.

The JSON output follows a specific schema with the following fields:

Field	Description	Type
category	Message category defined by `WT_VERBOSE_CATEGORY`	String
category_id	Value representation of the message category	Integer
error_code	Value representation of the error	Integer
error_str	Error message	String
msg	Message	String
session_dhandle_name	Session dhandle name	String
session_err_prefix	Database error prefix defined in the `WT_CONNECTION_IMPL` structure	String
session_name	Session name	String
thread	Thread id	String
ts_sec	Time in seconds since Epoch, as reported by the system's real time clock	Integer
ts_usec	Time in microseconds since Epoch, as reported by the system's real time clock	Integer
verbose_level	Severity level associated with the message. See Verbose messaging for more details	String
verbose_level_id	Value representation of the verbose level	Integer

Note: The information present in a message depends on the available data at the time when the message is generated. In other words, all the fields defined above may not be present in a message as shown in the example below:

{
    "category":"WT_VERB_SALVAGE_PROGRESS",
    "category_id":31,
    "msg":"WT_SESSION.salvage"
    "session_dhandle_name":"file:test_salvage.a.wt",
    "session_err_prefix":"test_salvage.test_salvage.test_salvage_api(column-fix)",
    "session_name":"WT_SESSION.salvage",
    "thread":"22604:0x123456789012",
    "ts_sec":1637730626,
    "ts_usec":20915,
    "verbose_level":"INFO",
    "verbose_level_id":0,
}