Version 12.0.0
All Classes Functions Variables Typedefs Enumerations Enumerator Modules Pages
Debugging

WiredTiger contains many assertions and diagnostic code blocks that are used to detect unexpected control flow and invalid program states. For performance reasons most checks are disabled by default and must be enabled either by compiling WiredTiger in diagnostic mode via the -DHAVE_DIAGNOSTIC=1 flag, or for a subset of checks by turning them on at runtime with the WT_CONNECTION configuration item extra_diagnostics . Note that in diagnostic mode all checks are always enabled and cannot be disabled.

There are two types of checks available. Assertions and diagnostic code blocks:

Assertions

WiredTiger offers the following assertions:

AssertionBehavior in diagnostic modeBehavior in release mode
WT_ASSERT Always run and abort WiredTiger on failureNever run.
WT_ASSERT_ALWAYS Always run and abort WiredTiger on failureAlways run and abort WiredTiger on failure.
WT_ASSERT_OPTIONAL Always run and abort WiredTiger on failureTakes a WT_DIAGNOSTIC_* category argument and only runs when the category is enabled on the WT_CONNECTION. On failure abort WiredTiger
WT_ERR_ASSERT Always run and abort WiredTiger on failureAlways run and take a WT_DIAGNOSTIC_* category argument. When the category is enabled on the WT_CONNECTION and the assertion fails abort WiredTiger. When the assertion fails and the category is not enabled on the WT_CONNECTION return a WT_ERR
WT_RET_ASSERT Always run and abort WiredTiger on failureAlways run and take a WT_DIAGNOSTIC_* category argument. When the category is enabled on the WT_CONNECTION and the assertion fails abort WiredTiger. When the assertion fails and the category is not enabled on the WT_CONNECTION return a WT_RET
WT_RET_PANIC_ASSERT Always run and abort WiredTiger on failureAlways run and take a WT_DIAGNOSTIC_* category argument. When the category is enabled on the WT_CONNECTION and the assertion fails abort WiredTiger. When the assertion fails and the category is not enabled on the WT_CONNECTION return a WT_RET_PANIC

Diagnostic Code Blocks

Longer, more extensive checks are marked by #ifdef HAVE_DIAGNOSTIC or EXTRA_DIAGNOSTICS_ENABLED blocks. Similar to assertions these checks are enabled either by running WiredTiger in diagnostic mode or by setting extra_diagnostics on the WT_CONNECTION.

CheckBehavior in diagnostic modeBehavior in release mode
#ifdef HAVE_DIAGNOSTICAlways run the code blockNever run the code block.
EXTRA_DIAGNOSTICS_ENABLED Always run the code blockTakes a WT_DIAGNOSTIC_* category as an argument and only runs when the category is enabled on the WT_CONNECTION.

Diagnostic Categories

Diagnostic checks across WiredTiger are grouped into categories that get enabled/disabled together. The following diagnostic categories (WT_DIAGNOSTIC_*) are defined:

CategoryDescription
WT_DIAGNOSTIC_ALL Enable all diagnostic categories.
WT_DIAGNOSTIC_CHECKPOINT_VALIDATE Verify data integrity of checkpoints.
WT_DIAGNOSTIC_CURSOR_CHECK Verify expected outcome of cursor operation.
WT_DIAGNOSTIC_DISK_VALIDATE Validate correctness of data written to and read from disk.
WT_DIAGNOSTIC_EVICTION_CHECK Ensure correct page state when performing eviction.
WT_DIAGNOSTIC_HS_VALIDATE Ensure correctness of records in the history store and data fetched from it.
WT_DIAGNOSTIC_KEY_OUT_OF_ORDER Verify correct ordering of keys in the btree.
WT_DIAGNOSTIC_LOG_VALIDATE Verify correctness of the Write Ahead Log.
WT_DIAGNOSTIC_PREPARED Ensure correct behavior of prepared transactions.
WT_DIAGNOSTIC_SLOW_OPERATION Identify and abort on slow operations in WiredTiger.
WT_DIAGNOSTIC_TXN_VISIBILITY Verify correct visibility of transactional data.

Configuring runtime diagnostics

Enabling assertions and diagnostic code blocks at runtime is controlled by the extra_diagnostics configuration option when opening (wiredtiger_open) or re-configuring (WT_CONNECTION::reconfigure) a wiredtiger connection. The extra_diagnostics configuration takes in a list of categories. Any category provided in the list is enabled and any category not provided is disabled. For example:

/* Open a connection to the database, enabling key ordering checks. */
error_check(wiredtiger_open(home, NULL, "create,extra_diagnostics=[key_out_of_order]", &conn));
/*
* Reconfigure the connection to turn on transaction visibility checks. As key_out_of_order is
* not provided in the new configuration it is disabled.
*/
error_check(conn->reconfigure(conn, "extra_diagnostics=[txn_visibility]"));
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_CONNECTION::reconfigure
int reconfigure(WT_CONNECTION *connection, const char *config)
Reconfigure a connection handle.