Conn pool stats

source/includes/note-conn-pool-stats.rst

@@ -0,0 +1,5 @@
+.. note::
+
+   :dbcommand:`connPoolStats` only returns meaningful results for
+   :program:`mongos` instances and for :program:`mongod` instances
+   in shard clusters.

source/reference.txt

@@ -35,6 +35,7 @@ Statuses and Errors
    reference/database-statistics
    reference/collection-statistics
    reference/collection-validation
+   reference/connection-pool-stats
    reference/replica-status
    reference/replica-configuration
    reference/replication-info

source/reference/commands.txt

@@ -1725,6 +1725,8 @@ Diagnostics
 
 .. dbcommand:: connPoolStats
 
+   .. include:: /includes/note-conn-pool-stats
+
    The command :dbcommand:`connPoolStats` returns information
    regarding the number of open connections to the current database
    instance, including client connections and server-to-server
@@ -1735,8 +1737,9 @@ Diagnostics
 
       { connPoolStats: 1 }
 
-   The value of the argument (e.g. ``1`` above) does not affect the
-   output of the command.
+   The value of the argument (i.e. ``1`` ) does not affect the
+   output of the command. See :doc:`/reference/connection-pool-stats`
+   for full documentation of the :dbcommand:`connPoolStats` output.
 
 .. dbcommand:: getCmdLineOpts
 
@@ -1771,13 +1774,13 @@ Diagnostics
    - ``full: true`` provides a more thorough scan of the data.
 
    - ``scandata: false`` skips the scan of the base collection
-     without skipping the scan of the index.
+      without skipping the scan of the index.
 
    The :program:`mongo` shell also provides a wrapper:
 
    .. code-block:: javascript
 
-        db.collection.validate();
+      db.collection.validate();
 
    Use one of the following forms to perform the full collection
    validation:
@@ -1790,6 +1793,8 @@ Diagnostics
    .. warning:: This command is resource intensive and may have an
       impact on the performance of your MongoDB instance.
 
+   .. TODO link to the document with these statistics
+
 .. dbcommand:: top
 
    The :dbcommand:`top` command returns raw usage of each database,
@@ -1824,13 +1829,17 @@ Diagnostics
     The information provided includes the following:
 
    - The version of MongoDB currently running.
+
    - The information about the system that built the
      ":program:`mongod`" binary, including a timestamp for the build.
-   - The architecture of the binary (i.e. 64 or 32 bits)
+
+   - The architecture of the binary (i.e. 64 or 32 bits.)
+
    - The maximum allowable :term:`BSON` object size in bytes (in the field
-     ``maxBsonObjectSize``.)
+       ``maxBsonObjectSize``.)
 
-   You must issue the :dbcommand:`buildInfo` command against the ``admin`` database.
+   You must issue the :dbcommand:`buildInfo` command against the
+   ``admin`` database.
 
 .. dbcommand:: getLastError
 
