1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Configuring the Logging Subsystem</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" /> 10 <link rel="up" href="filemanagement.html" title="Chapter��5.��Managing DB Files" /> 11 <link rel="prev" href="logfileremoval.html" title="Removing Log Files" /> 12 <link rel="next" href="wrapup.html" title="Chapter��6.��Summary and Examples" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Configuring the Logging Subsystem</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="logfileremoval.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��5.��Managing DB Files</th> 23 <td width="20%" align="right">��<a accesskey="n" href="wrapup.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="logconfig"></a>Configuring the Logging Subsystem</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="logconfig.html#logfilesize">Setting the Log File Size</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="logconfig.html#logregionsize">Configuring the Logging Region Size</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="logconfig.html#inmemorylogging">Configuring In-Memory Logging</a> 51 </span> 52 </dt> 53 <dt> 54 <span class="sect2"> 55 <a href="logconfig.html#logbuffer">Setting the In-Memory Log Buffer Size</a> 56 </span> 57 </dt> 58 </dl> 59 </div> 60 <p> 61 You can configure the following aspects of the logging 62 subsystem: 63 </p> 64 <div class="itemizedlist"> 65 <ul type="disc"> 66 <li> 67 <p> 68 Size of the log files. 69 </p> 70 </li> 71 <li> 72 <p> 73 Size of the logging subsystem's region. 74 See <a class="xref" href="logconfig.html#logregionsize" title="Configuring the Logging Region Size">Configuring the Logging Region Size</a>. 75 </p> 76 </li> 77 <li> 78 <p> 79 Maintain logs entirely in-memory. 80 See <a class="xref" href="logconfig.html#inmemorylogging" title="Configuring In-Memory Logging">Configuring In-Memory Logging</a> 81 for more information. 82 </p> 83 </li> 84 <li> 85 <p> 86 Size of the log buffer in memory. 87 See <a class="xref" href="logconfig.html#logbuffer" title="Setting the In-Memory Log Buffer Size">Setting the In-Memory Log Buffer Size</a>. 88 </p> 89 </li> 90 <li> 91 <p> 92 On-disk location of your log files. See 93 <a class="xref" href="enabletxn.html#splittingdata" title="Identifying Specific File Locations">Identifying Specific File Locations</a>. 94 </p> 95 </li> 96 </ul> 97 </div> 98 <div class="sect2" lang="en" xml:lang="en"> 99 <div class="titlepage"> 100 <div> 101 <div> 102 <h3 class="title"><a id="logfilesize"></a>Setting the Log File Size</h3> 103 </div> 104 </div> 105 </div> 106 <p> 107 Whenever a pre-defined amount of data is written to a 108 log file (10 MB by default), DB stops using the 109 current log file and starts writing to a new file. 110 You can change the maximum amount of data contained in each 111 log file by using the 112 113 <span> 114 <code class="methodname">EnvironmentConfig.setMaxLogFileSize()</code> 115 method. 116 </span> 117 Note that this method can be used at any time 118 during an application's lifetime. 119 </p> 120 <p> 121 Setting the log file size to something larger than its 122 default value is largely a matter of 123 convenience and a reflection of the application's 124 preference in backup media and frequency. However, if 125 you set the log file size too low relative to your 126 application's traffic patterns, you can cause 127 yourself trouble. 128 </p> 129 <p> 130 From a performance perspective, setting the log file 131 size to a low value can cause your active transactions to 132 pause their writing activities more frequently than would 133 occur with larger log file sizes. Whenever a 134 transaction completes the log buffer is flushed to 135 disk. Normally other transactions can continue to 136 write to the log buffer while this flush is in 137 progress. However, when one log file is being closed 138 and another created, all transactions must cease 139 writing to the log buffer until the switch over is 140 completed. 141 </p> 142 <p> 143 Beyond performance concerns, using smaller log files 144 can cause you to use more physical files on disk. 145 As a result, your application could run out 146 of log sequence numbers, depending on how busy your 147 application is. 148 </p> 149 <p> 150 Every log file is identified with a 10 digit number. 151 Moreover, the maximum number of log files that your application 152 is allowed to create in its lifetime is 2,000,000,000. 153 </p> 154 <p> 155 For example, if your application performs 6,000 transactions per 156 second for 24 hours a day, and you are logging 500 bytes of 157 data per transaction into 10 MB log files, then you 158 will run out of log files in around 221 years: 159 </p> 160 <pre class="programlisting"> (10 * 2^20 * 2000000000) / (6000 * 500 * 365 * 60 *60 * 24) = 221 </pre> 161 <p> 162 However, if you were writing 2000 bytes of data per 163 transaction, and using 1 MB log files, then the same 164 formula shows you running out of log files in 5 years time. 165 </p> 166 <p> 167 All of these time frames are quite long, to be sure, 168 but if you do run out of log files after, say, 5 years 169 of continuous operations, then you must reset your log 170 sequence numbers. To do so: 171 </p> 172 <div class="orderedlist"> 173 <ol type="1"> 174 <li> 175 <p> 176 Backup your databases as if to prepare for 177 catastrophic failure. See 178 <a class="xref" href="backuprestore.html" title="Backup Procedures">Backup Procedures</a> 179 for more information. 180 </p> 181 </li> 182 <li> 183 <p> 184 Reset the log file's sequence number using the 185 <span class="command"><strong>db_load</strong></span> utility's 186 <code class="literal">-r</code> option. 187 </p> 188 </li> 189 <li> 190 <p> 191 Remove all of the log files from your 192 environment. Note that this is the only 193 situation in which all of the log files are 194 removed from an environment; in all other 195 cases, at least a single log file is retained. 196 </p> 197 </li> 198 <li> 199 <p> 200 Restart your application. 201 </p> 202 </li> 203 </ol> 204 </div> 205 </div> 206 <div class="sect2" lang="en" xml:lang="en"> 207 <div class="titlepage"> 208 <div> 209 <div> 210 <h3 class="title"><a id="logregionsize"></a>Configuring the Logging Region Size</h3> 211 </div> 212 </div> 213 </div> 214 <p> 215 The logging subsystem's default region size is 60 KB. The 216 logging region is used to store filenames, and so you may 217 need to increase its size if a large number of files (that 218 is, if you have a very large number of databases) will 219 be opened and registered with DB's log manager. 220 </p> 221 <p> 222 You can set the size of your logging region by using the 223 224 <span> 225 <code class="methodname">EnvironmentConfig.setLogRegionSize()</code> 226 </span> 227 method. Note that this method can only be called before the 228 first environment handle for your application is opened. 229 </p> 230 </div> 231 <div class="sect2" lang="en" xml:lang="en"> 232 <div class="titlepage"> 233 <div> 234 <div> 235 <h3 class="title"><a id="inmemorylogging"></a>Configuring In-Memory Logging</h3> 236 </div> 237 </div> 238 </div> 239 <p> 240 It is possible to configure your logging subsystem such 241 that logs are maintained entirely in memory. When 242 you do this, you give up your transactional durability 243 guarantee. Without log files, you have no way to run 244 recovery so any system or software failures that you might 245 experience can corrupt your databases. 246 </p> 247 <p> 248 However, by giving up your durability guarantees, you can 249 greatly improve your application's throughput by avoiding 250 the disk I/O necessary to write logging information to 251 disk. In this case, you still retain your transactional 252 atomicity, consistency, and isolation guarantees. 253 </p> 254 <p> 255 To configure your logging subsystem to maintain your logs 256 entirely in-memory: 257 </p> 258 <div class="itemizedlist"> 259 <ul type="disc"> 260 <li> 261 <p> 262 Make sure your log buffer is capable of holding all 263 log information that can accumulate during the longest 264 running transaction. See <a class="xref" href="logconfig.html#logbuffer" title="Setting the In-Memory Log Buffer Size">Setting the In-Memory Log Buffer Size</a> for details. 265 </p> 266 </li> 267 <li> 268 <p> 269 Do not run normal recovery when you open your environment. In this configuration, there are no 270 log files available against which you can run recovery. As a result, if you specify recovery 271 when you open your environment, it is ignored. 272 </p> 273 </li> 274 <li> 275 <p> 276 Specify 277 278 <span> 279 <code class="literal">true</code> 280 to the 281 <code class="methodname">EnvironmentConfig.setLogInMemory()</code> 282 </span> 283 method. Note that you must specify this before 284 your application opens its first environment 285 handle. 286 </p> 287 </li> 288 </ul> 289 </div> 290 <p> 291 For example: 292 </p> 293 <pre class="programlisting">package db.txn; 294 295import com.sleepycat.db.Database; 296import com.sleepycat.db.DatabaseConfig; 297import com.sleepycat.db.DatabaseEntry; 298import com.sleepycat.db.DatabaseException; 299import com.sleepycat.db.Environment; 300import com.sleepycat.db.EnvironmentConfig; 301 302import java.io.File; 303 304... 305 306Database myDatabase = null; 307Environment myEnv = null; 308try { 309 EnvironmentConfig myEnvConfig = new EnvironmentConfig(); 310 myEnvConfig.setInitializeCache(true); 311 myEnvConfig.setInitializeLocking(true); 312 myEnvConfig.setInitializeLogging(true); 313 myEnvConfig.setTransactional(true); 314 315 // Specify in-memory logging 316 myEnvConfig.setLogInMemory(true); 317 318 // Specify the in-memory log buffer size. 319 myEnvConfig.setLogBufferSize(10 * 1024 * 1024); 320 321 myEnv = new Environment(new File("/my/env/home"), 322 myEnvConfig); 323 324 // From here, you open databases, create transactions and 325 // perform database operations exactly as you would if you 326 // were logging to disk. This part is omitted for brevity. </pre> 327 </div> 328 <div class="sect2" lang="en" xml:lang="en"> 329 <div class="titlepage"> 330 <div> 331 <div> 332 <h3 class="title"><a id="logbuffer"></a>Setting the In-Memory Log Buffer Size</h3> 333 </div> 334 </div> 335 </div> 336 <p> 337 When your application is configured for on-disk logging 338 (the default behavior for transactional applications), log 339 information is stored in-memory until the storage space 340 fills up, or a transaction commit forces the log 341 information to be flushed to disk. 342 </p> 343 <p> 344 It is possible to increase the amount of memory available 345 to your file log buffer. Doing so improves throughput for 346 long-running transactions, or for transactions that produce 347 a large amount of data. 348 </p> 349 <p> 350 When you have your logging subsystem configured to maintain 351 your log entirely in memory (see 352 <a class="xref" href="logconfig.html#inmemorylogging" title="Configuring In-Memory Logging">Configuring In-Memory Logging</a>), it is very important 353 to configure your log buffer size because the log buffer 354 must be capable of holding all log information that can 355 accumulate during the longest running transaction. 356 You must make sure that the in-memory log buffer size is 357 large enough that no transaction will ever span the entire 358 buffer. You must also avoid a state where the in-memory 359 buffer is full and no space can be freed because a 360 transaction that started the first log "file" is still 361 active. 362 </p> 363 <p> 364 When your logging subsystem is configured for on-disk 365 logging, the default log buffer space is 32 KB. When 366 in-memory logging is configured, the default log buffer 367 space is 1 MB. 368 </p> 369 <p> 370 You can increase your log buffer space using the 371 372 <span> 373 <code class="methodname">EnvironmentConfig.setLogBufferSize()</code> 374 </span> 375 method. Note that this method can only be called before the 376 first environment handle for your application is opened. 377 </p> 378 </div> 379 </div> 380 <div class="navfooter"> 381 <hr /> 382 <table width="100%" summary="Navigation footer"> 383 <tr> 384 <td width="40%" align="left"><a accesskey="p" href="logfileremoval.html">Prev</a>��</td> 385 <td width="20%" align="center"> 386 <a accesskey="u" href="filemanagement.html">Up</a> 387 </td> 388 <td width="40%" align="right">��<a accesskey="n" href="wrapup.html">Next</a></td> 389 </tr> 390 <tr> 391 <td width="40%" align="left" valign="top">Removing Log Files��</td> 392 <td width="20%" align="center"> 393 <a accesskey="h" href="index.html">Home</a> 394 </td> 395 <td width="40%" align="right" valign="top">��Chapter��6.��Summary and Examples</td> 396 </tr> 397 </table> 398 </div> 399 </body> 400</html> 401