Conn pool stats

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

@@ -0,0 +1,4 @@
+.. note::
+
+   :dbcommand:`connPoolStats` only return meaningful results for
+   :program:`mongos` program.

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 all connection pool status.
 
 .. 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,137 @@
+====================================
+Connection Pool Statistics Reference
+====================================
+
+.. default-domain:: mongodb
+
+Synopsis
+--------
+
+:program:`mongos` instances maintain a pool of connections for
+interacting with the constituent members of the :term:`shard clusters
+<shard cluster>`. The :dbcommand:`connPoolStats` returns statistics
+regarding these connection pools.
+
+.. include:: /includes/note-conn-pool-stats
+
+Output
+------
+
+.. stats:: hosts
+
+   :stats:`hosts` contains a document for every member in the
+   connection pool, every :term:`shard cluster`, :term:`replica
+   set`, and :term:`config database`.
+
+.. stats:: hosts.[host].available
+
+   The cummulative number of connections in the connection pool
+   available for a host to connect to a :program:`mongos`.
+
+.. stats:: hosts.[host].created
+
+   The number of connections in the connection pool that has ever
+   been created for this host by the :program:`mongos`.
+
+.. stats:: replicaSets
+
+   This field holds a document that contains detailed replica set
+   information.
+
+  .. stats:: replicaSets.shard
+
+     This document gives details on each shard within the replica set.
+
+    .. stats:: replicaSets.[shard].host
+
+       This :term:`document` gives details on each host within the shard in the replica set.
+
+       These values derive from the :doc:`replica set status
+       </reference/replica-status>` values.
+
+      .. stats:: replicaSets.[shard].[host].addr
+
+         This field indicates the address for a particular host in
+         the :term:`shard cluster` in the format of
+         "``[hostname]:[port]``".
+
+      .. stats:: replicaSets.[shard].[host].ok
+
+         This field indicates whether the host is accessible for
+         queries.
+
+         .. TODO verify with someone more knowledgable.
+
+      .. stats:: replicaSets.[shard].[host].ismaster
+
+         A field indicates whether this host is the :term:`master`
+         member of the replica set.
+
+      .. stats:: replicaSets.[shard].[host].hidden
+
+         This field indicates whether this host is a :term:`hidden
+         member` of the replica set.
+
+      .. stats:: replicaSets.[shard].[host].secondary
+
+         This field indicates whether this host is a
+         :term:`secondary` member of the replica set.
+
+      .. stats:: replicaSets.[shard].[host].pingTimeMillis
+
+         This field indicates the ping time in miliseconds from the
+         :program:`mongos`
+
+   .. stats:: replicaSets.[shard].master
+
+      This field indicates the number of the host that is the
+      :term:`master` from the ``hosts`` list.
+
+   .. stats:: replicaSets.[shard].nextSlave
+
+      This field indicates the number of the host that is the next
+      :term:`secondary` to read from instead of :term:`master` from
+      the ``hosts`` list.
+
+      .. TODO verify with someone more knowledgable.
+
+.. stats:: createdByType
+
+   The number of each type of connection that :program:`mongos` has
+   created in all connection pools.
+
+   .. stats:: createdByType.master
+
+      The total number of connections created to connect to a
+      :term:`shard cluster` that is a :term:`master` member.
+
+   .. stats:: createdByType.set
+
+      The total number of connections created to connect to a :term:`replica
+      set` member.
+
+   .. stats:: createdByType.sync
+
+      The total number of connections created to connect to the
+      :term:`config database`.
+
+.. stats:: totalAvailable
+
+   A running total of connections available in all connection pools.
+
+.. stats:: totalCreated
+
+   The total number of connections ever created in all connection pools.
+
+.. stats:: numDBClientConnection
+
+   The number of normal client connections in the connection pool.
+
+   .. TODO verify - unlike scoped, does this stay connected when
+   .. there is an exception?
+
+.. stats:: numAScopedConnection
+
+   The number of exception safe connections that exists in the
+   connection pool. The :program:`mongos will release all connections
+   when there is an exception thrown in MongoDB.