@@ -1903,10 +1912,10 @@ Diagnostics
      set`, :dbcommand:`getLog` will return recent notices related to
      replica set activity.
 
-   - ``startupWarnings`` - will return logs that *may* contain
-     errors or warnings from MongoDB's log from when the current
-     process started. If :program:`mongod` started without warnings,
-     this filter may return an empty array.
+   - ``startupWarnings`` - will return logs that *may* contain errors
+     or warnings from MongoDB's log from when the current process
+     started. If :program:`mongod` started without warnings, this
+     filter may return an empty array.
 
    You may also specify an asterisk (e.g. ``*``) as the ``<log>``
    value to return a list of available log filters. The following
@@ -1960,7 +1969,7 @@ Diagnostics
    The :dbcommand:`isMaster` command provides a basic overview of the current
    replication configuration. MongoDB :term:`drivers <driver>` and
    :term:`clients <client>` use this command to determine what kind of
-   node they're connected to and to discover additional members of a
+   member they're connected to and to discover additional members of a
    :term:`replica set`. The :func:`db.isMaster()` method provides a
    wrapper around this database command.
 

source/reference/connection-pool-stats.txt

@@ -0,0 +1,176 @@
+====================================
+Connection Pool Statistics Reference
+====================================
+
+.. default-domain:: mongodb
+
+Synopsis
+--------
+
+:program:`mongos` instances maintain a pool of connections for
+interacting with constituent members of the :term:`shard clusters
+<shard cluster>`. Additionally, :program:`mongod` instances maintain
+connection with other shards in the cluster for migrations. The
+:dbcommand:`connPoolStats` command returns statistics regarding these
+connections between the :program:`mongos` and :program:`mongod`
+instances or between the :program:`mongod` instances in a shard
+cluster.
+
+.. include:: /includes/note-conn-pool-stats
+..
+Output
+------
+
+.. stats:: hosts
+
+   The sub-documents of the :stats:`hosts` :term:`document` report connections
+   between the :program:`mongos` or :program:`mongod` instance and each component
+   :program:`mongod` of the :term:`shard cluster`.
+
+   .. stats:: hosts.[host].available
+
+      :stats:`hosts.[host].available` reports the total number of
+      connections that the :program:`mongos` or :program:`mongod`
+      could use to connect to this :program:`mongod`.
+
+   .. stats:: hosts.[host].created
+
+      :stats:`hosts.[host].created` reports the number of connections
+      that this :program:`mongos` or :program:`mongod` has ever created for this host.
+
+.. stats:: replicaSets
+
+   :stats:`replicaSets` is a :term:`document` that contains
+   :term:`replica set` information for the :term:`shard cluster`.
+
+   .. stats:: replicaSets.shard
+
+      The :stats:`replicaSets.shard` :term:`document` reports
+      on each :term:`shard` within the :term:`shard cluster`
+
+   .. stats:: replicaSets.[shard].host
+
+      The :stats:`replicaSets.[shard].host` field holds an array of
+      :term:`document` that reports on each host within the
+      :term:`shard` in the :term:`replica set`.
+
+      These values derive from the :doc:`replica set status
+      </reference/replica-status>` values.
+
+      .. stats:: replicaSets.[shard].host[n].addr
+
+         :stats:`replicaSets.[shard].host[n].addr` reports the address
+         for the host in the :term:`shard cluster` in the format of
+         "``[hostname]:[port]``".
+
+      .. stats:: replicaSets.[shard].host[n].ok
+
+         :stats:`replicaSets.[shard].host[n].ok` reports ``false``
+         when:
+
+         - the :program:`mongos` or :program:`mongod` cannot connect
+           to instance.
+
+         - the :program:`mongos` or :program:`mongod` received a
+           connection exception or error.
+
+         This field is for internal use.
+
+      .. stats:: replicaSets.[shard].host[n].ismaster
+
+         :stats:`replicaSets.[shard].host[n].ismaster` reports ``true``
+         if this :stats:`replicaSets.[shard].host` is the
+         :term:`primary` member of the :term:`replica set`.
+
+      .. stats:: replicaSets.[shard].host[n].hidden
+
+         :stats:`replicaSets.[shard].host[n].hidden` reports ``true``
+         if this :stats:`replicaSets.[shard].host` is a :term:`hidden
+         member` of the :term:`replica set`.
+
+      .. stats:: replicaSets.[shard].host[n].secondary
+
+         :stats:`replicaSets.[shard].host[n].secondary` reports
+         ``true`` if this :stats:`replicaSets.[shard].host` is a
+         :term:`secondary` member of the :term:`replica set`.
+
+      .. stats:: replicaSets.[shard].host[n].pingTimeMillis
+
+         :stats:`replicaSets.[shard].host[n].pingTimeMillis` reports
+         the ping time in milliseconds from the :program:`mongos` or
+         :program:`mongod` to this :stats:`replicaSets.[shard].host`.
+
+      .. stats:: replicaSets.[shard].host[n].tags
+
+         .. versionadded:: 2.2
+
+         :stats:`replicaSets.[shard].host[n].tags` reports the
+         :data:`members[n].tags`, if this member of the set has tags
+         configured.
+
+   .. stats:: replicaSets.[shard].master
+
+      :stats:`replicaSets.[shard].master` reports the ordinal identifier
+      of the host in the :stats:`replicaSets.[shard].host` array that is
+      the :term:`primary` of the :term:`replica set`.
+
+   .. stats:: replicaSets.[shard].nextSlave
+
+      .. deprecated:: 2.2
+
+      :stats:`replicaSets.[shard].nextSlave` reports the
+      :term:`secondary` member that the :program:`mongos` will use to
+      service the next request for this :term:`replica set`.
+
+.. stats:: createdByType
+
+   :stats:`createdByType` :term:`document` reports the number of each
+   type of connection that :program:`mongos` or :program:`mongod` has created in all
+   connection pools.
+
+   :program:`mongos` connect to :program:`mongod` instances using one
+   of three types of connections. The following sub-document reports
+   the total number of connections by type.
+
+   .. stats:: createdByType.master
+
+      :stats:`createdByType.master` reports the total number of
+      connections to the :term:`primary` member in each :term:`shard
+      cluster`.
+
+   .. stats:: createdByType.set
+
+      :stats:`createdByType.set` reports the total number of
+      connections to a :term:`replica set` member.
+
+   .. stats:: createdByType.sync
+
+      :stats:`createdByType.sync` reports the total number of
+      :term:`config database` connections.
+
+.. stats:: totalAvailable
+
+   :stats:`totalAvailable` reports the running total of connections
+   from the :program:`mongos` or :program:`mongod` to all :program:`mongod` instances in
+   the :term:`shard cluster` available for use. This value does not
+   reflect those connections that
+
+.. stats:: totalCreated
+
+   :stats:`totalCreated` reports the total number of connections ever
+   created from the :program:`mongos` or :program:`mongod` to all :program:`mongod`
+   instances in the :term:`shard cluster`.
+
+.. stats:: numDBClientConnection
+
+   :stats:`numDBClientConnection` reports the total number of
+   connections from the :program:`mongos` or :program:`mongod` to all of the :program:`mongod`
+   instances in the :term:`shard cluster`.
+
+.. stats:: numAScopedConnection
+
+   :stats:`numAScopedConnection` reports the number of exception safe
+   connections created from :program:`mongos` or :program:`mongod` to all :program:`mongod`
+   in the :term:`shard cluster`. The :program:`mongos` or :program:`mongod` releases these
+   connections after receiving a socket exception from the
+   :program:`mongod`.