DOCS-14139 Add server status metrics to cursor

Author: jason-price-mongodb

source/includes/extracts-server-status-projection-base.yaml

@@ -38,6 +38,24 @@ content: |
       :serverstatus:`readConcernCounters` to track use of read concern
       levels specified by query operations
 
+    - Added new metric to track number of incoming connections:
+
+      - :serverstatus:`connections.threaded`
+
+    - Added new metric to track resharding operations:
+
+      - :serverstatus:`shardingStatistics.resharding`
+
+    - Added new metric to track service executors:
+
+      - :serverstatus:`network.serviceExecutors`
+
+    - Added new metrics to track cursors:
+
+      - :serverstatus:`metrics.cursor.moreThanOneBatch`
+
+      - :serverstatus:`metrics.cursor.totalOpened`
+
   - Starting in MongoDB 4.4, {{operationName}}:
 
     - Added new metrics to track write concern failures caused

source/reference/command/serverStatus.txt

@@ -674,10 +674,9 @@ extra_info
    with limited memory environments and larger data sets. Limited and
    sporadic page faults do not necessarily indicate an issue.
 
-   Windows draws a distinction between "hard" page faults involving
-   disk I/O, and "soft" page faults that only require moving pages in
-   memory. MongoDB counts both hard and soft page faults in this
-   statistic.
+   Windows differentiates "hard" page faults involving disk I/O from
+   "soft" page faults that only require moving pages in memory. MongoDB
+   counts both hard and soft page faults in this statistic.
 
 .. _server-status-flowControl:
 
@@ -713,7 +712,7 @@ flowControl
 .. serverstatus:: flowControl.enabled
 
    A boolean that indicates whether :ref:`flow-control` is
-   enabled(``true``) or disabled (``false``).
+   enabled (``true``) or disabled (``false``).
 
    See also :parameter:`enableFlowControl`.
 
@@ -893,8 +892,8 @@ globalLock
 .. serverstatus:: globalLock.totalTime
 
    The time, in microseconds, since the database last started and
-   created the :serverstatus:`globalLock`. This is roughly equivalent
-   to total server uptime.
+   created the :serverstatus:`globalLock`. This is approximately
+   equivalent to the total server uptime.
 
 .. serverstatus:: globalLock.currentQueue
 
@@ -915,13 +914,13 @@ globalLock
 .. serverstatus:: globalLock.currentQueue.readers
 
    The number of operations that are currently queued and waiting for
-   the read lock. A consistently small read-queue, particularly of
+   the read lock. A consistently small read queue, particularly of
    shorter operations, should cause no concern.
 
 .. serverstatus:: globalLock.currentQueue.writers
 
    The number of operations that are currently queued and waiting for
-   the write lock. A consistently small write-queue, particularly of
+   the write lock. A consistently small write queue, particularly of
    shorter operations, is no cause for concern.
 
 .. serverstatus:: globalLock.activeClients
@@ -1032,7 +1031,7 @@ latchAnalysis
 .. serverstatus:: latchAnalysis
 
    A document that reports on metrics related to internal locking
-   primitives (a.k.a. latches).
+   primitives (also known as latches).
 
    To return :serverstatus:`latchAnalysis` information, you must
    explicitly specify the inclusion:
@@ -1348,24 +1347,24 @@ network
 .. serverstatus:: network
 
    A document that reports data on MongoDB's network use. These
-   statistics measure *ingress connections* only, i.e. traffic
-   seen by the :binary:`~bin.mongod` / :binary:`~bin.mongos` over
-   network connections initiated by clients or other
-   :binary:`~bin.mongod` / :binary:`~bin.mongos` instances. Traffic from
-   network connections initiated by this :binary:`~bin.mongod` /
-   :binary:`~bin.mongos` instance (i.e. *egress connections*) is *not*
-   measured in these statistics.
+   statistics measure *ingress connections* only, specifically the
+   traffic seen by the :binary:`~bin.mongod` or :binary:`~bin.mongos`
+   over network connections initiated by clients or other
+   :binary:`~bin.mongod` or :binary:`~bin.mongos` instances. Traffic
+   from network connections initiated by this :binary:`~bin.mongod` or
+   :binary:`~bin.mongos` instance (specifically, *egress connections*)
+   is *not* measured in these statistics.
 
 .. serverstatus:: network.bytesIn
 
    The total number of bytes that the server has *received* over network
