DOCSP-27565-database-profiler-update (#5824) (#5924)

* DOCSP-27565-database-profiler-update

* DOCSP-27565-database-profiler-update

* DOCSP-27565-database-profiler-update

* DOCSP-27565-database-profiler-update

* DOCSP-27565-database-profiler-update

* DOCSP-27565-database-profiler-update

* DOCSP-27565-database-profiler-update

---------

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/tutorial/manage-the-database-profiler.txt

@@ -16,6 +16,7 @@ The database profiler collects detailed information about
 :ref:`database-commands` executed against a running :binary:`~bin.mongod`
 instance. This includes CRUD operations as well as configuration and
 administration commands.
+
 The profiler writes all the data it collects to a
 :data:`system.profile <<database>.system.profile>` collection, a
 :doc:`capped collection </core/capped-collections>` in each profiled
@@ -30,8 +31,8 @@ levels <database-profiling-level>`.
 When enabled, profiling has an effect on database performance and
 disk use. See :ref:`Database Profiler Overhead<database-profiling-overhead>` for more information.
 
-This document outlines a number of key administration options for the
-database profiler. For additional related information, see:
+This page shows important administration options for the
+database profiler. For additional information, see:
 
 - :ref:`profiler`
 - :ref:`Profile Command <profile-command>`
@@ -56,31 +57,32 @@ Enable and Configure Database Profiling
 
 You can enable database profiling for :binary:`~bin.mongod` instances.
 
-This section uses :binary:`~bin.mongosh` helper
-:method:`db.setProfilingLevel()` helper to enable profiling. For
-instructions using the driver, see your :driver:`driver
-documentation </>`.
+This section shows how you use the :binary:`~bin.mongosh` helper method
+:method:`db.setProfilingLevel()` to enable profiling. To use a driver
+method instead, see the :driver:`driver documentation`.
 
-When you enable profiling for a :binary:`~bin.mongod` instance, you set
+To enable profiling for a :binary:`~bin.mongod` instance, set
 the :ref:`profiling level <database-profiling-levels>` to a value
-greater than 0. The profiler records data in the :data:`system.profile
+greater than ``0``. The profiler records data in the :data:`system.profile
 <<database>.system.profile>` collection. MongoDB creates the
 :data:`system.profile <<database>.system.profile>` collection in a
 database after you enable profiling for that database.
 
 To enable profiling and set the profiling level, pass the profiling
 level to the :method:`db.setProfilingLevel()` helper. For example, to
-enable profiling for all database operations, consider the following
-operation in :binary:`~bin.mongosh`:
+enable profiling for all database operations for the currently connected
+database, run this operation in :binary:`~bin.mongosh`:
 
 .. 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:
+The shell returns the *previous* profiling level in the ``was`` field
+and sets the new level. In the following output, the ``"ok" :
+1`` key-value pair indicates the operation succeeded:
 
 .. code-block:: javascript
+   :copyable: false
 
    { "was" : 0, "slowms" : 100, "sampleRate" : 1.0, "ok" : 1 }
 
@@ -97,7 +99,7 @@ The :ref:`slowms <set-profiling-level-options-slowms>` and
 settings are *global*. When set, these settings affect all databases in
 your process.
 
-When set via the :dbcommand:`profile` command or
+When set through the :dbcommand:`profile` command or
 :method:`db.setProfilingLevel()` shell helper method, :ref:`profiling
 level <database-profiling-level>` and :ref:`filter
 <set-profiling-level-options-filter>` settings are set at the *database*
@@ -111,7 +113,7 @@ Specify the Threshold for Slow Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, the slow operation threshold is 100 milliseconds. To change
-the slow operation threshold, specify the desired threshold value in
+the slow operation threshold, specify the required threshold value in
 one of the following ways:
 
 - Set the value of ``slowms`` using the :dbcommand:`profile` command or
@@ -122,37 +124,38 @@ one of the following ways:
 - Set the value of :setting:`~operationProfiling.slowOpThresholdMs` in a
   :ref:`configuration file <configuration-options>`.
 
-For example, the following code sets the profiling level for the
-current :binary:`~bin.mongod` instance to ``1`` and sets the slow
-operation threshold for the :binary:`~bin.mongod` instance to 20
+The following example sets the profiling level for the
+currently connected database to ``1`` and sets the slow
+operation threshold for the :binary:`~bin.mongod` instance to ``20``
 milliseconds:
 
 .. code-block:: javascript
 
-   db.setProfilingLevel(1, { slowms: 20 })
+   db.setProfilingLevel( 1, { slowms: 20 } )
 
-Profiling level of ``1`` will profile operations slower than the
-threshold.
+A profiling level of ``1`` causes the profiler to record operations
+slower than the ``slowms`` threshold.
 
 .. important::
+
    The slow operation threshold applies to all databases in a
    :binary:`~bin.mongod` instance. It is used by both the database profiler
    and the diagnostic log and should be set to the highest useful value to
    avoid performance degradation.
 
-Starting in MongoDB 4.0, you can use :method:`db.setProfilingLevel()`
+You can use :method:`db.setProfilingLevel()`
 to configure ``slowms`` and ``sampleRate`` for :binary:`~bin.mongos`.
 For the :binary:`~bin.mongos`, the ``slowms`` and ``sampleRate``
 configuration settings only affect the diagnostic log and not the
 profiler since profiling is not available on :binary:`~bin.mongos`.
 [#mongos-systemlog]_
 
-For example, the following sets a :binary:`~bin.mongos` instance's slow
-operation threshold for logging slow operations:
+The following example sets a :binary:`~bin.mongos` instance's slow
+operation threshold for logging slow operations to ``20``:
 
 .. code-block:: javascript
 
-   db.setProfilingLevel(0, { slowms: 20 })
+   db.setProfilingLevel( 0, { slowms: 20 } )
 
 .. include:: /includes/extracts/4.2-changes-log-query-shapes-plan-cache-key.rst
 
@@ -161,7 +164,7 @@ operation threshold for logging slow operations:
 Profile a Random Sample of Slow Operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To profile only a randomly sampled subset of all *slow* operations ,
+To profile only a randomly sampled subset of all *slow* operations,
 specify the desired sample rate in one of the following ways:
 [#slow-oplogs]_
 
@@ -176,33 +179,33 @@ specify the desired sample rate in one of the following ways:
   :ref:`configuration file <configuration-options>`.
 
 By default, ``sampleRate`` is set to ``1.0``, meaning all *slow*
-operations are profiled. When ``sampleRate`` is set between 0 and 1,
-databases with profiling level ``1`` will only profile a randomly sampled
-percentage of *slow* operations according to ``sampleRate``.
+operations are profiled. When ``sampleRate`` is set between ``0`` and ``1``,
+databases with a profiling level ``1`` only profile a randomly sampled
+percentage of *slow* operations based on ``sampleRate``.
 
-For example, the following method sets the profiling level for the
-:binary:`~bin.mongod` to ``1`` and sets the profiler to sample 42% of
-all *slow* operations:
+The following example sets the profiling level for the currently
+connected database to ``1`` and sets the profiler to sample 42% of all
+*slow* operations:
 
 .. code-block:: javascript
 
-   db.setProfilingLevel(1, { sampleRate: 0.42 })
+   db.setProfilingLevel( 1, { sampleRate: 0.42 } )
 
 The modified sample rate value also applies to the system log.
 
-Starting in MongoDB 4.0, you can use :method:`db.setProfilingLevel()`
+You can use :method:`db.setProfilingLevel()`
 to configure ``slowms`` and ``sampleRate`` for :binary:`~bin.mongos`.
 For the :binary:`~bin.mongos`,  the ``slowms`` and
 ``sampleRate`` configuration settings only affect the diagnostic log
-and not the profiler since profiling is not available on
+and not the profiler because profiling isn't available on
 :binary:`~bin.mongos`. [#mongos-systemlog]_
 
 For example, the following sets a :binary:`~bin.mongos` instance's
 sampling rate for logging slow operations:
 
 .. code-block:: javascript
 
-   db.setProfilingLevel(0, { sampleRate: 0.42 })
+   db.setProfilingLevel( 0, { sampleRate: 0.42 } )
 
 .. important::
 
@@ -221,7 +224,7 @@ You can set a filter to control which operations are profiled and
 logged. You can set the profiling filter in one of the following ways:
 
 - Set the value of ``filter`` using the :dbcommand:`profile` command
-  or :method:`db.setProfilingLevel()` shell helper method.
+  or the :method:`db.setProfilingLevel()` shell helper method.
 
 - Set the value of :setting:`~operationProfiling.filter` in a
   :ref:`configuration file <configuration-options>`.
@@ -240,8 +243,8 @@ available on :binary:`~bin.mongos`.
    <set-profiling-level-options-sampleRate>` options do not affect the
    diagnostic log or the profiler.
 
-For example, the following :method:`db.setProfilingLevel()` method sets
-for a :binary:`~bin.mongod` instance:
+The following :method:`db.setProfilingLevel()` example sets
+the profile level for the currently connected database:
 
 - the :ref:`profiling level <set-profiling-level-level>` to ``2``,
 
@@ -259,8 +262,8 @@ for a :binary:`~bin.mongod` instance:
 Check Profiling Level
 ~~~~~~~~~~~~~~~~~~~~~
 
-To view the :ref:`profiling level <database-profiling-levels>`, issue
-the following from :binary:`~bin.mongosh`:
+To view the :ref:`profiling level <database-profiling-levels>`, run
+the following example in :binary:`~bin.mongosh`:
 
 .. code-block:: javascript
 
@@ -283,17 +286,23 @@ that should be profiled.
 Disable Profiling
 ~~~~~~~~~~~~~~~~~
 
-To disable profiling, use the following helper in
+To disable profiling, run the following example in
 :binary:`~bin.mongosh`:
 
 .. code-block:: javascript
 
    db.setProfilingLevel(0)
 
+.. note::
+
+   Disabling profiling can improve database performance and lower disk
+   use. For more information, see :ref:`Database Profiler
+   Overhead<database-profiling-overhead>`  .
+
 Enable Profiling for an Entire ``mongod`` Instance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For development purposes in testing environments, you can enable
+For development and test environments, you can enable
 database profiling for an entire :binary:`~bin.mongod` instance. The
 profiling level applies to all databases provided by the
 :binary:`~bin.mongod` instance.
@@ -313,10 +322,10 @@ This sets the profiling level to ``1``, defines slow operations as those
 that last longer than ``15`` milliseconds, and specifies that only 50%
 of *slow* operations should be profiled. [#slow-oplogs]_
 
-The ``slowms`` and ``slowOpSampleRate`` also affect which operations
-are recorded to the diagnostic log when :parameter:`logLevel` is
-set to ``0``. The ``slowms`` and ``slowOpSampleRate`` are also
-available to configure diagnostic logging for :binary:`~bin.mongos`. [#slow-oplogs]_
+The ``slowms`` and ``slowOpSampleRate`` also affect the operations that
+are recorded in the diagnostic log when :parameter:`logLevel` is set to
+``0``. The ``slowms`` and ``slowOpSampleRate`` are also available to
+configure diagnostic logging for :binary:`~bin.mongos`. [#slow-oplogs]_
 
 .. seealso::
 
@@ -365,8 +374,8 @@ operation, including reads, on the :data:`system.profile
 Example Profiler Data Queries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This section displays example queries to the :data:`system.profile <<database>.system.profile>`
-collection. For an explanation of the query output, see
+This section shows example queries on the :data:`system.profile
+<<database>.system.profile>` collection. For query output details, see
 :doc:`/reference/database-profiler`.
 
 To return the most recent 10 log entries in the :data:`system.profile <<database>.system.profile>`
@@ -391,45 +400,44 @@ the following. This example returns operations in the ``mydb`` database's
 
    db.system.profile.find( { ns : 'mydb.test' } ).pretty()
 
-To return operations slower than ``5`` milliseconds, run a query
-similar to the following:
+To return operations that take longer than 5 milliseconds to complete,
+run:
 
 .. code-block:: javascript
 
    db.system.profile.find( { millis : { $gt : 5 } } ).pretty()
 
-To return information from a certain time range, run a query similar to
-the following:
+To return operations for a specific time range, run:
 
 .. code-block:: javascript
 
-   db.system.profile.find({
-     ts : {
-       $gt: new ISODate("2012-12-09T03:00:00Z"),
-       $lt: new ISODate("2012-12-09T03:40:00Z")
-     }
-   }).pretty()
+   db.system.profile.find( {
+      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 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 } )
+   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 } )
 
 Show the Five Most Recent Events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 On a database that has profiling enabled, the ``show profile`` helper
 in :binary:`~bin.mongosh` displays the 5 most recent operations
-that took at least 1 millisecond to execute. Issue ``show profile``
-from :binary:`~bin.mongosh`, as follows:
+that took at least 1 millisecond to execute. Run ``show profile``
+from :binary:`~bin.mongosh`:
 
 .. code-block:: javascript
 
@@ -444,11 +452,16 @@ When enabled, profiling has an effect on database performance,
 especially when configured with a
 :ref:`profiling level<database-profiling-level>` of 2, or when using a
 low :ref:`threshold<database-profiling-specify-slowms-threshold>` value
-with a profiling level of 1. Profiling also consumes disk space, as it
-logs to both the :data:`system.profile <<database>.system.profile>`
-collection and also the MongoDB :option:`logfile <mongod --logpath>`.
-Carefully consider any performance and security implications before
-configuring and enabling the profiler on a production deployment.
+with a profiling level of 1.
+
+Profiling also uses disk space, because profiling
+writes logs to the :data:`system.profile <<database>.system.profile>`
+collection and the MongoDB :option:`logfile <mongod --logpath>`.
+
+.. warning::
+
+   Consider performance and storage implications before
+   you enable the profiler in a production deployment.
 
 The ``system.profile`` Collection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~