From 47c53cd0df85765578e46b9a0627aee7c2da1a52 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 7 Dec 2012 14:55:56 -0500 Subject: [PATCH 1/7] DOCS-850 database profiler documentation --- source/reference/current-op.txt | 4 +- source/reference/database-profiler.txt | 208 ++++++++++++++ .../tutorial/manage-the-database-profiler.txt | 253 ++++++++++++++++++ 3 files changed, 463 insertions(+), 2 deletions(-) create mode 100644 source/reference/database-profiler.txt create mode 100644 source/tutorial/manage-the-database-profiler.txt diff --git a/source/reference/current-op.txt b/source/reference/current-op.txt index c601a1447b8..e205e2015b1 100644 --- a/source/reference/current-op.txt +++ b/source/reference/current-op.txt @@ -211,11 +211,11 @@ Output Reference the :data:`msg` field. The :data:`progress` specifies the following information: - .. data:: done + .. data:: progress.done Reports the number completed. - .. data:: total + .. data:: progress.total Reports the total number. diff --git a/source/reference/database-profiler.txt b/source/reference/database-profiler.txt new file mode 100644 index 00000000000..71ebb0739ac --- /dev/null +++ b/source/reference/database-profiler.txt @@ -0,0 +1,208 @@ +======================== +Database Profiler Output +======================== + +.. default-domain:: mongodb + +The database profiler logs information about read and write operations, +cursor operations, and database commands. To set the level of logging +for the database profiler, see +:doc:`/tutorial/manage-the-database-profiler`. + +The database profiler logs data in the ``system.profile`` collection, +which is a :term:`capped collection`. To view the profiler's output, +query this collection. + +If you view operations on a read-only database, you will still see write +operations in the ``system.profile`` collection because the database +profiler itself performs writes to ``system.profile``. + +Example Output +-------------- + +The following is an example of database profiler output for a query +operation. + +.. code-block:: javascript + + { + "ts" : ISODate("2012-12-06T16:14:33.844Z"), + "op" : "query", + "ns" : "test.system.indexes", + "query" : { + "expireAfterSeconds" : { + "$exists" : true + } + }, + "ntoreturn" : 0, + "ntoskip" : 0, + "nscanned" : 16, + "keyUpdates" : 0, + "numYield" : 0, + "lockStats" : { + "timeLockedMicros" : { + "r" : NumberLong(34), + "w" : NumberLong(0) + }, + "timeAcquiringMicros" : { + "r" : NumberLong(1), + "w" : NumberLong(2) + } + }, + "nreturned" : 0, + "responseLength" : 20, + "millis" : 0, + "client" : "127.0.0.1", + "user" : "" + } + +Output Reference +---------------- + +The database profiler reports the following values. The set of values +reported for a given operation depends on the operation: + +.. stats:: ts + + The timestamp of the operation. + +.. stats:: op + + The type of operation. The possible values are: + + - ``insert`` + - ``query`` + - ``update`` + - ``remove`` + - ``getmore`` + - ``command`` + +.. stats:: ns + + The :term:`namespace` the operation targets. MongoDB forms + namespaces using the name of the :term:`database` and the name of + the :term:`collection`. + +.. stats:: query + + The query criteria used. + +.. stats:: command + + The command used. + +.. stats:: updateobj + + The updated document. + +.. stats:: cursorid + + The ID of the cursor accessed by a ``getmore`` operation. + +.. stats:: ntoreturn + + The number of documents the operation specified to return. For + example, the :dbcommand:`profile` command returns one document, a + results document, and would have an ``ntoreturn`` value of ``1``. The + :method:`limit() ` method, if set to ``5``, would + have an ``ntoreturn`` value of ``5``. + + An ``ntoreturn`` value of ``0`` indicates that the command did not + specify a number of documents to return, as would be the case with a + simple :method:`find() ` command with no limit + specified. + +.. stats:: ntoskip + + The number of documents the :method:`skip() ` method + specified to skip. + + .. is that above statement true ??? + +.. stats:: nscanned + + The number of documents that were scanned in the index in order to + carry out the operation. If ``nscanned`` is much higher than + ``nreturned``, the database is scanning many objects to find the + target objects. Consider creating an index to improve this. + +.. stats:: moved + + A value of ``true`` indicates that the update operation moved one or + more documents to a new location on disk. This is slower than an + in-place update. Usually this occurs if a document grows in size. + +.. stats:: nmoved + + The number of documents moved on disk by the operation. + + .. is that above statement true ??? + +.. stats:: nupdated + + The number of documents updated by the operation. + +.. stats:: keyUpdates + + The number of index keys the update changed. Changing an index key + carries a small performance cost. The database must remove the old + key and insert a new key into the B-tree index. + +.. stats:: numYield + + The number of times the operation yielded to allow other operations + to complete. Typically, operations yield when they need access to + data that MongoDB has not yet fully read into memory. This allows + other operations that have data in memory to complete while MongoDB + reads in data for the yielding operation. + +.. stats:: lockStats + + The time in microseconds the operation spent acquiring and holding + locks. This field reports data for the following lock types: + + - ``R`` - global read lock + - ``W`` - global write lock + - ``r`` - database-specific read lock + - ``w`` - database-specific write lock + + .. stats:: lockStats.timeLockedMicros + + The time in microseconds the operation held a specific lock. + + .. stats:: lockStats.timeAcquiringMicros + + The time in microseconds the operation spent waiting to acquire a + specific lock. + +.. stats:: nreturned + + The number of documents returned by the operation. + +.. stats:: responseLength + + The length in bytes of the operation's result document. A large + number of bytes returned (hundreds of kilobytes or more) causes slow + performance. To limit the size of a query result document, use a + :ref:`projection `. + +.. stats:: millis + + The time in milliseconds to for the server to perform the operation. + This time does not include network time nor time to acquire the lock. + +.. stats:: client + + The IP address or hostname of the client connection where the + operation originates. + + For some commands, such as :method:`db.eval()`, the client is + ``0.0.0.0:0`` instead of an actual client. + +.. stats:: user + + The authenticated user who ran the operation. If the operation was + not run by an authenticated user, this field's value is an empty + string. + + .. is that above statement true ??? diff --git a/source/tutorial/manage-the-database-profiler.txt b/source/tutorial/manage-the-database-profiler.txt new file mode 100644 index 00000000000..07a66165eab --- /dev/null +++ b/source/tutorial/manage-the-database-profiler.txt @@ -0,0 +1,253 @@ +========================================== +Analyze Performance of Database Operations +========================================== + +.. default-domain:: mongodb + +To analyze the performance of database operations use the database +profiler, as described here. + +The database profiler logs information about database operations and +stores the information in the ``system.profile`` collection, which is a +:term:`capped collection`. The profiler stores information about read +and write operations, cursor operations, and database commands. + +You can enable database profiling on a per-database basis. By default, +profiling is disabled for a database. When you enable profiling you also +set the level of operations logged. Profiling information is recorded in +the ``system.profile`` collection. + +For related information, see: + +- :doc:`/reference/database-profiler` +- :doc:`Profile Command ` +- :doc:`/reference/current-op` + +.. _database-profiling-levels: + +Profiling Levels +---------------- + +The following profiling levels are available: + +- ``0`` - Off. Profiling is disabled. + +- ``1`` - Log operations slow operations. By default slow operations are + those slower than 100 milliseconds. You can modify this value. + +- ``2`` - Log all database operations. + +.. _database-profiling-enable-profiling: + +Enable Database Profiling and Set the Log Level +----------------------------------------------- + +You can enable database profiling from the :program:`mongod` shell or +through a driver using the :dbcommand:`profile` command. This section +will describe how to do so from the :program:`mongod` shell. To do so +from a driver, see the :doc:`driver documentation +` for your driver. + +When you enable profiling, you also set the :ref:`log level +`. Profiling information is recorded in the +``system.profile`` collection, which MongoDB creates the first time you +enable profiling in a database. + +To enable profiling and set the log level, issue the +:method:`db.setProfilingLevel()` command, passing the log level as a +parameter. For example, to enable profiling for all database operations, +issue the following from the :program:`mongod` shell: + +.. code-block:: javascript + + db.setProfilingLevel(2) + +The shell returns a document showing the *previous* level of profiling. +The ``"ok" : 1`` key-value pair indicates the operation succeeded: + +.. code-block:: javascript + + { "was" : 0, "slowms" : 100, "ok" : 1 } + +To verify the new setting, see :ref:`database-profiling-view-status`. + +Specify the Threshold for Slow Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you set the log level to ``1``, the database profiler logs only +those operations that are slower than the default threshold of 100 +milliseconds. To change this default, issue two parameters the +:method:`db.setProfilingLevel()` command: the first is the log level +``1`` and the second is the time in milliseconds at which an operation +is considered slow. + +For example, to log operations that are slower than 20 milliseconds +issue the following from the :program:`mongod` shell: + +.. code-block:: javascript + + db.setProfilingLevel(1,20) + +To verify the new setting, see :ref:`database-profiling-view-status`. + +.. _database-profiling-view-status: + +View Profiling Level +~~~~~~~~~~~~~~~~~~~~ + +To view the :ref:`profiling level `, issue +the following from the :program:`mongod` shell. + +.. code-block:: javascript + + db.getProfilingStatus() + +The shell returns a document similar to the following: + +.. code-block:: javascript + + { "was" : 0, "slowms" : 100 } + +The ``was`` field indicates the current level of profiling. + +The ``slowms`` field indicates the length of time in milliseconds an +operation must take before it is considered slow. Operations that take +longer than this threshold are logged by the database profiler if the +profiling level is ``1``, as shown in the ``was`` field. For an +explanation of log levels, see :ref:`database-profiling-levels`. + +Disable Profiling +~~~~~~~~~~~~~~~~~ + +To disable profiling, issue the following from the :program:`mongod` +shell. + +.. code-block:: javascript + + db.setProfilingLevel(0) + +Enable Profiling for an Entire :program:`mongod` Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also enable database profiling for an entire :program:`mongod` instance. +The level will apply to all databases in the instance. + +To enable profiling for a :program:`mongod` instance, issue a command +similar to the following from the command line or within the MongoDB +:doc:`configuration file `: + +.. code-block:: sh + + mongod --profile=1 --slowms=15 + +Database Profiling and Sharding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You *cannot* enable sharding on a :program:`mongos` instance. To enable +profiling in a shard cluster, you must enable profiling for each +:program:`mongod` instance in the cluster. + +View Profiler Data +------------------ + +The database profiler logs information about database operations in the +``system.profile`` collection. + +To view log information, query the ``system.profile`` collection. To +view example queries, see :ref:`database-profiling-example-queries` + +For an explanation of the output data, see +:doc:`/reference/database-profiler`. + +Show the Five Most Recent Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``show profile`` helper displays the 5 most recent +operations that took at least 1 millisecond to execute. + +To display these operations, issue ``show profile`` from the :program:`mongo` shell: + +.. code-block:: javascript + + show profile + +.. _database-profiling-example-queries: + +Example Profiler Data Queries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section displays example queries to the ``system.profile`` collection. + +To view the most recent 10 log entries in the ``system.profile`` +collection, run a query similar to the following: + +.. code-block:: javascript + + db.system.profile.find().limit(10).sort({ts:-1}) + +To view all operations except command operations (:term:`$cmd`), run a query +similar to the following: + +.. code-block:: javascript + + db.system.profile.find( function() { return this.info.indexOf('$cmd')<0 } ) + + +To view operations for a particular collection, run a query similar to +the following. This example views operations in the ``test`` collection: + +.. code-block:: javascript + + db.system.profile.find( { info: /mydb.test/ } ) + + +To view view operations slower than ``5`` milliseconds, run a query +similar to the following: + +.. code-block:: javascript + + db.system.profile.find( { millis : { $gt : 5 } } ) + + +To view information from a certain time range, run a query similar to the following: + +.. code-block:: javascript + + db.system.profile.find( + ... { ts : { $gt : new ISODate("2011-07-12T03:00:00Z") , + ... $lt : new ISODate("2011-07-12T03:40:00Z") } + ... } ) + +The following example looks at the time range, suppresses the ``user`` field +from the output to make it easier to read, and sorts the results by how +long each operation took to run: + +.. code-block:: javascript + + db.system.profile.find( + ... { ts : { $gt : new ISODate("2011-07-12T03:00:00Z") , + ... $lt : new ISODate("2011-07-12T03:40:00Z") } + ... } , { user : 0 } ).sort( { millis : -1 } ) + +Profiler Overhead +----------------- + +When enabled, profiling has a minor effect on performance. The +``system.profile`` collection, which is a :term:`capped collection`, is +set to a small size by default. + +You can change the size of the ``system.profile`` collection, you must +disable profiling, drop the ``system.profile`` collection, create a new +``system.profile`` collection, and re-enable profiling. + +Use a sequence of commands similar to the following: + +.. code-block:: javascript + + db.setProfilingLevel(0) + + db.system.profile.drop() + + db.createCollection("system.profile", {capped:true, size:4000000}) + + db.setProfilingLevel(1) From 06aee1833b6a4cdc05753a001983d761c6670bb0 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Dec 2012 16:40:31 -0500 Subject: [PATCH 2/7] DOCS-850 review edits to db profiler reference page --- source/faq/concurrency.txt | 2 + source/reference/database-profiler.txt | 100 ++++++++++++++----------- 2 files changed, 58 insertions(+), 44 deletions(-) diff --git a/source/faq/concurrency.txt b/source/faq/concurrency.txt index 94df153991d..1694f26bd52 100644 --- a/source/faq/concurrency.txt +++ b/source/faq/concurrency.txt @@ -60,6 +60,8 @@ contention in your :program:`mongod` instance. To terminate an operation, use :method:`db.killOp()`. +.. _faq-concurrency-yielding: + Does a read or write ever yield the lock? ----------------------------------------- diff --git a/source/reference/database-profiler.txt b/source/reference/database-profiler.txt index 71ebb0739ac..dd945d2c1d4 100644 --- a/source/reference/database-profiler.txt +++ b/source/reference/database-profiler.txt @@ -13,44 +13,49 @@ The database profiler logs data in the ``system.profile`` collection, which is a :term:`capped collection`. To view the profiler's output, query this collection. -If you view operations on a read-only database, you will still see write +If you turn on profiling operations on a read-only database, you will still see write operations in the ``system.profile`` collection because the database profiler itself performs writes to ``system.profile``. Example Output -------------- -The following is an example of database profiler output for a query +The following is an example of database profiler output for an update operation. .. code-block:: javascript { - "ts" : ISODate("2012-12-06T16:14:33.844Z"), - "op" : "query", - "ns" : "test.system.indexes", + "ts" : ISODate("2012-12-10T19:31:28.977Z"), + "op" : "update", + "ns" : "social.users", "query" : { - "expireAfterSeconds" : { - "$exists" : true + "name" : "jane" + }, + "updateobj" : { + "$set" : { + "likes" : [ + "basketball", + "trekking" + ] } }, - "ntoreturn" : 0, - "ntoskip" : 0, - "nscanned" : 16, + "nscanned" : 8, + "moved" : true, + "nmoved" : 1, + "nupdated" : 1, "keyUpdates" : 0, "numYield" : 0, "lockStats" : { "timeLockedMicros" : { - "r" : NumberLong(34), - "w" : NumberLong(0) + "r" : NumberLong(0), + "w" : NumberLong(258) }, "timeAcquiringMicros" : { - "r" : NumberLong(1), - "w" : NumberLong(2) + "r" : NumberLong(0), + "w" : NumberLong(7) } }, - "nreturned" : 0, - "responseLength" : 20, "millis" : 0, "client" : "127.0.0.1", "user" : "" @@ -93,7 +98,8 @@ reported for a given operation depends on the operation: .. stats:: updateobj - The updated document. + The :ref:`update document ` passed in + during an :doc:`update ` operation. .. stats:: cursorid @@ -102,14 +108,14 @@ reported for a given operation depends on the operation: .. stats:: ntoreturn The number of documents the operation specified to return. For - example, the :dbcommand:`profile` command returns one document, a - results document, and would have an ``ntoreturn`` value of ``1``. The - :method:`limit() ` method, if set to ``5``, would - have an ``ntoreturn`` value of ``5``. - - An ``ntoreturn`` value of ``0`` indicates that the command did not - specify a number of documents to return, as would be the case with a - simple :method:`find() ` command with no limit + example, the :dbcommand:`profile` command would return one document + (a results document) so the ``ntoreturn`` value would be ``1``. The + :method:`limit(5) ` command would return five + documents so the ``ntoreturn`` value would be ``5``. + + If the ``ntoreturn`` value is ``0``, the command did not specify a + number of documents to return, as would be the case with a simple + :method:`find() ` command with no limit specified. .. stats:: ntoskip @@ -117,34 +123,32 @@ reported for a given operation depends on the operation: The number of documents the :method:`skip() ` method specified to skip. - .. is that above statement true ??? - .. stats:: nscanned - The number of documents that were scanned in the index in order to - carry out the operation. If ``nscanned`` is much higher than - ``nreturned``, the database is scanning many objects to find the - target objects. Consider creating an index to improve this. + The number of documents that were scanned in the :doc:`index ` in order to + carry out the operation. + + In general, if ``nscanned`` is much higher than ``nreturned``, the + database is scanning many objects to find the target objects. + Consider creating an index to improve this. .. stats:: moved A value of ``true`` indicates that the update operation moved one or more documents to a new location on disk. This is slower than an - in-place update. Usually this occurs if a document grows in size. + in-place update. This should only happen if the document grows in size. .. stats:: nmoved The number of documents moved on disk by the operation. - .. is that above statement true ??? - .. stats:: nupdated The number of documents updated by the operation. .. stats:: keyUpdates - The number of index keys the update changed. Changing an index key + The number of :doc:`index ` keys the update changed. Changing an index key carries a small performance cost. The database must remove the old key and insert a new key into the B-tree index. @@ -154,7 +158,8 @@ reported for a given operation depends on the operation: to complete. Typically, operations yield when they need access to data that MongoDB has not yet fully read into memory. This allows other operations that have data in memory to complete while MongoDB - reads in data for the yielding operation. + reads in data for the yielding operation. For more information, + see :ref:`the FAQ on when operations yield `. .. stats:: lockStats @@ -182,13 +187,17 @@ reported for a given operation depends on the operation: .. stats:: responseLength The length in bytes of the operation's result document. A large - number of bytes returned (hundreds of kilobytes or more) causes slow - performance. To limit the size of a query result document, use a - :ref:`projection `. + ``responseLength`` can affect performance. To limit the size of a the + result document for a query operation, you can use any of the + following: + + - :ref:Projections ` + - :method:`The limit() method ` + _ :method:`The batchSize() method ` .. stats:: millis - The time in milliseconds to for the server to perform the operation. + The time in milliseconds for the server to perform the operation. This time does not include network time nor time to acquire the lock. .. stats:: client @@ -201,8 +210,11 @@ reported for a given operation depends on the operation: .. stats:: user - The authenticated user who ran the operation. If the operation was - not run by an authenticated user, this field's value is an empty - string. + The authenticated user who ran the operation. + +.. todo Test what values appear for authenticated users and add that info. + When we do, we can add back this: "If the operation was not run by an + authenticated user, this field's value is an empty string." - .. is that above statement true ??? +.. todo Consider adding documentation to our manual on the + "internal user" used by replication From 5895c6da05bae67ac002477661c2edf1fa5794da Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Dec 2012 18:01:22 -0500 Subject: [PATCH 3/7] DOCS-850 review edits to db profiler tutorial --- source/reference/database-profiler.txt | 2 +- source/reference/mongod.txt | 2 +- .../copy-databases-between-instances.txt | 2 +- .../tutorial/manage-the-database-profiler.txt | 115 +++++++++++------- 4 files changed, 71 insertions(+), 50 deletions(-) diff --git a/source/reference/database-profiler.txt b/source/reference/database-profiler.txt index dd945d2c1d4..7d08fea6449 100644 --- a/source/reference/database-profiler.txt +++ b/source/reference/database-profiler.txt @@ -193,7 +193,7 @@ reported for a given operation depends on the operation: - :ref:Projections ` - :method:`The limit() method ` - _ :method:`The batchSize() method ` + - :method:`The batchSize() method ` .. stats:: millis diff --git a/source/reference/mongod.txt b/source/reference/mongod.txt index a12de82f4f4..e7945e6db2c 100644 --- a/source/reference/mongod.txt +++ b/source/reference/mongod.txt @@ -249,7 +249,7 @@ Options .. option:: --journal Enables operation journaling to ensure write durability and data - consistency. :program:`mongodb` enables journaling by default on + consistency. :program:`mongod` enables journaling by default on 64-bit builds of versions after 2.0. .. option:: --journalOptions diff --git a/source/tutorial/copy-databases-between-instances.txt b/source/tutorial/copy-databases-between-instances.txt index 1f58cf6d9d6..e52e85c4337 100644 --- a/source/tutorial/copy-databases-between-instances.txt +++ b/source/tutorial/copy-databases-between-instances.txt @@ -13,7 +13,7 @@ entire logical databases between :program:`mongod` instances. With these commands you can copy data between instances with a simple interface without the need for an intermediate stage. The :method:`db.cloneDatabase()` and :method:`db.copyDatabase()` provide -helpers for these operations in the :program:`mongod` shell. +helpers for these operations in the :program:`mongo` shell. Data migrations that require an intermediate stage or that involve more than one database instance are beyond the scope of this diff --git a/source/tutorial/manage-the-database-profiler.txt b/source/tutorial/manage-the-database-profiler.txt index 07a66165eab..4daf0051e54 100644 --- a/source/tutorial/manage-the-database-profiler.txt +++ b/source/tutorial/manage-the-database-profiler.txt @@ -32,7 +32,7 @@ The following profiling levels are available: - ``0`` - Off. Profiling is disabled. -- ``1`` - Log operations slow operations. By default slow operations are +- ``1`` - Log slow operations. By default slow operations are those slower than 100 milliseconds. You can modify this value. - ``2`` - Log all database operations. @@ -42,9 +42,9 @@ The following profiling levels are available: Enable Database Profiling and Set the Log Level ----------------------------------------------- -You can enable database profiling from the :program:`mongod` shell or +You can enable database profiling from the :program:`mongo` shell or through a driver using the :dbcommand:`profile` command. This section -will describe how to do so from the :program:`mongod` shell. To do so +will describe how to do so from the :program:`mongo` shell. To do so from a driver, see the :doc:`driver documentation ` for your driver. @@ -56,7 +56,7 @@ enable profiling in a database. To enable profiling and set the log level, issue the :method:`db.setProfilingLevel()` command, passing the log level as a parameter. For example, to enable profiling for all database operations, -issue the following from the :program:`mongod` shell: +issue the following from the :program:`mongo` shell: .. code-block:: javascript @@ -74,19 +74,27 @@ To verify the new setting, see :ref:`database-profiling-view-status`. Specify the Threshold for Slow Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When you set the log level to ``1``, the database profiler logs only -those operations that are slower than the default threshold of 100 -milliseconds. To change this default, issue two parameters the -:method:`db.setProfilingLevel()` command: the first is the log level -``1`` and the second is the time in milliseconds at which an operation -is considered slow. +The threshold for slow operations applies to the entire +:program:`mongod` instance. When you change the threshold, you change it +for all databases on the instance. -For example, to log operations that are slower than 20 milliseconds -issue the following from the :program:`mongod` shell: +By default the threshold is 100 milliseconds. Databases with a log level +of ``1`` will log operations slower than 100 milliseconds. + +To change the threshold, issue two parameters to the +:method:`db.setProfilingLevel()` command. The first parameter sets the +log level for the current database, and the second sets the default slow +operation threshold *for the entire :program:`mongod` instance*. + +For example, the following command sets the log level for the current +database to ``0`` (disable profiling) but at the same time sets the +slow-operation threshold for the :program:`mongod` instance to 20 +milliseconds. Any database on the instance with a log level of ``1`` +will have this threshold: .. code-block:: javascript - db.setProfilingLevel(1,20) + db.setProfilingLevel(0,20) To verify the new setting, see :ref:`database-profiling-view-status`. @@ -96,7 +104,7 @@ View Profiling Level ~~~~~~~~~~~~~~~~~~~~ To view the :ref:`profiling level `, issue -the following from the :program:`mongod` shell. +the following from the :program:`mongo` shell: .. code-block:: javascript @@ -116,6 +124,12 @@ longer than this threshold are logged by the database profiler if the profiling level is ``1``, as shown in the ``was`` field. For an explanation of log levels, see :ref:`database-profiling-levels`. +To view only the log level, issue the following: + +.. code-block:: javascript + + db.getProfilingLevel() + Disable Profiling ~~~~~~~~~~~~~~~~~ @@ -129,11 +143,13 @@ shell. Enable Profiling for an Entire :program:`mongod` Instance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. todo Add a qualifier that this is not a common approach + You can also enable database profiling for an entire :program:`mongod` instance. The level will apply to all databases in the instance. -To enable profiling for a :program:`mongod` instance, issue a command -similar to the following from the command line or within the MongoDB +To enable profiling for a :program:`mongod` instance, pass the following +parameters to :program:`mongod` at startup or within the :doc:`configuration file `: .. code-block:: sh @@ -143,7 +159,7 @@ similar to the following from the command line or within the MongoDB Database Profiling and Sharding ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You *cannot* enable sharding on a :program:`mongos` instance. To enable +You *cannot* enable profiling on a :program:`mongos` instance. To enable profiling in a shard cluster, you must enable profiling for each :program:`mongod` instance in the cluster. @@ -159,54 +175,41 @@ view example queries, see :ref:`database-profiling-example-queries` For an explanation of the output data, see :doc:`/reference/database-profiler`. -Show the Five Most Recent Events -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``show profile`` helper displays the 5 most recent -operations that took at least 1 millisecond to execute. - -To display these operations, issue ``show profile`` from the :program:`mongo` shell: - -.. code-block:: javascript - - show profile - -.. _database-profiling-example-queries: - Example Profiler Data Queries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section displays example queries to the ``system.profile`` collection. +This section displays example queries to the ``system.profile`` +collection. For an explanation of the query output, see +:doc:`/reference/database-profiler`. To view the most recent 10 log entries in the ``system.profile`` collection, run a query similar to the following: .. code-block:: javascript - db.system.profile.find().limit(10).sort({ts:-1}) + db.system.profile.find().limit(10).sort( { ts : -1 } ).pretty() To view all operations except command operations (:term:`$cmd`), run a query similar to the following: .. code-block:: javascript - db.system.profile.find( function() { return this.info.indexOf('$cmd')<0 } ) - + db.system.profile.find( { op: { $ne : 'command' } } ).pretty() To view operations for a particular collection, run a query similar to -the following. This example views operations in the ``test`` collection: +the following. This example views operations in the ``mydb`` database's +``test`` collection: .. code-block:: javascript - db.system.profile.find( { info: /mydb.test/ } ) - + db.system.profile.find( { ns : 'mydb.test' } ).pretty() To view view operations slower than ``5`` milliseconds, run a query similar to the following: .. code-block:: javascript - db.system.profile.find( { millis : { $gt : 5 } } ) + db.system.profile.find( { millis : { $gt : 5 } } ).pretty() To view information from a certain time range, run a query similar to the following: @@ -214,9 +217,9 @@ To view information from a certain time range, run a query similar to the follow .. code-block:: javascript db.system.profile.find( - ... { ts : { $gt : new ISODate("2011-07-12T03:00:00Z") , - ... $lt : new ISODate("2011-07-12T03:40:00Z") } - ... } ) + { ts : { $gt : new ISODate("2012-12-09T03:00:00Z") , + $lt : new ISODate("2012-12-09T03:40:00Z") } + } ).pretty() The following example looks at the time range, suppresses the ``user`` field from the output to make it easier to read, and sorts the results by how @@ -229,18 +232,36 @@ long each operation took to run: ... $lt : new ISODate("2011-07-12T03:40:00Z") } ... } , { user : 0 } ).sort( { millis : -1 } ) +Show the Five Most Recent Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On a database for which profiling is enabled, the ``show profile`` +helper displays the 5 most recent operations that took at least 1 +millisecond to execute. Issue ``show profile`` from the :program:`mongo` +shell: + +.. code-block:: javascript + + show profile + +.. _database-profiling-example-queries: + Profiler Overhead ----------------- When enabled, profiling has a minor effect on performance. The ``system.profile`` collection, which is a :term:`capped collection`, is -set to a small size by default. +set to several thousand typical profile documents by default. + +To change the size of the ``system.profile`` collection, you must: -You can change the size of the ``system.profile`` collection, you must -disable profiling, drop the ``system.profile`` collection, create a new -``system.profile`` collection, and re-enable profiling. +1. Disable profiling. +#. Drop the ``system.profile`` collection. +#. Create a new ``system.profile`` collection. +#. Re-enable profiling. -Use a sequence of commands similar to the following: +For example, use the following sequence of commands to create a new +profile collection sized to 4000000 bytes: .. code-block:: javascript From e79e084d511374922af946190290810ffe3cb231 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Dec 2012 18:03:56 -0500 Subject: [PATCH 4/7] DOCS-850 typo --- source/reference/database-profiler.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/database-profiler.txt b/source/reference/database-profiler.txt index 7d08fea6449..b8734061bc1 100644 --- a/source/reference/database-profiler.txt +++ b/source/reference/database-profiler.txt @@ -191,7 +191,7 @@ reported for a given operation depends on the operation: result document for a query operation, you can use any of the following: - - :ref:Projections ` + - :ref:`Projections ` - :method:`The limit() method ` - :method:`The batchSize() method ` From b608740ddfb504bae6066aa40758650546b9dc30 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 10 Dec 2012 18:11:11 -0500 Subject: [PATCH 5/7] DOCS-850 minor --- source/tutorial/manage-the-database-profiler.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/tutorial/manage-the-database-profiler.txt b/source/tutorial/manage-the-database-profiler.txt index 4daf0051e54..1b1fde57460 100644 --- a/source/tutorial/manage-the-database-profiler.txt +++ b/source/tutorial/manage-the-database-profiler.txt @@ -140,13 +140,12 @@ shell. db.setProfilingLevel(0) -Enable Profiling for an Entire :program:`mongod` Instance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Enable Profiling for an Entire ``mongod`` Instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. todo Add a qualifier that this is not a common approach - -You can also enable database profiling for an entire :program:`mongod` instance. -The level will apply to all databases in the instance. +For development purposes, you can enable database profiling for an +entire :program:`mongod` instance. The profiling level will apply to all +databases in the instance. To enable profiling for a :program:`mongod` instance, pass the following parameters to :program:`mongod` at startup or within the From c6485c6d9d63d3b4777586d2ee4d1e301613fd18 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 12 Dec 2012 10:55:12 -0500 Subject: [PATCH 6/7] DOCS-850 minor review edits --- source/tutorial/manage-the-database-profiler.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/tutorial/manage-the-database-profiler.txt b/source/tutorial/manage-the-database-profiler.txt index 1b1fde57460..8e0e5ed239d 100644 --- a/source/tutorial/manage-the-database-profiler.txt +++ b/source/tutorial/manage-the-database-profiler.txt @@ -78,6 +78,9 @@ The threshold for slow operations applies to the entire :program:`mongod` instance. When you change the threshold, you change it for all databases on the instance. +.. warning:: Changing the slow-operation threshold for the database + profiler also affects the logging subsystem's slow operation threshold. + By default the threshold is 100 milliseconds. Databases with a log level of ``1`` will log operations slower than 100 milliseconds. @@ -249,8 +252,9 @@ Profiler Overhead ----------------- When enabled, profiling has a minor effect on performance. The -``system.profile`` collection, which is a :term:`capped collection`, is -set to several thousand typical profile documents by default. +``system.profile`` collection is a :term:`capped collection` with a +default size of 1 megabyte. It is able to store several thousand typical +profile documents by default. To change the size of the ``system.profile`` collection, you must: From 4eef7848b15fe6be0b982427d185d7165d67ef83 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 12 Dec 2012 13:42:29 -0500 Subject: [PATCH 7/7] DOCS-850 minor --- source/tutorial/manage-the-database-profiler.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/tutorial/manage-the-database-profiler.txt b/source/tutorial/manage-the-database-profiler.txt index 8e0e5ed239d..4fab08b6b69 100644 --- a/source/tutorial/manage-the-database-profiler.txt +++ b/source/tutorial/manage-the-database-profiler.txt @@ -78,7 +78,7 @@ The threshold for slow operations applies to the entire :program:`mongod` instance. When you change the threshold, you change it for all databases on the instance. -.. warning:: Changing the slow-operation threshold for the database +.. important:: Changing the slow-operation threshold for the database profiler also affects the logging subsystem's slow operation threshold. By default the threshold is 100 milliseconds. Databases with a log level