Version 10.0.2
Message handling

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

FieldDescriptionType
categoryMessage category defined by WT_VERBOSE_CATEGORY String
category_idValue representation of the message categoryInteger
error_codeValue representation of the errorInteger
error_strError messageString
msgMessageString
session_dhandle_nameSession dhandle nameString
session_err_prefixDatabase error prefix defined in the WT_CONNECTION_IMPL structureString
session_nameSession nameString
threadThread idString
ts_secTime in seconds since Epoch, as reported by the system's real time clockInteger
ts_usecTime in microseconds since Epoch, as reported by the system's real time clockInteger
verbose_levelSeverity level associated with the message. See Verbose messaging for more detailsString
verbose_level_idValue representation of the verbose levelInteger

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,
}
WT_EVENT_HANDLER
The interface implemented by applications to handle error, informational and progress messages.
Definition: wiredtiger.in:3247
WT_SESSION::salvage
int salvage(WT_SESSION *session, const char *name, const char *config)
Salvage a table.
wiredtiger_open
int wiredtiger_open(const char *home, WT_EVENT_HANDLER *event_handler, const char *config, WT_CONNECTION **connectionp)
Open a connection to a database.
WT_SESSION
All data operations are performed in the context of a WT_SESSION.
Definition: wiredtiger.in:751
WT_PANIC
#define WT_PANIC
WiredTiger library panic.
Definition: wiredtiger.in:3835