DOCS-14777 profile filter options (#868)

* DOCS-14777 profiler filter options

* Staging fixes

* Review feedback

* Review feedback

* Review feedback

* Staging updates

* Staging updates

* Review feedback

* Staging fixes

* Staging fixes

* fake commit

* DOCS-14777 profile filter options

* fake commit

* DOCS-14777 profile filter options

* Staging chagnes

* Build error

Author: Dave

source/includes/database-profiler-levels.rst

@@ -11,7 +11,16 @@
 
    * - ``1``
      - The profiler collects data for operations that take longer
-       than the value of ``slowms``.
+       than the value of ``slowms`` or that match a :ref:`filter
+       <set-profiling-level-options-filter>`. 
+
+       When a filter is set:
+
+       + The ``slowms`` and ``sampleRate`` options are not used for
+         profiling.
+       + The profiler only captures operations that match the
+         :ref:`filter <set-profiling-level-options-filter>`.
 
    * - ``2``
-     - The profiler collects data for all operations.
+     - The profiler collects data for all operations.
+

source/reference/command/profile.txt

@@ -18,36 +18,39 @@ Definition
    .. versionchanged:: 5.0
 
    For a :binary:`~bin.mongod` instance, the command enables, disables,
-   or configures the :doc:`/tutorial/manage-the-database-profiler`. The
+   or configures the :ref:`database profiler <database-profiler>`. The
    profiler captures and records data on the performance of write
    operations, cursors, and database commands on a running
    :binary:`~bin.mongod` instance. If the profiler is disabled, the
    command configures how slow operations are logged to the diagnostic
    log.
 
    On :binary:`~bin.mongod`, if the :ref:`database profiler level
-   <set-profiling-level-level>` is ``1`` or ``2`` (i.e. the
-   :doc:`database profiler </tutorial/manage-the-database-profiler/>` is
-   enabled), the :ref:`slowms <set-profiling-level-options-slowms>`,
-   :ref:`sampleRate <set-profiling-level-options-sampleRate>`, and
-   :ref:`filter <set-profiling-level-options-filter>` affect the
-   behavior of both the profiler and the :option:`diagnostic log <mongod
-   --logpath>`.
+   <set-profiling-level-level>` is ``2``, full logging is enabled on
+   the profiler and the :option:`diagnostic log <mongod --logpath>`.
+
+   At :ref:`database profiler level <set-profiling-level-level>` ``1``,
+   the following settings modify both the profiler and the
+   :option:`diagnostic log <mongod --logpath>`:
+
+   - :ref:`slowms <set-profiling-level-options-slowms>`
+   - :ref:`sampleRate <set-profiling-level-options-sampleRate>`
+   - :ref:`filter <set-profiling-level-options-filter>`
 
    If the :ref:`database profiler level <set-profiling-level-level>` is
-   ``0`` (i.e. :doc:`database profiler
-   </tutorial/manage-the-database-profiler/>` is disabled), the
-   :ref:`slowms <set-profiling-level-options-slowms>`,
-   :ref:`sampleRate <set-profiling-level-options-sampleRate>`, and
-   :ref:`filter <set-profiling-level-options-filter>` affect
-   only the diagnostic log.
+   ``0``, the :ref:`database profiler <database-profiler>` is disabled.
+   At level ``0`` the following settings only modify the diagnostic log:
 
+   - :ref:`slowms <set-profiling-level-options-slowms>`
+   - :ref:`sampleRate <set-profiling-level-options-sampleRate>`
+   - :ref:`filter <set-profiling-level-options-filter>`
+
    Starting in MongoDB 4.0, for a :binary:`~bin.mongos` instance, the
    command only configures how operations get written to the diagnostic
-   log. You cannot enable the
-   :doc:`/tutorial/manage-the-database-profiler` on a
-   :binary:`~bin.mongos` instance because ``mongos`` does not have any
-   collections that the profiler can write to.
+   log. You cannot enable the :ref:`database profiler
+   <database-profiler>` on a :binary:`~bin.mongos` instance because
+   ``mongos`` does not have any collections that the profiler can write
+   to.
 
    .. include:: /includes/log-changes-to-database-profiler.rst
 
@@ -75,7 +78,6 @@ Definition
 
    .. _slowms-threshold-option:
 
-
    .. list-table::
       :header-rows: 1
       :widths: 20 20 80
@@ -111,7 +113,7 @@ Definition
 
           .. note::
              This argument affects the same setting as the configuration option
-             :setting:`~operationProfiling.slowOpThresholdMs`.
+             :setting:`operationProfiling.slowOpThresholdMs`.
 
 
 
@@ -127,44 +129,43 @@ Definition
           .. note::
 
              This argument affects the same setting as the configuration option
-             :setting:`~operationProfiling.slowOpSampleRate` and does not
+             :setting:`operationProfiling.slowOpSampleRate` and does not
              affect the :ref:`slow oplog entry log messages on secondaries
              (available starting in MongoDB 4.2) <slow-oplog>`.
 
       * - ``filter``
-        
         - object
+        - .. _profile-filter-def:
 
-        - Optional.
-
-          A filter expression that controls which operations are
-          profiled and logged.
+          Optional.
+          A query that determines which operations are profiled or
+          logged.
 
-          The ``filter`` expression takes the following form:
+          The filter query takes the following form:
 
           .. code-block:: javascript
 
              { <field1>: <expression1>, ... }
-            
-          The ``<field>`` can be
-          :ref:`any field in the profiler output <profiler>`. The
-          ``<expression>`` is a
-          :ref:`query condition expression <query-selectors>`.
+
+          The query can be any legal :method:`~db.collection.find()`
+          operation where the query ``<field>`` matches a field in the
+          :ref:`profiler output <profiler>`.
 
           .. note::
-          
-             This argument affects the same setting as the configuration
-             option :setting:`~operationProfiling.filter`. When
-             ``filter`` is set, the ``slowms`` and ``sampleRate``
+
+             This argument affects the same setting as the
+             configuration option :setting:`operationProfiling.filter`.
+             
+             When ``filter`` is set, the ``slowms`` and ``sampleRate``
              options are not used for profiling and slow-query log
              lines.
 
           .. versionadded:: 4.4.2
 
 The :method:`db.getProfilingStatus()` and
-:method:`db.setProfilingLevel()` :doc:`shell methods
-</reference/method>` provide wrappers around the :dbcommand:`profile`
-command.
+:method:`db.setProfilingLevel()` :ref:`shell methods
+<js-administrative-methods>` provide wrappers around the
+:dbcommand:`profile` command.
 
 .. |binary| replace:: :binary:`~bin.mongod` or :binary:`~bin.mongos`
 
@@ -185,3 +186,31 @@ command against the ``admin`` database.
 .. seealso::
 
    :ref:`Database Profiling <database-profiling>`
+
+Example
+-------
+
+Enable profiling and filter the logged data:
+
+.. code-block:: javascript
+
+   db.runCommand( 
+      {
+        profile: 1,
+        filter:
+           {
+              $or:
+              [
+                 { millis: { $gte: 100 } },
+                 { user: "testuser@admin" }
+              ]
+           }
+      }
+   )
+
+The :ref:`filter <profile-filter-def>` only selects operations that
+are:
+
+- at least ``100`` milliseconds long, or
+- submitted by the ``testuser``.
+