-   connections initiated by clients or other :binary:`~bin.mongod` /
+   connections initiated by clients or other :binary:`~bin.mongod` or
    :binary:`~bin.mongos` instances.
 
 .. serverstatus:: network.bytesOut
 
    The total number of bytes that the server has *sent* over network
-   connections initiated by clients or other :binary:`~bin.mongod` /
+   connections initiated by clients or other :binary:`~bin.mongod` or
    :binary:`~bin.mongos` instances.
 
 .. serverstatus:: network.numSlowDNSOperations
@@ -1439,8 +1438,8 @@ network
    .. versionadded:: 4.4
 
    The total number of accepted incoming TCP Fast Open (TFO) connections
-   to the :binary:`~bin.mongod` / :binary:`~bin.mongos` since the 
-   ``mongod / mongos`` last started.
+   to the :binary:`~bin.mongod` or :binary:`~bin.mongos` since the 
+   ``mongod`` or ``mongos`` last started.
 
 .. serverstatus:: network.serviceExecutors
 
@@ -1611,13 +1610,11 @@ opReadConcernCounters
         - Number of query operations that specified read
           concern level :readconcern:`"local"`.
 
-
       * - ``"majority"``
 
         - Number of query operations that specified read
           concern level :readconcern:`"majority"`.
 
-
       * - ``"snapshot"``
 
         - Number of query operations that specified read
@@ -2398,6 +2395,7 @@ repl
 .. serverstatus:: repl.replicationProgress[n].memberID
 
    The integer identifier for this member of the replica set.
+
 .. _server-status-security:
 
 security
@@ -2450,19 +2448,19 @@ security
    A document that reports on:
 
    - The number of times a given authentication mechanism has been used
-     to authenticate against the
-     :binary:`~bin.mongod` / :binary:`~bin.mongos` instance. (New in MongoDB 4.4)
+     to authenticate against the :binary:`~bin.mongod` or
+     :binary:`~bin.mongos` instance. (New in MongoDB 4.4)
 
    - The :binary:`~bin.mongod`/:binary:`~bin.mongos` instance's TLS/SSL
