docs/gsg_txn/C/logconfig.html

   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 xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Configuring the Logging Subsystem</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="logfileremoval.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 5. Managing DB Files</th>
  26           <td width="20%" align="right"> <a accesskey="n" href="wrapup.html">Next</a></td>
  27         </tr>
  28       </table>
  29       <hr />
  30     </div>
  31     <div class="sect1" lang="en" xml:lang="en">
  32       <div class="titlepage">
  33         <div>
  34           <div>
  35             <h2 class="title" style="clear: both"><a id="logconfig"></a>Configuring the Logging Subsystem</h2>
  36           </div>
  37         </div>
  38       </div>
  39       <div class="toc">
  40         <dl>
  41           <dt>
  42             <span class="sect2">
  43               <a href="logconfig.html#logfilesize">Setting the Log File Size</a>
  44             </span>
  45           </dt>
  46           <dt>
  47             <span class="sect2">
  48               <a href="logconfig.html#logregionsize">Configuring the Logging Region Size</a>
  49             </span>
  50           </dt>
  51           <dt>
  52             <span class="sect2">
  53               <a href="logconfig.html#inmemorylogging">Configuring In-Memory Logging</a>
  54             </span>
  55           </dt>
  56           <dt>
  57             <span class="sect2">
  58               <a href="logconfig.html#logbuffer">Setting the In-Memory Log Buffer Size</a>
  59             </span>
  60           </dt>
  61         </dl>
  62       </div>
  63       <p>
  64             You can configure the following aspects of the logging
  65             subsystem:
  66         </p>
  67       <div class="itemizedlist">
  68         <ul type="disc">
  69           <li>
  70             <p>
  71                     Size of the log files.
  72                 </p>
  73           </li>
  74           <li>
  75             <p>
  76                     Size of the logging subsystem's region.
  77                     See <a class="xref" href="logconfig.html#logregionsize" title="Configuring the Logging Region Size">Configuring the Logging Region Size</a>.
  78                 </p>
  79           </li>
  80           <li>
  81             <p>
  82                     Maintain logs entirely in-memory.
  83                     See <a class="xref" href="logconfig.html#inmemorylogging" title="Configuring In-Memory Logging">Configuring In-Memory Logging</a>
  84                     for more information.
  85                 </p>
  86           </li>
  87           <li>
  88             <p>
  89                     Size of the log buffer in memory.
  90                     See <a class="xref" href="logconfig.html#logbuffer" title="Setting the In-Memory Log Buffer Size">Setting the In-Memory Log Buffer Size</a>.
  91                 </p>
  92           </li>
  93           <li>
  94             <p>
  95                     On-disk location of your log files. See
  96                     <a class="xref" href="enabletxn.html#splittingdata" title="Identifying Specific File Locations">Identifying Specific File Locations</a>.
  97                 </p>
  98           </li>
  99         </ul>
 100       </div>
 101       <div class="sect2" lang="en" xml:lang="en">
 102         <div class="titlepage">
 103           <div>
 104             <div>
 105               <h3 class="title"><a id="logfilesize"></a>Setting the Log File Size</h3>
 106             </div>
 107           </div>
 108         </div>
 109         <p>
 110                     Whenever a pre-defined amount of data is written to a
 111                     log file (10 MB by default), DB stops using the
 112                     current log file and starts writing to a new file.
 113                     You can change the maximum amount of data contained in each
 114                     log file by using the
 115                         <span>
 116                             <code class="methodname">DB_ENV-&gt;set_lg_max()</code>
 117
 118                             method.
 119                         </span>
 120
 121                         Note that this method can be used at any time
 122                         during an application's lifetime.
 123                 </p>
 124         <p>
 125                     Setting the log file size to something larger than its
 126                     default value is largely a matter of
 127                     convenience and a reflection of the application's
 128                     preference in backup media and frequency. However, if
 129                     you set the log file size too low relative to your
 130                     application's traffic patterns, you can cause
 131                     yourself trouble.
 132                 </p>
 133         <p>
 134                     From a performance perspective, setting the log file
 135                     size to a low value can cause your active transactions to
 136                     pause their writing activities more frequently than would
 137                     occur with larger log file sizes. Whenever a
 138                     transaction completes the log buffer is flushed to
 139                     disk. Normally other transactions can continue to
 140                     write to the log buffer while this flush is in
 141                     progress. However, when one log file is being closed
 142                     and another created, all transactions must cease
 143                     writing to the log buffer until the switch over is
 144                     completed.
 145                 </p>
 146         <p>
 147                     Beyond performance concerns, using smaller log files
 148                     can cause you to use more physical files on disk.
 149                     As a result, your application could run out
 150                     of log sequence numbers, depending on how busy your
 151                     application is.
 152                 </p>
 153         <p>
 154                     Every log file is identified with a 10 digit number.
 155                     Moreover, the maximum number of log files that your application
 156                     is allowed to create in its lifetime is 2,000,000,000.
 157                 </p>
 158         <p>
 159                     For example, if your application performs 6,000 transactions per
 160                     second for 24 hours a day, and you are logging 500 bytes of
 161                     data per transaction into 10 MB log files, then you
 162                     will run out of log files in around 221 years:
 163                 </p>
 164         <pre class="programlisting">     (10 * 2^20 * 2000000000) / (6000 * 500 * 365 * 60 *60 * 24) = 221 </pre>
 165         <p>
 166                     However, if you were writing 2000 bytes of data per
 167                     transaction, and using 1 MB log files, then the same
 168                     formula shows you running out of log files in 5 years time.
 169                 </p>
 170         <p>
 171                     All of these time frames are quite long, to be sure,
 172                     but if you do run out of log files after, say, 5 years
 173                     of continuous operations, then you must reset your log
 174                     sequence numbers. To do so:
 175                 </p>
 176         <div class="orderedlist">
 177           <ol type="1">
 178             <li>
 179               <p>
 180                             Backup your databases as if to prepare for
 181                             catastrophic failure. See
 182                             <a class="xref" href="backuprestore.html" title="Backup Procedures">Backup Procedures</a>
 183                             for more information.
 184                         </p>
 185             </li>
 186             <li>
 187               <p>
 188                             Reset the log file's sequence number using the
 189                             <span class="command"><strong>db_load</strong></span> utility's
 190                             <code class="literal">-r</code> option.
 191                         </p>
 192             </li>
 193             <li>
 194               <p>
 195                             Remove all of the log files from your
 196                             environment. Note that this is the only
 197                             situation in which all of the log files are
 198                             removed from an environment; in all other
 199                             cases, at least a single log file is retained.
 200                         </p>
 201             </li>
 202             <li>
 203               <p>
 204                             Restart your application.
 205                         </p>
 206             </li>
 207           </ol>
 208         </div>
 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="logregionsize"></a>Configuring the Logging Region Size</h3>
 215             </div>
 216           </div>
 217         </div>
 218         <p>
 219                 The logging subsystem's default region size is 60 KB. The
 220                 logging region is used to store filenames, and so you may
 221                 need to increase its size if a large number of files (that
 222                 is, if you have a very large number of databases) will
 223                 be opened and registered with DB's log manager.
 224             </p>
 225         <p>
 226                 You can set the size of your logging region by using the
 227                 <span>
 228                     <code class="methodname">DB_ENV-&gt;set_lg_regionmax()</code>
 229
 230                 </span>
 231
 232                 method. Note that this method can only be called before the
 233                 first environment handle for your application is opened.
 234             </p>
 235       </div>
 236       <div class="sect2" lang="en" xml:lang="en">
 237         <div class="titlepage">
 238           <div>
 239             <div>
 240               <h3 class="title"><a id="inmemorylogging"></a>Configuring In-Memory Logging</h3>
 241             </div>
 242           </div>
 243         </div>
 244         <p>
 245                 It is possible to configure your logging subsystem such
 246                 that logs are maintained entirely in memory. When
 247                 you do this, you give up your transactional durability
 248                 guarantee. Without log files, you have no way to run
 249                 recovery so any system or software failures that you might
 250                 experience can corrupt your databases.
 251             </p>
 252         <p>
 253                 However, by giving up your durability guarantees, you can
 254                 greatly improve your application's throughput by avoiding
 255                 the disk I/O necessary to write logging information to
 256                 disk. In this case, you still retain your transactional
 257                 atomicity, consistency, and isolation guarantees.
 258             </p>
 259         <p>
 260                 To configure your logging subsystem to maintain your logs
 261                 entirely in-memory:
 262             </p>
 263         <div class="itemizedlist">
 264           <ul type="disc">
 265             <li>
 266               <p>
 267                         Make sure your log buffer is capable of holding all
 268                         log information that can accumulate during the longest
 269                         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.
 270                     </p>
 271             </li>
 272             <li>
 273               <p>
 274                         Do not run normal recovery when you open your environment.  In this configuration, there are no
 275                         log files available against which you can run recovery. As a result, if you specify recovery
 276                         when you open your environment, it is ignored.
 277                     </p>
 278             </li>
 279             <li>
 280               <p>
 281                         Specify
 282                             <span>
 283                                 <code class="literal">DB_LOG_IN_MEMORY</code> to the
 284                                 <code class="methodname">DB_ENV-&gt;log_set_config()</code>
 285
 286                             </span>
 287
 288                             method. Note that you must specify this before
 289                             your application opens its first environment
 290                             handle.
 291                     </p>
 292             </li>
 293           </ul>
 294         </div>
 295         <p>
 296                 For example:
 297             </p>
 298         <pre class="programlisting">#include &lt;stdio.h&gt;
 299 #include &lt;stdlib.h&gt;
 300
 301 #include "db.h"
 302
 303 int
 304 main(void)
 305 {
 306     int ret, ret_c;
 307     u_int32_t db_flags, env_flags;
 308     DB_ENV *envp;
 309     const char *db_home_dir = "/tmp/myEnvironment";
 310
 311     envp = NULL;
 312
 313     /* Create the environment */
 314     ret = db_env_create(&amp;envp, 0);
 315     if (ret != 0) {
 316         fprintf(stderr, "Error creating environment handle: %s\n",
 317             db_strerror(ret));
 318         return (EXIT_FAILURE);
 319     }
 320
 321     /*
 322      * Indicate that logging is to be performed only in memory.
 323      * Doing this means that we give up our transactional durability
 324      * guarantee.
 325      */
 326     envp-&gt;log_set_config(envp, DB_LOG_IN_MEMORY, 1);
 327
 328     /*
 329      * Configure the size of our log memory buffer. This must be
 330      * large enough to hold all the logging information likely
 331      * to be created for our longest running transaction. The
 332      * default size for the logging buffer is 1 MB when logging
 333      * is performed in-memory. For this example, we arbitrarily
 334      * set the logging buffer to 5 MB.
 335      */
 336      ret = envp-&gt;set_lg_bsize(envp, 5 * 1024 * 1024);
 337      if (ret != 0) {
 338         fprintf(stderr, "Error setting log buffer size: %s\n",
 339             db_strerror(ret));
 340         goto err;
 341      }
 342
 343     /*
 344      * Set the normal flags for a transactional subsystem. Note that
 345      * we DO NOT specify DB_RECOVER. Also, remember that the logging
 346      * subsystem is automatically enabled when we initialize the
 347      * transactional subsystem, so we do not explicitly enable
 348      * logging here.
 349      */
 350     env_flags = DB_CREATE     |  /* If the environment does not
 351                                   * exist, create it. */
 352                 DB_INIT_LOCK  |  /* Initialize locking */
 353                 DB_INIT_LOG   |  /* Initialize logging */
 354                 DB_INIT_MPOOL |  /* Initialize the cache */
 355                 DB_THREAD     |  /* Free-thread the env handle. */
 356                 DB_INIT_TXN;     /* Initialize transactions */
 357
 358     /* Open the environment as normal */
 359     ret = envp-&gt;open(envp, db_home_dir, env_flags, 0);
 360     if (ret != 0) {
 361         fprintf(stderr, "Error opening environment: %s\n",
 362             db_strerror(ret));
 363         goto err;
 364     }
 365
 366
 367      /*
 368       * From here, you create transactions and perform database operations
 369       * exactly as you would if you were logging to disk. This part is
 370       * omitted for brevity.
 371       */
 372
 373       ...
 374
 375 err:
 376     /* Close the databases (omitted) */
 377
 378     ...
 379
 380     /* Close the environment */
 381     if (envp != NULL) {
 382         ret_c = envp-&gt;close(envp, 0);
 383         if (ret_c != 0) {
 384             fprintf(stderr, "environment close failed: %s\n",
 385                 db_strerror(ret_c));
 386             ret = ret_c;
 387         }
 388     }
 389
 390     return (ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
 391 } </pre>
 392       </div>
 393       <div class="sect2" lang="en" xml:lang="en">
 394         <div class="titlepage">
 395           <div>
 396             <div>
 397               <h3 class="title"><a id="logbuffer"></a>Setting the In-Memory Log Buffer Size</h3>
 398             </div>
 399           </div>
 400         </div>
 401         <p>
 402                 When your application is configured for on-disk logging
 403                 (the default behavior for transactional applications), log
 404                 information is stored in-memory until the storage space
 405                 fills up, or a transaction commit forces the log
 406                 information to be flushed to disk.
 407             </p>
 408         <p>
 409                 It is possible to increase the amount of memory available
 410                 to your file log buffer. Doing so improves throughput for
 411                 long-running transactions, or for transactions that produce
 412                 a large amount of data.
 413             </p>
 414         <p>
 415                 When you have your logging subsystem configured to maintain
 416                 your log entirely in memory (see
 417                 <a class="xref" href="logconfig.html#inmemorylogging" title="Configuring In-Memory Logging">Configuring In-Memory Logging</a>), it is very important
 418                 to configure your log buffer size because the log buffer
 419                 must be capable of holding all log information that can
 420                 accumulate during the longest running transaction.
 421                 You must make sure that the in-memory log buffer size is
 422                 large enough that no transaction will ever span the entire
 423                 buffer. You must also avoid a state where the in-memory
 424                 buffer is full and no space can be freed because a
 425                 transaction that started the first log "file" is still
 426                 active.
 427             </p>
 428         <p>
 429                 When your logging subsystem is configured for on-disk
 430                 logging, the default log buffer space is 32 KB. When
 431                 in-memory logging is configured, the default log buffer
 432                 space is 1 MB.
 433             </p>
 434         <p>
 435                 You can increase your log buffer space using the
 436                 <span>
 437                     <code class="methodname">DB_ENV-&gt;set_lg_bsize()</code>
 438
 439                 </span>
 440
 441                 method. Note that this method can only be called before the
 442                 first environment handle for your application is opened.
 443             </p>
 444       </div>
 445     </div>
 446     <div class="navfooter">
 447       <hr />
 448       <table width="100%" summary="Navigation footer">
 449         <tr>
 450           <td width="40%" align="left"><a accesskey="p" href="logfileremoval.html">Prev</a> </td>
 451           <td width="20%" align="center">
 452             <a accesskey="u" href="filemanagement.html">Up</a>
 453           </td>
 454           <td width="40%" align="right"> <a accesskey="n" href="wrapup.html">Next</a></td>
 455         </tr>
 456         <tr>
 457           <td width="40%" align="left" valign="top">Removing Log Files </td>
 458           <td width="20%" align="center">
 459             <a accesskey="h" href="index.html">Home</a>
 460           </td>
 461           <td width="40%" align="right" valign="top"> Chapter 6. Summary and Examples</td>
 462         </tr>
 463       </table>
 464     </div>
 465   </body>
 466 </html>