DOCS-10546: random sampling for profiler/logging

Author: nlarew

source/administration/analyzing-mongodb-performance.txt

@@ -179,74 +179,29 @@ information.
 Database Profiling
 ------------------
 
-MongoDB's "Profiler" is a database profiling system that can help identify
-inefficient queries and operations.
+The :doc:`/tutorial/manage-the-database-profiler` collects detailed
+information about operations run against a mongod instance. The
+profiler's output can help to identify inefficient queries and
+operations.
 
-The following profiling levels are available:
-
-.. list-table::
-   :header-rows: 1
-
-   * - **Level**
-
-     - **Setting**
-
-   * - 0
-
-     - Off. No profiling
-
-   * - 1
-
-     - On. Only includes *"slow"* operations
-
-   * - 2
-
-     - On. Includes *all* operations
+You can enable and configure profiling for individual databases or for
+all databases on a :program:`mongod` instance.
+Profiler settings affect only a single :program:`mongod` instance and
+will not propagate across a :term:`replica set` or :term:`sharded
+cluster`.
 
-Enable the profiler by setting the
-:dbcommand:`profile` value using the following command in the
-:program:`mongo` shell:
+See :doc:`/tutorial/manage-the-database-profiler` for information on
+enabling and configuring the profiler.
 
-.. code-block:: javascript
-
-   db.setProfilingLevel(1)
-
-The :setting:`~operationProfiling.slowOpThresholdMs` setting defines what constitutes a "slow"
-operation. To set the threshold above which the profiler considers
-operations "slow" (and thus, included in the level ``1`` profiling
-data), you can configure :setting:`~operationProfiling.slowOpThresholdMs` at runtime as an argument to
-the :method:`db.setProfilingLevel()` operation.
+The following profiling levels are available:
 
-.. see:: The documentation of :method:`db.setProfilingLevel()` for more
-   information.
+.. include:: /includes/database-profiler-levels.rst
 
-By default, :program:`mongod` records all "slow" queries to its
-:setting:`log <logpath>`, as defined by :setting:`~operationProfiling.slowOpThresholdMs`.
+.. include:: /includes/warning-profiler-performance.rst
 
 .. note::
+   .. include:: /includes/fact-log-slow-queries.rst
 
-   Because the database profiler can negatively impact
-   performance, only enable profiling for strategic intervals and as
-   minimally as possible on production systems.
-
-   You may enable profiling on a per-:program:`mongod` basis. This
-   setting will not propagate across a :term:`replica set` or
-   :term:`sharded cluster`.
-
-You can view the output of the profiler in the ``system.profile``
-collection of your database by issuing the ``show profile`` command in
-the :program:`mongo` shell, or with the following operation:
-
-.. code-block:: javascript
-
-   db.system.profile.find( { millis : { $gt : 100 } } )
-
-This returns all operations that lasted longer than 100 milliseconds.
-Ensure that the value specified here (``100``, in this example) is above the
-:setting:`~operationProfiling.slowOpThresholdMs` threshold.
-
-You must use the :operator:`$query` operator to access the ``query``
-field of documents within ``system.profile``.
 
 .. class:: hidden
 

source/includes/apiargs-dbcommand-profile-fields.yaml

@@ -0,0 +1,73 @@
+position: 1
+name: profile
+type: int
+optional: false
+description: |
+  Default: 0
+
+  | Specifies which operations should be profiled.
+  | The following profiler levels are available:
+  
+  .. list-table::
+     :header-rows: 1
+     :widths: 25 75
+     
+     * - Level
+       - Description
+
+     * - ``-1``
+       - Returns the current profiler level, but does not change it.
+
+     * - ``0``
+       - Turns the profiler off so that it does not
+         collect any data.
+         This is the default profiler level.
+
+     * - ``1``
+       - Sets the profiler to collect data for operations that take
+         longer than the value of ``slowms``.
+
+     * - ``2``
+       - Sets the profiler to collect data for all operations.
+
+interface: dbcommand
+operation: profile
+arg_name: field
+---
+position: 2
+name: slowms
+type: int
+optional: true
+description: |
+  Default: 100
+
+  .. include:: /includes/dbcommand-slowms-definition.rst
+
+  .. note::
+     This argument affects the same setting as the configuration option
+     :setting:`~operationProfiling.slowOpThresholdMs`.
+
+
+interface: dbcommand
+operation: profile
+arg_name: field
+---
+position: 3
+name: sampleRate
+type: double
+optional: true
+description: |
+  Default: 1.0
+
+  | The fraction of *slow* operations that should be profiled.
+  | ``sampleRate`` accepts values between 0 and 1, inclusive.
+
+  .. note::
+     This argument affects the same setting as the configuration option
+     :setting:`~operationProfiling.slowOpSampleRate`.
+
+  .. versionadded:: 3.6
+interface: dbcommand
+operation: profile
+arg_name: field
+...