-     certificate. (Only appears for :binary:`~bin.mongod` /
+     certificate. (Only appears for :binary:`~bin.mongod` or
      :binary:`~bin.mongos` instance with support for TLS)
 
    .. serverstatus:: security.authentication.mechanisms
 
       A document that reports on the number of times a given
       authentication mechanism has been used to authenticate against the
-      :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. The values
-      in the document distinguish standard authentication and
+      :binary:`~bin.mongod` or :binary:`~bin.mongos` instance. The
+      values in the document distinguish standard authentication and
       speculative authentication. [#speculative-auth]_
 
       .. versionadded:: 4.4
@@ -2473,7 +2471,7 @@ security
          configuration of the :parameter:`authenticationMechanisms`
          parameter. The ``mechanisms`` document includes a field for
          each authentication mechanism supported by your
-         :binary:`~bin.mongod` / :binary:`~bin.mongos` instance.
+         :binary:`~bin.mongod` or :binary:`~bin.mongos` instance.
 
          The following example shows the shape of the ``mechanisms``
          document for a deployment that only supports :doc:`x.509
@@ -2484,7 +2482,7 @@ security
       A document that reports on the number of times
       :doc:`x.509 </core/security-x.509/>` has been used to
       authenticate against the
-      :binary:`~bin.mongod` / :binary:`~bin.mongos` instance.
+      :binary:`~bin.mongod` or :binary:`~bin.mongos` instance.
 
       Includes total number of ``x.509`` authentication attempts and the
       subset of those attempts which were speculative.
@@ -2755,7 +2753,7 @@ shardingStatistics
 
    To calculate the duration of the catch-up phase, subtract
    :serverstatus:`~shardingStatistics.totalCriticalSectionCommitTimeMillis` from
-   :serverstatus:`~shardingStatistics.totalCriticalSectionTimeMillis`
+   :serverstatus:`~shardingStatistics.totalCriticalSectionTimeMillis`:
 
    .. code-block:: none
 
@@ -3704,7 +3702,7 @@ transactions
 
    |mongos-only|
 
-   Breakdown of the commits by types.  For example:
+   Breakdown of the commits by types. For example:
 
    .. code-block:: javascript
       :copyable: false
@@ -3754,6 +3752,7 @@ transactions
         - Commits of transactions that did not contact any shards.
 
       * - ``singleShard``
+
         - Commits of transactions that affected a single shard.
 
       * - ``singleWriteShard``
@@ -4578,13 +4577,15 @@ metrics
             }
       },
       "cursor" : {
+            "moreThanOneBatch" : NumberLong(<num>),
             "timedOut" : NumberLong(<num>),
+            "totalOpened" : NumberLong(<num>),
             "open" : {
                "noTimeout" : NumberLong(<num>),
                "pinned" : NumberLong(<num>),
                "multiTarget" : NumberLong(<num>),
                "singleTarget" : NumberLong(<num>),
-               "total" : NumberLong(<num>),
+               "total" : NumberLong(<num>)
             }
       },
       "document" : {
@@ -4600,7 +4601,7 @@ metrics
             },
             "wtimeouts" : NumberLong(<num>),
             "default" : {
-                "unsatisfiable" : <num>
+                "unsatisfiable" : <num>,
                 "wtimeouts" : <num>
             }
       },
@@ -4648,7 +4649,7 @@ metrics
          "initialSync" : {
             "completed" : <NumberLong>,
             "failedAttempts" : <NumberLong>,
-            "failures" : <NumberLong>,
+            "failures" : <NumberLong>
          },
          "network" : {
             "bytes" : <NumberLong>,
@@ -4957,7 +4958,7 @@ metrics
    oplog application process on :term:`secondaries <secondary>`
    members of replica sets. See
    :ref:`replica-set-internals-multi-threaded-replication` for more
-   information on the oplog application processes
+   information on the oplog application processes.
 
 .. serverstatus:: metrics.repl.apply.batches.num
 
@@ -5211,7 +5212,7 @@ metrics
 .. serverstatus:: metrics.storage.freelist.search.bucketExhausted
 
    The number of times that :binary:`~bin.mongod` has examined the free
-   list without finding a suitably large record allocation.
+   list without finding a large record allocation.
 
 .. serverstatus:: metrics.storage.freelist.search.requests
 
@@ -5244,12 +5245,29 @@ metrics
 
    A document that contains data regarding cursor state and use.
 
+.. serverstatus:: metrics.cursor.moreThanOneBatch
+
+   The total number of cursors that have returned more than one batch
+   since the server process started. Additional batches are retrieved
+   using the :dbcommand:`getMore` command.
+
+   .. versionadded:: 5.0
+
 .. serverstatus:: metrics.cursor.timedOut
 
    The total number of cursors that have timed out since the server
    process started. If this number is large or growing at a regular
    rate, this may indicate an application error.
 
+.. serverstatus:: metrics.cursor.totalOpened
+
+   The total number of cursors that have been opened since the server
+   process started, including cursors currently open. Differs from
+   :serverstatus:`metrics.cursor.open.total`, which is the number of
+   currently open cursors only.
+
+   .. versionadded:: 5.0
+
 .. serverstatus:: metrics.cursor.open
 
    A document that contains data regarding open cursors.
@@ -5268,8 +5286,8 @@ metrics
 
    The number of cursors that MongoDB is maintaining for clients.
    Because MongoDB exhausts unused cursors, typically this value small
-   or zero. However, if there is a queue, stale tailable cursors, or a
-   large number of operations this value may rise.
+   or zero. However, if there is a queue, or stale tailable cursors, or
+   a large number of operations this value may increase.
 
 .. serverstatus:: metrics.cursor.open.singleTarget
 
@@ -5319,8 +5337,8 @@ watchdog
 
 .. serverstatus:: watchdog.monitorPeriod
 
-   The value set by :parameter:`watchdogPeriodSeconds`. This represents the
-   period in between status checks.
+   The value set by :parameter:`watchdogPeriodSeconds`. This is the
+   period between status checks.
 
 Output Changelog
 ----------------

source/release-notes/5.0.txt

@@ -249,6 +249,16 @@ output:
                on the service executors that run operations for client
                requests
 
+   Cursor Metrics
+      .. list-table::
+   
+         * - | :serverstatus:`metrics.cursor.moreThanOneBatch`, which
+               reports the total number of cursors that have returned
+               more than one batch (additional batches are retrieved
+               using the :dbcommand:`getMore` command)
+             | :serverstatus:`metrics.cursor.totalOpened`, which reports
+               the total number of cursors that have been opened
+
 Additional ``dbStats`` Free Space Statistics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~