-
Notifications
You must be signed in to change notification settings - Fork 5
Expand file tree
/
Copy pathdebugging.html
More file actions
180 lines (178 loc) · 13 KB
/
debugging.html
File metadata and controls
180 lines (178 loc) · 13 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>WiredTiger: Debugging</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="sorttable.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="wiredtiger.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><a href="http://wiredtiger.com/"><img alt="Logo" src="LogoFinal-header.png" alt="WiredTiger" /></a></td>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">Version 12.0.0</span>
</div>
<div id="projectbrief"><!-- 12.0.0 --></div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="banner">
<a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a>
<a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('debugging.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Debugging </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>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 <code><code>-DHAVE_DIAGNOSTIC=1</code></code> flag, or for a subset of checks by turning them on at runtime with the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> configuration item <code>extra_diagnostics</code> . Note that in diagnostic mode all checks are always enabled and cannot be disabled.</p>
<p>There are two types of checks available. Assertions and diagnostic code blocks:</p>
<h1><a class="anchor" id="assertions"></a>
Assertions</h1>
<p>WiredTiger offers the following assertions:</p>
<table class="doxtable">
<tr>
<th>Assertion</th><th>Behavior in diagnostic mode</th><th>Behavior in release mode </th></tr>
<tr>
<td><code>WT_ASSERT</code> </td><td>Always run and abort WiredTiger on failure</td><td>Never run. </td></tr>
<tr>
<td><code>WT_ASSERT_ALWAYS</code> </td><td>Always run and abort WiredTiger on failure</td><td>Always run and abort WiredTiger on failure. </td></tr>
<tr>
<td><code>WT_ASSERT_OPTIONAL</code> </td><td>Always run and abort WiredTiger on failure</td><td>Takes a <code>WT_DIAGNOSTIC_*</code> category argument and only runs when the category is enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code>. On failure abort WiredTiger </td></tr>
<tr>
<td><code>WT_ERR_ASSERT</code> </td><td>Always run and abort WiredTiger on failure</td><td>Always run and take a <code>WT_DIAGNOSTIC_*</code> category argument. When the category is enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> and the assertion fails abort WiredTiger. When the assertion fails and the category is not enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> return a WT_ERR </td></tr>
<tr>
<td><code>WT_RET_ASSERT</code> </td><td>Always run and abort WiredTiger on failure</td><td>Always run and take a <code>WT_DIAGNOSTIC_*</code> category argument. When the category is enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> and the assertion fails abort WiredTiger. When the assertion fails and the category is not enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> return a WT_RET </td></tr>
<tr>
<td><code>WT_RET_PANIC_ASSERT</code> </td><td>Always run and abort WiredTiger on failure</td><td>Always run and take a <code>WT_DIAGNOSTIC_*</code> category argument. When the category is enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> and the assertion fails abort WiredTiger. When the assertion fails and the category is not enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code> return a WT_RET_PANIC </td></tr>
</table>
<h1><a class="anchor" id="diagnostic_code_blocks"></a>
Diagnostic Code Blocks</h1>
<p>Longer, more extensive checks are marked by <code>#ifdef HAVE_DIAGNOSTIC</code> or <code>EXTRA_DIAGNOSTICS_ENABLED</code> blocks. Similar to assertions these checks are enabled either by running WiredTiger in diagnostic mode or by setting <code>extra_diagnostics</code> on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code>.</p>
<table class="doxtable">
<tr>
<th>Check</th><th>Behavior in diagnostic mode</th><th>Behavior in release mode </th></tr>
<tr>
<td><code>#ifdef HAVE_DIAGNOSTIC</code></td><td>Always run the code block</td><td>Never run the code block. </td></tr>
<tr>
<td><code>EXTRA_DIAGNOSTICS_ENABLED</code> </td><td>Always run the code block</td><td>Takes a <code>WT_DIAGNOSTIC_*</code> category as an argument and only runs when the category is enabled on the <code><a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database.">WT_CONNECTION</a></code>. </td></tr>
</table>
<h1><a class="anchor" id="diagnostic_categories"></a>
Diagnostic Categories</h1>
<p>Diagnostic checks across WiredTiger are grouped into categories that get enabled/disabled together. The following diagnostic categories (<code>WT_DIAGNOSTIC_*</code>) are defined:</p>
<table class="doxtable">
<tr>
<th>Category</th><th>Description </th></tr>
<tr>
<td><code>WT_DIAGNOSTIC_ALL</code> </td><td>Enable all diagnostic categories. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_CHECKPOINT_VALIDATE</code> </td><td>Verify data integrity of checkpoints. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_CURSOR_CHECK</code> </td><td>Verify expected outcome of cursor operation. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_DISK_VALIDATE</code> </td><td>Validate correctness of data written to and read from disk. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_EVICTION_CHECK</code> </td><td>Ensure correct page state when performing eviction. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_HS_VALIDATE</code> </td><td>Ensure correctness of records in the history store and data fetched from it. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_KEY_OUT_OF_ORDER</code> </td><td>Verify correct ordering of keys in the btree. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_LOG_VALIDATE</code> </td><td>Verify correctness of the Write Ahead Log. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_PREPARED</code> </td><td>Ensure correct behavior of prepared transactions. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_SLOW_OPERATION</code> </td><td>Identify and abort on slow operations in WiredTiger. </td></tr>
<tr>
<td><code>WT_DIAGNOSTIC_TXN_VISIBILITY</code> </td><td>Verify correct visibility of transactional data. </td></tr>
</table>
<h2><a class="anchor" id="extra_diagnostics_configuration"></a>
Configuring runtime diagnostics</h2>
<p>Enabling assertions and diagnostic code blocks at runtime is controlled by the <code>extra_diagnostics</code> configuration option when opening (<a class="el" href="group__wt.html#gacbe8d118f978f5bfc8ccb4c77c9e8813" title="Open a connection to a database.">wiredtiger_open</a>) or re-configuring (<a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#a579141678af06217b22869cbc604c6d4" title="Reconfigure a connection handle.">WT_CONNECTION::reconfigure</a>) a wiredtiger connection. The <code>extra_diagnostics</code> configuration takes in a list of categories. Any category provided in the list is enabled and any category not provided is disabled. For example:</p>
<div class="fragment"><div class="line"> <span class="comment">/* Open a connection to the database, enabling key ordering checks. */</span></div>
<div class="line"> error_check(<a class="code" href="group__wt.html#gacbe8d118f978f5bfc8ccb4c77c9e8813">wiredtiger_open</a>(home, NULL, <span class="stringliteral">"create,extra_diagnostics=[key_out_of_order]"</span>, &conn));</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/*</span></div>
<div class="line"><span class="comment"> * Reconfigure the connection to turn on transaction visibility checks. As key_out_of_order is</span></div>
<div class="line"><span class="comment"> * not provided in the new configuration it is disabled.</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> error_check(conn-><a class="code" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#a579141678af06217b22869cbc604c6d4">reconfigure</a>(conn, <span class="stringliteral">"extra_diagnostics=[txn_visibility]"</span>));</div>
</div><!-- fragment --></div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<div class="ttc" id="agroup__wt_html_gacbe8d118f978f5bfc8ccb4c77c9e8813"><div class="ttname"><a href="group__wt.html#gacbe8d118f978f5bfc8ccb4c77c9e8813">wiredtiger_open</a></div><div class="ttdeci">int wiredtiger_open(const char *home, WT_EVENT_HANDLER *event_handler, const char *config, WT_CONNECTION **connectionp)</div><div class="ttdoc">Open a connection to a database.</div></div>
<div class="ttc" id="astruct_w_t___c_o_n_n_e_c_t_i_o_n_html_a579141678af06217b22869cbc604c6d4"><div class="ttname"><a href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#a579141678af06217b22869cbc604c6d4">WT_CONNECTION::reconfigure</a></div><div class="ttdeci">int reconfigure(WT_CONNECTION *connection, const char *config)</div><div class="ttdoc">Reconfigure a connection handle.</div></div>
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">Reference Guide</a></li><li class="navelem"><a class="el" href="programming.html">Writing WiredTiger applications</a></li>
<li class="footer">Copyright (c) 2008-present MongoDB, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>