DOCS-15983 Top Command Paramenters (#2754) (#2843)

* WIP

* DOCS-15983 Add Parameter Details for Top Command

* event type descriptions

* move to table

* fix text styling and wording

* build errors

* typo

* change wording for event fields

* JD edits

* JD edits pt 2

Author: ajhuh-mdb

source/reference/command/top.txt

@@ -12,59 +12,111 @@ top
 
 .. dbcommand:: top
 
-   :dbcommand:`top` is an administrative command that
-   returns usage statistics for each collection. :dbcommand:`top`
-   provides amount of time, in microseconds, used and a count of
-   operations for the following event types:
-
-   - total
-   - readLock
-   - writeLock
-   - queries
-   - getmore
-   - insert
-   - update
-   - remove
-   - commands
+   :dbcommand:`top` is an administrative command that returns usage statistics 
+   for each collection. You can use :dbcommand:`top` metrics to compare the 
+   relative performance of your collections against each other.
 
    .. important::
 
       The :dbcommand:`top` command must be run against a
       :doc:`mongod </reference/program/mongod>` instance. Running
       :dbcommand:`top` against a :doc:`mongos </reference/program/mongos>`
-      instance will return an error.
+      instance returns an error. 
 
-   Issue the :dbcommand:`top` command against the :term:`admin
-   database` in the form:
+Definition
+----------
+   
+For every collection, :dbcommand:`top` returns the amount of ``time``, in 
+microseconds, that each :ref:`event <event-types>` takes to execute and a 
+``count`` of how many times each event has executed. The ``time`` and 
+``count`` metrics reset only after you restart your :binary:`~bin.mongod` 
+instance.
 
-   .. code-block:: javascript
+Syntax
+------
 
-      { top: 1 }
-
-
-Example
--------
-
-At :binary:`~bin.mongosh` prompt, use :dbcommand:`top` with the
-following invocation:
+Issue the :dbcommand:`top` command against the :term:`admin database`:
 
 .. code-block:: javascript
 
-   db.adminCommand("top")
-
-Alternately you can use :dbcommand:`top` as follows:
+   db.runCommand(
+      { 
+        top: 1 
+      }
+   )
+
+.. _event-types:
+
+Event Fields 
+------------
+
+The :dbcommand:`top` command returns usage statistics for the following event 
+fields: 
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Field
+     - Description
+
+   * - ``total`` 
+     - The combination of all ``readLock`` and ``writeLock`` operations. 
+     
+   * - ``readLock``
+     - Usage statistics for operations that use read locks. These operations 
+       include but are not limited to queries and aggregations. 
+
+   * - ``writeLock``
+     - Usage statistics for operations that use write locks. These operations 
+       include but are not limited to inserting, updating, and removing 
+       documents.
+
+   * - ``queries``
+     - Usage statistics for query operations such as :dbcommand:`find`. The 
+       ``queries.time`` and ``queries.count`` fields also update 
+       ``readLock.time`` and increment ``readLock.count``.
+
+   * - ``getmore`` 
+     - Usage statistics for :dbcommand:`getMore` operations. The 
+       ``getmore.time`` and ``getmore.count`` fields also update 
+       ``readLock.time`` and increment ``readLock.count``.
+
+   * - ``insert``
+     - Usage statistics for :dbcommand:`insert` operations. The 
+       ``insert.time`` and ``insert.count`` fields also update 
+       ``readLock.time`` and increment ``readLock.count``.
+
+   * - ``update`` 
+     - Usage statistics for :dbcommand:`update` operations. The 
+       ``update.time`` and ``update.count`` fields also update 
+       ``readLock.time`` and increment ``readLock.count``.
+
+   * - ``remove`` 
+     - Usage statistics for :dbcommand:`delete` operations. The 
+       ``remove.time`` and ``remove.count`` fields also update 
+       ``readLock.time`` and increment ``readLock.count``.
+
+   * - ``commands`` 
+     - Usage statistics for operations such as aggregations, index creation, 
+       and index removal. Depending on the type of command, the 
+       ``commands.time`` and ``commands.count`` fields update the ``writeLock`` 
+       fields or the ``readLock`` fields. 
+       
+       For example, aggregation operations increment ``readLock.time`` and 
+       ``readLock.count``. Index creation increments ``writeLock.time`` 
+       and ``writeLock.count``.
 
-.. code-block:: javascript
-
-   db.adminCommand( { top: 1 } )
+Example
+-------
 
-The output of the top command would resemble the following
-output:
+The output of the :dbcommand:`top` command resembles the following output:
 
 .. code-block:: javascript
 
    {
      "totals" : {
+        note: "all times in microseconds",
         "records.users" : {
                      "total" : {
                              "time" : 305277,
@@ -104,3 +156,8 @@ output:
                      }
              }
    }
+
+Learn More 
+----------
+
+- :ref:`faq-concurrency-locking`