diff --git a/source/includes/fact-latencystats-reference.rst b/source/includes/fact-latencystats-reference.rst new file mode 100644 index 00000000000..f516044fbd3 --- /dev/null +++ b/source/includes/fact-latencystats-reference.rst @@ -0,0 +1,84 @@ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Field Name + - Description + + * - ``reads`` + - Latency statistics for read requests. + + * - ``writes`` + - Latency statistics for write requests. + + * - ``commands`` + - Latency statistics for database commands. + +Each of these fields contains an embedded document bearing the +following fields: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Field Name + - Description + + * - ``latency`` + - A :bsontype:`long ` giving the total combined + latency in microseconds. + + * - ``ops`` + - A :bsontype:`long ` giving the total number of + operations performed on the collection since startup. + + * - ``histogram`` + - An array of embedded documents, each representing a latency range. + Each document covers twice the previous document's range. For + upper values between 2048 microseconds and roughly 1 second, + the histogram includes half-steps. + + This field only exists given the + ``latencyStats: { histograms: true }`` option. Empty ranges with + a zero ``count`` are omitted from the output. + + Each document bears the following fields: + + .. list-table:: + + * - Field Name + - Description + + * - ``micros`` + - A :bsontype:`long ` giving the inclusive + upper time bound of the current latency range in + microseconds. + + The document's range spans between the previous document's + ``micros`` value, exclusive, and this document's + ``micros`` value, inclusive. + + * - ``count`` + - A :bsontype:`long ` giving the number of + operations with latency less than or equal to ``micros``. + + For example, if ``collStats`` returns the following histogram: + + .. code-block:: javascript + + histogram: [ + { micros: NumberLong(1), count: NumberLong(10) }, + { micros: NumberLong(2), count: NumberLong(1) }, + { micros: NumberLong(4096), count: NumberLong(1)} + { micros: NumberLong(137438953472), count: NumberLong(1000) }, + { micros: NumberLong(274877906944), count: NumberLong(100) } + ] + + This indicates that there were: + + - 10 operations taking 1 microsecond or less, + - 1 operation in the range (1, 2] microseconds, + - 1 operation in the range (3072, 4096] microseconds, + - 1000 operations in the range (68719476736, 137438953472], and + - 100 operations in the range (137438953472, 274877906944]. diff --git a/source/includes/ref-toc-method-collection.yaml b/source/includes/ref-toc-method-collection.yaml index cefd8715c73..fa4ca3a67fc 100644 --- a/source/includes/ref-toc-method-collection.yaml +++ b/source/includes/ref-toc-method-collection.yaml @@ -110,6 +110,10 @@ name: ":method:`db.collection.isCapped()`" file: /reference/method/db.collection.isCapped description: "Reports if a collection is a :term:`capped collection`." --- +name: ":method:`db.collection.latencyStats()`" +file: /reference/method/db.collection.latencyStats +description: "Returns latency statistics for a collection." +--- name: ":method:`db.collection.mapReduce()`" file: /reference/method/db.collection.mapReduce description: "Performs map-reduce style data aggregation." diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index 09992edd679..014124a286e 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -108,7 +108,7 @@ Instance Information .. serverstatus:: pid The process id number. - + .. serverstatus:: uptime The number of seconds that the current MongoDB process has been @@ -671,6 +671,34 @@ network values to ensure that MongoDB's network utilization is consistent with expectations and application use. +opLatencies +~~~~~~~~~~~ + +.. code-block:: javascript + + "opLatencies" : { + "reads" : , + "writes" : , + "commands" : + }, + +.. serverstatus:: opLatencies + + A document containing operation latencies for the database as a whole. + See :ref:`latency-stats-document` for an description of this document. + +.. serverstatus:: opLatencies.reads + + Latency statistics for read requests. + +.. serverstatus:: opLatencies.writes + + Latency statistics for write operations. + +.. serverstatus:: opLatencies.commands + + Latency statistics for database commands. + .. _server-status-opcounters: opcounters @@ -1026,7 +1054,7 @@ security .. serverstatus:: security .. versionadded:: 3.0 - + A document that reports on security configuration and details. Only appears for :program:`mongod` instances compiled with support for TLS/SSL. @@ -1360,7 +1388,7 @@ wiredTiger cache` can provide an overview of the I/O activity. .. serverstatus:: wiredTiger.cache.pages written from cache - + Number of pages written from the cache. :serverstatus:`wiredTiger.cache.pages written from cache` with the :serverstatus:`wiredTiger.cache.pages read into @@ -1426,7 +1454,7 @@ wiredTiger Amount of time, in milliseconds, to create the most recent checkpoint. An increase in this value under stead write load may indicate saturation on the I/O subsystem. - + .. serverstatus:: wiredTiger.concurrentTransactions .. versionadded:: 3.0 @@ -1533,8 +1561,8 @@ mem .. serverstatus:: mem.note The field :serverstatus:`mem.note` appears if - :serverstatus:`mem.supported` is false. - + :serverstatus:`mem.supported` is false. + The :serverstatus:`mem.note` field contains the text: ``"not all mem info support on this platform"``. diff --git a/source/reference/method/db.collection.latencyStats.txt b/source/reference/method/db.collection.latencyStats.txt new file mode 100644 index 00000000000..60543eb5f29 --- /dev/null +++ b/source/reference/method/db.collection.latencyStats.txt @@ -0,0 +1,95 @@ +============================ +db.collection.latencyStats() +============================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. method:: db.collection.latencyStats(options) + + :method:`db.collection.latencyStats()` returns latency + statistics for a given collection. It is a wrapper around + :pipeline:`$collStats`. + + This method has the form: + + .. code-block:: javascript + + db.collection.latencyStats( { histograms: } ) + + The ``histograms`` argument is an optional boolean. If + ``histograms: true`` then :method:`~db.collection.latencyStats()` adds + latency histograms to the return document. + +.. seealso:: :pipeline:`$collStats` + +Output +------ + +:method:`~db.collection.latencyStats()` returns a document containing +a field ``latencyStats``, containing the following fields: + +.. include:: /includes/fact-latencystats-reference.rst + +Examples +-------- + +You can run :method:`~db.collection.latencyStats()` in a :program:`mongo` +shell as follows: + +.. code-block:: javascript + + db.data.latencyStats( { histograms: true } ).pretty() + +:method:`~db.collection.latencyStats()` returns a document such as +the following: + +.. code-block:: javascript + + { + "ns" : "test.data", + "localTime" : ISODate("2016-11-01T21:56:28.962Z"), + "latencyStats" : { + "reads" : { + "histogram" : [ + { + "micros" : NumberLong(16), + "count" : NumberLong(6) + }, + { + "micros" : NumberLong(512), + "count" : NumberLong(1) + } + ], + "latency" : NumberLong(747), + "ops" : NumberLong(7) + }, + "writes" : { + "histogram" : [ + { + "micros" : NumberLong(64), + "count" : NumberLong(1) + }, + { + "micros" : NumberLong(24576), + "count" : NumberLong(1) + } + ], + "latency" : NumberLong(26845), + "ops" : NumberLong(2) + }, + "commands" : { + "histogram" : [ ], + "latency" : NumberLong(0), + "ops" : NumberLong(0) + } + } + } diff --git a/source/reference/operator/aggregation/collStats.txt b/source/reference/operator/aggregation/collStats.txt index 75a4d0d03c1..807bf19d731 100644 --- a/source/reference/operator/aggregation/collStats.txt +++ b/source/reference/operator/aggregation/collStats.txt @@ -86,91 +86,7 @@ else the pipeline returns an error. The ``latencyStats`` embedded document only exists in the output if ``$collStats`` receives the ``latencyStats`` option. - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Field Name - - Description - - * - ``reads`` - - Latency statistics for read requests. - - * - ``writes`` - - Latency statistics for write requests. - - * - ``commands`` - - Latency statistics for database commands. - -Each of these fields contains an embedded document bearing the -following fields: - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - Field Name - - Description - - * - ``latency`` - - A :bsontype:`long ` giving the total combined - latency in microseconds. - - * - ``ops`` - - A :bsontype:`long ` giving the total number of - operations performed on the collection since startup. - - * - ``histogram`` - - An array of embedded documents, each representing a latency range. - Each document covers twice the previous document's range. For - upper values between 2048 microseconds and roughly 1 second, - the histogram includes half-steps. - - This field only exists given the - ``latencyStats: { histograms: true }`` option. Empty ranges with - a zero ``count`` are omitted from the output. - - Each document bears the following fields: - - .. list-table:: - - * - Field Name - - Description - - * - ``micros`` - - A :bsontype:`long ` giving the inclusive - upper time bound of the current latency range in - microseconds. - - The document's range spans between the previous document's - ``micros`` value, exclusive, and this document's - ``micros`` value, inclusive. - - * - ``count`` - - A :bsontype:`long ` giving the number of - operations with latency less than or equal to ``micros``. - - For example, if ``collStats`` returns the following histogram: - - .. code-block:: javascript - - histogram: [ - { micros: 1, count: 10 }, - { micros: 2, count: 1 }, - { micros: 4096, count: 1} - { micros: 137438953472, count: 1000 }, - { micros: 274877906944, count: 100 } - ] - - This indicates that there were: - - - 10 operations taking 1 microsecond or less, - - 1 operation in the range (1, 2] microseconds, - - 1 operation in the range (3072, 4096] microseconds, - - 1000 operations in the range (68719476736, 137438953472], and - - 100 operations in the range (137438953472, 274877906944]. - +.. include:: /includes/fact-latencystats-reference.rst For example, if you run ``$collStats`` with the ``latencyStats: {}`` option on a ``matrices`` collection: