Navigation
This version of the documentation is archived and no longer supported.

$collStats (aggregation)

On this page

Definition

$collStats

New in version 3.4.

Returns statistics regarding a collection or view.

The $collStats stage has the following prototype form:

copy 
{
  $collStats:
    {
      latencyStats: { histograms: <boolean> },
      storageStats: {}
    }
}

All of the fields in the argument document are optional.

  • latencyStats adds latency statistics to the return document.
  • latencyStats.histograms adds latency histogram information to latencyStats if true.
  • storageStats adds storage statistics to the return document.

The return document includes the following fields:

Field Name Description
ns The namespace of the requested collection or view.
localTime The current time on the MongoDB server, expressed as UTC milliseconds since the Unix epoch.
latencyStats

A collection of statistics related to request latency for a collection or view. See latencyStats Document for details on this document.

Only exists given the latencyStats: {} option.
storageStats

A collection of statistics related to a collection’s storage engine. See storageStats Document for details on this document.

Only exists given the storageStats: {} option. Returns an error if applied to a view.

Behavior

$collStats must be the first stage in an aggregation pipeline, or else the pipeline returns an error.

latencyStats Document

The latencyStats embedded document only exists in the output if $collStats receives the latencyStats option.

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:

Field Name Description
latency A long giving the total combined latency in microseconds.
ops A 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:

Field Name Description
micros

A 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 long giving the number of operations with latency less than or equal to micros.

For example, if collStats returns the following histogram:

copy 
histogram: [
  { micros: NumberLong(1), count: NumberLong(10) },
  { micros: NumberLong(2), count: NumberLong(1) },
  { micros: NumberLong(4096), count: NumberLong(1) },
  { micros: NumberLong(16384), count: NumberLong(1000) },
  { micros: NumberLong(49152), 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 (12288, 16384], and
  • 100 operations in the range (32768, 49152].

For example, if you run $collStats with the latencyStats: {} option on a matrices collection:

copy 
db.matrices.aggregate( [ { $collStats: { latencyStats: { histograms: true } } } ] )

This query will return a result similar to the following:

copy 
{ "ns" : "test.matrices",
  "localTime" : ISODate("2016-10-25T21:47:54.233Z"),
  "latencyStats" :
    { "reads" :
        { "histogram" : [
            { "micros" : NumberLong(16),
              "count" : NumberLong(3) },
            { "micros" : NumberLong(32),
              "count" : NumberLong(1) },
            { "micros" : NumberLong(128),
              "count" : NumberLong(1) } ],
          "latency" : NumberLong(264),
          "ops" : NumberLong(5) },
      "writes" :
        { "histogram" : [
            { "micros" : NumberLong(32),
              "count" : NumberLong(1) },
            { "micros" : NumberLong(64),
              "count" : NumberLong(3) },
            { "micros" : NumberLong(24576),
              "count" : NumberLong(1) } ],
          "latency" : NumberLong(27659),
          "ops" : NumberLong(5) },
      "commands" :
        { "histogram" : [ ],
          "latency" : NumberLong(0),
          "ops" : NumberLong(0) }
    }
}

storageStats Document

The storageStats embedded document only exists in the output if $collStats receives the storageStats option.

The contents of this document are dependent on the storage engine in use. See Output for a reference on this document.

For example, if you run $collStats with the storageStats: {} option on a matrices collection using the WiredTiger Storage Engine:

copy 
db.matrices.aggregate( [ { $collStats: { storageStats: { } } } ] )

This query will return a result similar to the following:

copy 
{
  "ns" : "test.matrices",
  "localTime" : ISODate("2016-10-25T19:43:56.599Z"),
  "storageStats" : {
    "size" : 192,
    "count" : 4,
    "avgObjSize" : 48,
    "numExtents" : 1,
    "storageSize" : 8192,
    "lastExtentSize" : 8192,
    "paddingFactor" : 1,
    "paddingFactorNote" : "paddingFactor is unused and unmaintained in 3.0. It    remains hard coded to 1.0 for compatibility only.",
    "userFlags" : 1,
    "capped" : false,
    "nindexes" : 1,
    "indexDetails" : {

    },
    "totalIndexSize" : 8176,
    "indexSizes" : {
      "_id_" : 8176
    }
  }
}

Performing $collStats with the storageStats option on a view results in an error.

See also

collStats, db.collection.stats()

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.