WiredTiger can be configured to maintain a variety of run-time and data-source statistics. As maintaining statistics may involve updating shared-memory data structures and traversing disk-based data structures, configuring statistics may decrease application performance.
The wiredtiger_open statistics
configuration must be set in order for statistics to be maintained. When configured to none
(the default), no statistics are maintained and attempting to read the statistics will result in an error. Alternatively, the fast
configuration maintains a subset of the statistics which are relatively inexpensive, and the all
configuration maintains all statistics regardless of cost.
The following example configures WiredTiger to maintain all statistics, regardless of cost:
Statistics are gathered and returned to the application using a statistics cursor, which returns key/value pairs to the application. See Statistics Data for information about accessing the gathered statistics.
When the WT_SESSION::open_cursor method is called to open a statistics cursor, the statistics configuration specifies the statistics to be gathered, similarly to the wiredtiger_open function. The fast
configuration gathers the subset of the statistics that are relatively inexpensive, and the all
configuration gathers all statistics, regardless of cost. If no configuration is specified, the current database statistics configuration is assumed.
The configuration of the WT_SESSION::open_cursor method must agree with the database configuration: if the database is configured to maintain fast
statistics, attempts to open a statistics cursor in all
mode will fail. If the database has been configured to maintain all
statistics, the statistics cursor can be configured in either fast
or all
modes. For example, an application might configure the database to maintain all available statistics, but the application might gather expensive statistics less frequently than inexpensive ones.
The following example opens a statistics cursor on the database:
The following example opens a statistics cursor on a table:
The following example opens a statistics cursor on a table, but gathering only the relatively inexpensive statistics:
The WT_SESSION::open_cursor method and the wiredtiger_open function also support the statistics configuration value clear
.
When clear
is specified to the WT_SESSION::open_cursor method, gathered statistics will be reset, where appropriate, after they are gathered. For example, a cache size statistic is not cleared because it's not expected to change rapidly over time, while the count of cursor insert operations will be cleared. This allows applications to easily monitor changes in the system over time.
The following example gathers all statistics for a table, regardless of cost, and then clears them:
When clear
is specified to the wiredtiger_open function, gathered statistics will be reset, where appropriate, after they are gathered. This applies to all statistics cursors (as if clear
was configured when the cursor was opened), as well as statistics logging, when it is configured.
The following example configures WiredTiger to maintain only relatively inexpensive statistics, and to clears statistics after they are gathered or logged:
The following example opens a statistics cursor on an open join cursor:
The statistics gathered will be organized by reference cursors participating in the join (see WT_SESSION::join); the uri of each reference cursor appears as a prefix in the description field returned as a value by the statistics cursor.
WiredTiger will optionally log database statistics into a file when the the wiredtiger_open statistics_log
configuration is set.
The resulting statistics can be displayed using the wtstats
visualization tool. For more information, see Visualizing performance with wtstats.
The following example logs statistics every 30 seconds:
Each record is formatted as a space-separated timestamp, unsigned 64-bit value and a variable length string which describes the statistic.
The timestamp format may be changed with the statistics_log.timestamp
configuration string. The timestamp
value may contain ISO C90 standard strftime conversion specifications.
The statistics the database is configured to maintain are logged, that is, configuring the database to maintain fast
or all
statistics will modify the statistics that will be logged.
Statistics for specific underlying data sources may be included by adding a list of data source URIs to the statistics_log
configuration string:
Statistics for all underlying data sources of a particular type may be included by adding a partial data source URI to the statistics_log
configuration string:
When database statistics are logged, the database home will be the first space-separated entry for each record in the log file. For example:
When data source statistics are logged, the data source's URI will be the first space-separated entry for each record in the log file. For example:
No statistics are logged for any data source for which a handle is not currently open in the database, nor will any statistics requiring the traversal of a tree (as if the statistics_fast
configuration string were set).
The location of the log files may be changed with the statistics_log.path
configuration string. The path
value value may contain ISO C90 standard strftime conversion specifications. WiredTiger will not create non-existent directories in the path, they must exist before wiredtiger_open is called.
The following example logs statistics into files named with the month, day and year:
A Python script that parses the default logging output and uses the gnuplot, utility to generate Portable Network Graphics (PNG) format graphs is included in the WiredTiger distribution in the file tools/statlog.py
.
To interactively examine statistics results, see Visualizing performance with wtstats.