Skip to content

Commit 76a05b6

Browse files
author
Ed Costello
committed
Port of :wiki:DOCS/mongoperf to docs
1 parent 1483ffa commit 76a05b6

File tree

1 file changed

+136
-2
lines changed

1 file changed

+136
-2
lines changed

‎source/reference/mongoperf.txt

Lines changed: 136 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,33 @@
11
.. _mongoperf:
22

3-
============
3+
=============
44
``mongoperf``
5-
============
5+
=============
6+
7+
.. http://www.mongodb.org/display/DOCS/mongoperf
68

79
.. default-domain:: mongodb
810

911
Synopsis
1012
--------
1113

14+
:program:`mongoperf` is a utility to check disk I/O performance independent of MongoDB.
15+
It times tests of random disk I/O and presents the results.
16+
:program:`mongoperf` can be used to check disk subsystem performance even when MongoDB
17+
will not be used at all: the :samp:`mmf:false` mode is completely generic.
18+
In that mode is it somewhat analogous to tools such as
19+
`bonnie++ <http://sourceforge.net/projects/bonnie/>`_
20+
(albeit mongoperf is simpler).
21+
22+
Specify options to :program:`mongoperf` using a JavaScript document.
23+
1224
.. seealso::
1325

26+
* `bonnie <http://www.textuality.com/bonnie/>`_
27+
* `bonnie++ <http://sourceforge.net/projects/bonnie/>`_
28+
* `Output from an example run <https://gist.github.com/1694664>`_
29+
* `Checking Disk Performance with the mongoperf Utility <http://blog.mongodb.org/post/40769806981/checking-disk-performance-with-the-mongoperf-utility>`_
30+
1431
.. _mongoperf-options:
1532

1633
Options
@@ -22,12 +39,129 @@ Options
2239

2340
.. option:: --help
2441

42+
Displays the options to :program:`mongoperf`.
43+
Options are specified using a JavaScript document.
44+
2545
.. _mongoperf-fields:
2646

2747
Fields
2848
------
2949

50+
:samp:`nThreads: {integer}`
51+
52+
number of threads, defaults to 1. You will need several threads to
53+
test a disk subsystem to saturation. For example, try
54+
:samp:`nThreads:16`
55+
56+
:samp:`fileSizeMB: {integer}`
57+
58+
test file size, default is 1Mb (1024^2 bytes)
59+
60+
:samp:`sleepMicros: {integer}`
61+
62+
pause for *sleepMicros* / *nThreads* between each operation
63+
(default 0).
64+
65+
:samp:`mmf: {Boolean}`
66+
67+
Set to *true* to use memory mapped files (default: false)
68+
69+
:samp:`r: {Boolean}`
70+
71+
Set to *true* to perform reads (default: false)
72+
73+
:samp:`w: {Boolean}`
74+
75+
Set to *true* to perform writes (default: false)
76+
77+
:samp:`recSizeKB: {integer}`
78+
79+
Size of each write in KB
80+
81+
:samp:`syncDelay: {integer}`
82+
83+
Seconds between fsyncs, like
84+
:mongodb:option:`--syncdelay <mongod --syncdelay>` in mongod.
85+
For use with :samp:`mmf:true` mode only. The :samp:`syncDelay:{secs}`
86+
option instructs :program:`mongoperf` to
87+
perform an asynchronous fsync of the test mmap file at the
88+
specified interval.
89+
:program:`mongod` does something similar
90+
every 60 seconds, thus this can be useful to test basic system
91+
behavior in a simpler setting. This option is applicable only
92+
when using :samp:`mmf:true` mode.
93+
Currently in :program:`mongoperf` this defaults to zero, which
94+
means off.
95+
3096

3197
Use
3298
---
3399

100+
Building
101+
~~~~~~~~
102+
103+
Run ``scons mongoperf`` or ``scons mongoperf.exe`` to build.
104+
105+
.. note::
106+
107+
.. version-added: 2.0.2
108+
:program:`mongoperf` is new, so will need a recent version of the
109+
MongoDB source code.
110+
111+
Running
112+
~~~~~~~
113+
114+
.. code-block:: javascript
115+
116+
mongoperf
117+
118+
usage:
119+
120+
mongoperf < myjsonconfigfile
121+
122+
{
123+
nThreads:<n>, // number of threads (default 1)
124+
fileSizeMB:<n>, // test file size (default 1MB)
125+
sleepMicros:<n>, // pause for sleepMicros/nThreads between each operation (default 0)
126+
mmf:<bool>, // if true do i/o's via memory mapped files (default false)
127+
r:<bool>, // do reads (default false)
128+
w:<bool>, // do writes (default false)
129+
recSizeKB:<n>, // size of each write (default 4KB)
130+
syncDelay:<n> // secs between fsyncs, like --syncdelay in mongod. (default 0/never)
131+
}
132+
133+
134+
* non-mmf io is direct io (no caching). use a large file size to test
135+
making the heads move significantly and to avoid i/o coalescing
136+
* mmf io uses caching (the file system cache).
137+
138+
139+
.. code-block:: sh
140+
141+
# example invocation:
142+
# test physical (direct) random read io's, using 16 concurrent reader threads,
143+
# and a 1GB test file.
144+
echo "{nThreads:16,fileSizeMB:1000,r:true}" | ./mongoperf | tee out
145+
146+
# we might do this while it runs:
147+
iostat -xm 2
148+
149+
150+
mmf:false mode (direct i/o test)
151+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
153+
In this default mode, mongoperf performs random 4KB +direct+ (physical)
154+
disk i/o's (i.e., O_DIRECT is used on Linux).
155+
Thus this is a physical disk i/o test.
156+
157+
mmf:true mode
158+
~~~~~~~~~~~~~
159+
160+
If :samp:`mmf:true` is specified as an option, tests are performed using
161+
memory-mapped files.
162+
These files are opened in a `normal` fashion and thus *caching is allowed*.
163+
This sometimes can be used to test file system cache behavior with
164+
memory mapped files.
165+
166+
167+
.. TODO:: previously had terse link to iostat

0 commit comments

Comments
 (0)