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