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
flag, or for a subset of checks by turning them on at runtime with the -DHAVE_DIAGNOSTIC=1
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:
WiredTiger offers the following assertions:
Assertion | Behavior in diagnostic mode | Behavior in release mode |
---|---|---|
WT_ASSERT | Always run and abort WiredTiger on failure | Never run. |
WT_ASSERT_ALWAYS | Always run and abort WiredTiger on failure | Always run and abort WiredTiger on failure. |
WT_ASSERT_OPTIONAL | Always run and abort WiredTiger on failure | Takes 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 failure | Always 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 failure | Always 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 failure | Always 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 |
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
.
Check | Behavior in diagnostic mode | Behavior in release mode |
---|---|---|
#ifdef HAVE_DIAGNOSTIC | Always run the code block | Never run the code block. |
EXTRA_DIAGNOSTICS_ENABLED | Always run the code block | Takes a WT_DIAGNOSTIC_* category as an argument and only runs when the category is enabled on the WT_CONNECTION . |
Diagnostic checks across WiredTiger are grouped into categories that get enabled/disabled together. The following diagnostic categories (WT_DIAGNOSTIC_*
) are defined:
Category | Description |
---|---|
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. |
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: