Skip to content

Commit 95d7dbf

Browse files
author
Sam Kleinman
committed
DOCS-971: edits
1 parent 4604478 commit 95d7dbf

File tree

2 files changed

+139
-95
lines changed

2 files changed

+139
-95
lines changed

‎source/reference/components.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ provide diagnostic information related to the current operation of a
9191
mongostat
9292
mongotop
9393
mongosniff
94+
mongoperf
9495

9596
GridFS
9697
------

‎source/reference/mongoperf.txt

Lines changed: 138 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,15 @@
1111
Synopsis
1212
--------
1313

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).
14+
:program:`mongoperf` is a utility to check disk I/O performance
15+
independently of MongoDB. :
16+
17+
It times tests of random disk I/O and
18+
presents the results. ou can use :program:`mongoperf` for any case
19+
apart from MongoDB. he :samp:`mmf:false` mode is completely generic.
20+
In that mode is it somewhat analogous to tools such as `bonnie++
21+
<http://sourceforge.net/projects/bonnie/>`_ (albeit mongoperf is
22+
simpler).
2123

2224
Specify options to :program:`mongoperf` using a JavaScript document.
2325

@@ -39,129 +41,170 @@ Options
3941

4042
.. option:: --help
4143

42-
Displays the options to :program:`mongoperf`.
43-
Options are specified using a JavaScript document.
44+
Displays the options to :program:`mongoperf`. Specify options to
45+
:program:`mongoperf` with a JSON document described in the
46+
:ref:`mongoperf-fields` section.
47+
48+
.. option:: <jsonconfig>
49+
50+
:program:`mongoperf` accepts configuration options in the form of a
51+
file that holds a :term:`JSON` document. You must stream the
52+
content of this file into :program:`mongoperf`, as in the following
53+
operation:
54+
55+
.. code-block:: sh
56+
57+
mongperf < config
58+
59+
In this example ``config`` is the name of a file that holds a JSON
60+
document that resembles the following example:
61+
62+
.. code-block:: javascript
63+
64+
{
65+
nThreads:<n>,
66+
fileSizeMB:<n>,
67+
sleepMicros:<n>,
68+
mmf:<bool>,
69+
r:<bool>,
70+
w:<bool>,
71+
recSizeKB:<n>,
72+
syncDelay:<n>
73+
}
74+
75+
See the :ref:`mongoperf-fields` section for documentation of each
76+
of these fields.
4477

4578
.. _mongoperf-fields:
4679

47-
Fields
48-
------
80+
Configuration Fields
81+
--------------------
4982

50-
:samp:`nThreads: {integer}`
83+
.. setting:: mongoperf.nThreads
5184

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`
85+
*Type:* Integer.
86+
87+
*Default:* 1
88+
89+
Defines the number of threads :program:`mongoperf` will use in the
90+
test. To saturate your system's storage system you will need
91+
multiple threads. Consider setting :setting:`~mongoperf.nThreads` to ``16``.
5592

56-
:samp:`fileSizeMB: {integer}`
57-
58-
test file size, default is 1Mb (1024^2 bytes)
59-
60-
:samp:`sleepMicros: {integer}`
93+
.. setting:: mongoperf.fileSizeMB
94+
95+
*Type:* Integer.
6196

62-
pause for *sleepMicros* / *nThreads* between each operation
63-
(default 0).
64-
65-
:samp:`mmf: {Boolean}`
97+
*Default:* 1 megabyte (i.e. 1024\ :sup:`2` bytes)
6698

67-
Set to *true* to use memory mapped files (default: false)
99+
Test file size.
68100

69-
:samp:`r: {Boolean}`
101+
.. setting:: mongoperf.sleepMicros
70102

71-
Set to *true* to perform reads (default: false)
72-
73-
:samp:`w: {Boolean}`
103+
*Type:* Integer.
74104

75-
Set to *true* to perform writes (default: false)
76-
77-
:samp:`recSizeKB: {integer}`
105+
*Default:* 0
106+
107+
:program:`mongoperf` will pause for the number of specified
108+
:setting:`~mongoperf.sleepMicros` divided by the
109+
:setting:`~mongoperf.nThreads` between each operation.
110+
111+
.. setting:: mongoperf.mmf
112+
113+
*Type:* Boolean.
78114

79-
Size of each write in KB
80-
81-
:samp:`syncDelay: {integer}`
115+
*Default:* ``false``
116+
117+
Set :setting:`~mongoperf.mmf` to ``true`` to use memory mapped
118+
files for the tests.
119+
120+
Generally:
82121

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.
122+
- when :setting:`~mongoperf.mmf` is ``false``, :program:`mongoperf`
123+
tests direct, physical, I/O, without caching. Use a large file
124+
size to test heavy random I/O load and to avoid I/O coalescing.
95125

126+
- when :setting:`~mongoperf.mmf` is ``true``, :program:`mongoperf`
127+
runs tests of the caching system, and can use normal file system
128+
cache. Use :program:`mmf` in this mode to test file system cache
129+
behavior with memory mapped files.
96130

97-
Use
98-
---
131+
.. setting:: mongoperf.r
99132

100-
Building
101-
~~~~~~~~
133+
*Type:* Boolean.
134+
135+
*Default:* ``false``
136+
137+
Set :setting:`~mongoperf.r` to ``true`` to perform reads as part of
138+
the tests.
139+
140+
Either :setting:`~mongoperf.r` or :setting:`~mongoperf.w` must be ``true``.
141+
142+
.. setting:: mongoperf.w
102143

103-
Run ``scons mongoperf`` or ``scons mongoperf.exe`` to build.
144+
*Type:* Boolean.
145+
146+
*Default:* ``false``
147+
148+
Set :setting:`~mongoperf.w` to ``true`` to perform writes as part of
149+
the tests.
150+
151+
Either :setting:`~mongoperf.r` or :setting:`~mongoperf.w` must be ``true``.
104152

105-
.. note::
153+
.. setting:: mongoperf.recSizeKB: {integer}`
106154

107-
.. version-added: 2.0.2
108-
:program:`mongoperf` is new, so will need a recent version of the
109-
MongoDB source code.
155+
*Type:* Integer.
156+
157+
*Default:* 4 kb
158+
159+
The size of each write operation.
160+
161+
.. setting:: mongoperf.syncDelay
110162

111-
Running
112-
~~~~~~~
163+
*Type:* Integer.
164+
165+
*Default:* 0
113166

114-
.. code-block:: javascript
167+
Seconds between disk flushes. :setting:`~mongoperf.syncDelay` is
168+
similar to :setting:`syncDelay` for :program:`mongod`.
115169

116-
mongoperf
170+
The :setting:`~mongoperf.syncDelay` controls how frequently
171+
:program:`mongoperf` performs an asynchronous disk flush the memory
172+
mapped file used for testing. By default, :program:`mongod`
173+
performs this operation every every 60 seconds. Use
174+
:setting:`~mongoperf.syncDelay` to test basic system performance of
175+
this type of operation.
117176

118-
usage:
177+
Only use :setting:`~mongoperf.syncDelay` in conjunction with
178+
:setting:`~mongoperf.mmf` set to ``true``.
119179

120-
mongoperf < myjsonconfigfile
180+
The default value of ``0`` disables this
121181

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-
}
182+
Use
183+
---
132184

185+
.. code-block:: javascript
133186

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).
187+
mongoperf < jsonconfigfile
137188

189+
Replace ``jsonconfigfile`` with the path to the :program:`mongoperf`
190+
configuration. You may also invoke :program:`mongoperf` in the
191+
following form:
138192

139193
.. code-block:: sh
140194

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
195+
echo "{nThreads:16,fileSizeMB:1000,r:true}" | ./mongoperf
148196

197+
In this operation:
149198

150-
mmf:false mode (direct i/o test)
151-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199+
- :program:`mongoperf` tests direct physical random read io's, using
200+
16 concurrent reader threads.
152201

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.
202+
- :program:`mongoperf` uses a 1 gigabyte test file.
156203

157-
mmf:true mode
158-
~~~~~~~~~~~~~
204+
Consider using ``iostat``, as invoked in the following example to
205+
monitor I/O performance during the test.
159206

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.
207+
.. code-block:: sh
165208

209+
iostat -xm 2
166210

167-
.. TODO:: previously had terse link to iostat

0 commit comments

Comments
 (0)