source/includes/apiargs-method-db.setProfilingLevel-param.yaml

@@ -1,6 +1,10 @@
 arg_name: param
-description: |-
-  Specifies a profiling level, which is either ``0`` for no profiling, ``1`` for only slow operations, or ``2`` for all operations.
+description: |
+  Configures the profiler level.
+  The following profiler levels are available:
+  
+  .. include:: /includes/database-profiler-levels.rst
+
 interface: method
 name: level
 operation: db.setProfilingLevel
@@ -9,12 +13,41 @@ position: 1
 type: integer
 ---
 arg_name: param
-description: |-
-  Sets the threshold in milliseconds for the profile to consider a query or operation to be slow.
+description: |
+  Accepts an integer or an options document. If an integer value is
+  passed as the ``options`` argument instead of a document, the value is
+  assigned to ``slowms``.
+  The following options are available:
+
+  .. list-table::
+     :stub-columns: 1
+     :widths: 15 85
+
+     * - slowms
+       - | Default: 100
+         | Type: integer
+
+         .. include:: /includes/dbcommand-slowms-definition.rst
+
+         .. note::
+            This argument affects the same setting as the configuration
+            file option :setting:`~operationProfiling.slowOpThresholdMs`.
+
+     * - sampleRate
+       - | Default: 1.0
+         | Type: double
+         
+         The fraction of *slow* operations that should be profiled.
+         ``sampleRate`` accepts values between 0 and 1, inclusive.
+
+         .. note::
+            This argument affects the same setting as the configuration option
+            :setting:`~operationProfiling.slowOpSampleRate`.
+
 interface: method
-name: slowms
+name: options
 operation: db.setProfilingLevel
 optional: true
 position: 2
-type: integer
+type: document or integer
 ...

source/includes/database-profiler-levels.rst

@@ -0,0 +1,17 @@
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+   
+   * - Level
+     - Description
+
+   * - ``0``
+     - The profiler is off and does not collect any data.
+       This is the default profiler level.
+
+   * - ``1``
+     - The profiler collects data for operations that take longer
+       than the value of ``slowms``.
+
+   * - ``2``
+     - The profiler collects data for all operations.

source/includes/dbcommand-slowms-definition.rst

@@ -0,0 +1,4 @@
+The *slow* operation time threshold, in milliseconds. Operations
+that run for longer than this threshold are considered *slow*.
+
+.. include:: /includes/fact-log-slow-queries.rst

source/includes/fact-log-slow-queries.rst

@@ -0,0 +1,7 @@
+The system log and profiler are configured separately but share the same
+settings for ``slowms`` and ``sampleRate``.
+When :setting:`~param.logLevel` is set to ``0``, :program:`mongod`
+records *slow* queries to the system log at a rate determined by
+:setting:`~operationProfiling.slowOpSampleRate`. At higher
+:setting:`~param.logLevel` settings, all queries appear in the system
+log regardless of their latency.

source/includes/options-conf.yaml

@@ -1010,6 +1010,37 @@ description: |
   method.
 ---
 program: conf
+name: operationProfiling.mode
+type: string
+default: "``off``"
+directive: setting
+description: |
+  Specifies which operations should be :doc:`profiled
+  </tutorial/manage-the-database-profiler>`.
+  The following profiler levels are available:
+
+  .. list-table::
+   :header-rows: 1
+   :widths: 25 75
+   
+   * - Level
+     - Description
+
+   * - ``off``
+     - The profiler is off and does not collect any data.
+       This is the default profiler level.
+
+   * - ``slowOp``
+     - The profiler collects data for operations that take longer
+       than the value of ``slowms``.
+
+   * - ``all``
+     - The profiler collects data for all operations.
+  
+  .. include:: /includes/warning-profiler-performance.rst
+
+---
+program: conf
 name: operationProfiling.slowOpThresholdMs
 type: integer
 default: 100
@@ -1024,18 +1055,32 @@ post: |
   The {{role}} setting is available only for :program:`mongod`.
 ---
 program: conf
-name: operationProfiling.mode
+name: operationProfiling.slowOpSampleRate
+type: double
+default: 1.0
+directive: setting
+replacement:
+  program: ":program:`mongod`"
+inherit:
+  name: slowOpSampleRate
+  program: mongod
+  file: options-mongod.yaml
+---
+program: conf
+name: storage.dbPath
 type: string
 directive: setting
 replacement:
   program: ":program:`mongod`"
-  intro: "The"
+  storage_engine: :setting:`~storage.engine`
 inherit:
-  name: profilingmode
+  name: dbpath
   program: mongod
   file: options-mongod.yaml
 post: |
   The {{role}} setting is available only for :program:`mongod`.
+
+  .. include:: /includes/extracts/linux-config-expectations-storage-dbpath.rst
 ---
 program: conf
 name: storage.dbPath