1 files changed, 119 insertions, 0 deletions
diff --git a/src/third_party/wiredtiger/src/docs/wtstats.dox b/src/third_party/wiredtiger/src/docs/wtstats.dox
new file mode 100644
index 00000000000..c4218049a4a
--- /dev/null
+++ b/src/third_party/wiredtiger/src/docs/wtstats.dox
@@ -0,0 +1,119 @@
+/*! @page wtstats Visualizing performance with wtstats
+
+The WiredTiger distribution includes the \b wtstats tool that can be
+used to examine information generated using statistics logging (see
+@ref statistics_log) and wtperf monitoring output (see @ref wtperf).
+
+After running an application with statistics logging configured, the
+statistics output files will be in the database home directory. By
+default they are the files named with a \c WiredTigerStat prefix and a
+day and hour timestamp.
+
+To create an HTML file with a graphical representation of the statistics
+run the following command, replacing \c wiredtiger with the path to the
+WiredTiger build directory, and replacing \c database-directory with the
+application's database home directory:
+
+\code{.sh}
+python wiredtiger/tools/wtstats/wtstats.py database-directory
+\endcode
+
+If not all of the statistics files are being processed, a subset can be
+specified to the tool. For example:
+
+\code{.sh}
+python wiredtiger/tools/wtstats.py database-directory/WiredTigerStat.06.*
+\endcode
+
+In either case, a \c wtstats.html file will be generated in the current
+directory that you can open in your browser.
+
+Additional options are available, use <tt>wtstats.py --help</tt> to
+display them.
+
+The following is an example \c wtstats.html display:
+
+\image html wtstats.png "wtstats.html"
+
+@section wtstats_display Manipulating the wtstats display
+
+When you open the generated HTML file, you will see an empty page with
+some basic instructions in the middle, a sidebar containing grouped
+sections on the left, and buttons to toggle axis settings at the top
+right.
+
+To look at specific statistics, open the respective section by clicking
+on the section heading or the little arrow on the right. For example,
+click on the word "connection" in the sidebar to reveal the _connection_
+stats. Inside a group, click on any of the contained stats to toggle
+them on or off. You should see the stats graph appear in the main
+window. To toggle the entire group on or off, you can click on the
+circle next to the group heading. To look at one specific isolated
+statistic, you can shift-click on the stat. This will disable all but
+the chosen stat. Shift-clicking it again will return to the previous
+selection.
+
+Depending on your WiredTiger settings, you may have gathered a large
+number of stats. Use the search bar above the stats groups to filter
+stats on keywords. For example, typing `mem` into the search bar will
+show all stats that have the substring "mem" in them. Press the "Clear"
+button to clear the filter again.
+
+Once some stats are showing in the main view panel, use the mouse to
+hover over the graphs. A cross-hair will appear highlighting the data
+point closest to the mouse cursor and showing the stat name and value
+(y-axis). A small gray label below the x-axis will additionally show the
+exact x-axis value for the current data point.
+
+You can zoom into the graph via various mouse/trackpad gestures (some
+of which may not be supported by your input device):
+
+- use the scroll wheel (mouse)
+- use two-finger vertical scroll (touchpad)
+- use pinch-to-zoom gesture (touchpad)
+- use double-click to zoom in, shift+double-click to zoom out (mouse, touchpad)
+
+If you zoom into a dataset far enough to see individual data points,
+they will be displayed as little circles along the graph line.
+
+You can pan the graphs left/right by click-dragging the area
+horizontally.
+
+If your data contains a lot of sample points (more than pixels available
+in the current window), \c wtstats will sub-sample your data for
+efficiency reasons. When this happens, a yellow warning box will appear
+at the top next to the buttons. Due to sub-sampling, narrow spikes in a
+graph may not always be visible and you may experience some jitter when
+panning the data left/right. To ensure that all data points are
+rendered, widen your browser window or zoom into the data until the
+sub-sampling warning disappears.
+
+The \c wtstats display lets you switch modes for both the x- and y-axis
+with the buttons at the top right.
+
+The x-axis button switches between relative and absolute time, with the
+default being relative time.
+
+In "relative time" mode, every individual stat is assumed to start at
+time 0, and the x-axis displays the duration in seconds that have passed
+since the start. A useful use case for relative mode is when you record
+multiple stat files of the same data workload in succession, and want
+to compare them against each other. Relative mode will show the stat
+files overlapping, despite them being recorded at different times.
+
+Absolute time plots the stats at their exact recording times. The x-axis
+shows date and time of the events. If stat files are recorded at
+different times, they appear in the graph at different intervals on the
+x-axis. This mode is most useful to correlate events in \c wtstats with
+other data sources, for example system profiling or monitoring data,
+based on their timestamp.
+
+The y-axis button toggles between linear and logarithmic scaling mode,
+the default is linear. Linear mode is most useful if the visible stats
+have similar value ranges. However, if you compare stats of different
+magnitudes, for example "bytes in cache" vs. "files open", you can
+switch to "log-scale" mode to avoid having one graph dominate the entire
+range. The same is true for outliers in a single graph: if the outlier
+dominates the range, switch to log mode for better scaling.
+
+*/