MongoDB聚合：$collStats

聚合阶段$collStates用于返回集合或视图统计信息。

语法

{
  $collStats:
    {
      latencyStats: { histograms: <boolean> },
      storageStats: { scale: <number> },
      count: {},
      queryExecStats: {}
    }
}

参数说明

$collStats接收一个文档参数，可选的字段如下：

latencyStats 延迟统计信息

向返回结果添加延迟统计信息，包括读、写、命令、事务的时间。

latencyStats.histograms 延迟统计柱状图数据

当值为true时，向latencyStats内嵌文档中添加时延柱状图数据序列，根据这个序列可以生成柱状图。

storageStats 存储相关信息

向返回结果文档添加存储相关的统计信息：

• 指定一个空的文档（如：storageStats: {}），表示数据大小的缺省比例因子为1，会以字节为单位返回数据大小。
• 指定比例因子（即 storageStats: { scale: }），对数据使用指定的比例因子。例如，要显示千字节而不是字节，可指定比例因子为 1024。
  如果指定的是非整数比例因子，MongoDB 将使用指定因子的整数部分。例如，如果指定比例因子为 1023.999，MongoDB 将使用 1023 作为比例因子。
  比例因子不会影响那些在字段名中指定测量单位的大小，例如 “当前缓存中的字节数”。

count 文档计数

将集合文档总数添加到返回结果文档中。计数基于数据集的元数据，可为分片集群提供快速但有时不准确的计数。

queryExecStats 执行统计信息

添加查询执行统计信息到返回文档中。

对于副本集中的集合或集群中的非分片集合，$collStats 会输出一个文档。对于分片集合，$collStats 会为每个分片输出一个文档。输出文档包括以下字段：

字段名	含义
ns	请求的集合或视图的命名空间。
shard	输出文档对应的分片名称。仅当$collStats在分片集群上运行时才会出现。分片集群和非分片集群都会产生这个字段。
host	生成输出文档的 mongod 进程的主机名和端口。
localTime	MongoDB 服务器上的当前时间，以 UNIX 纪元后的 UTC 毫秒表示。
latencyStats	与集合或视图的请求延迟有关的统计信息。仅在指定latencyStats：{}选项时才有。
storageStats	与数据集存储引擎相关的统计信息。各种大小数据按指定系数比例（在字段名中指定测量单位的大小除外）。只有指定 storageStats 选项时才会出现。如果应用于视图，则返回错误信息。
count	集合中的文档总数。存储统计计数（storageStats.count）中也有该数据。仅在指定 count：{} 选项时才会出现。如果应用于视图，则返回错误信息。
queryExecStats	与执行集合查询相关的统计信息。仅在指定queryExecStats：{}选项时才会出现。如果应用于视图，则返回错误信息。

使用

$collStats必须是聚合管道的第一阶段，否则管道会返回错误。

使用可查询加密时，$collStats 输出会对加密集合的某些信息进行编辑：

• 输出会省略 "queryExecStats"。
• 输出省略 "latencyStats"
• 输出中删除了 "WiredTiger"（如果存在），只包含 url 字段。

**注意：**事务中不能使用$collStats。

latencyStats 文档

只有指定了latencyStats选项，输出中才会嵌入latencyStats文档。

字段名	描述
reads	读取请求的延迟统计数据。
writes	写入请求的延迟统计数据。
commands	数据库命令的延迟统计。
transactions	数据库事务的延迟统计。

每个字段都包含一个嵌入文档，其中包含以下字段：

• latency，一个 64 位整数，表示以微秒为单位的总延迟时间。

• ops，一个 64 位整数，表示自启动以来对数据集执行的操作总数。

• histogram，嵌入式文档数组，每个文档代表一个延迟范围。每个文档的范围是前一个文档范围的两倍。对于介于 2048 微秒和大约 1 秒之间的上限值，直方图包含半步。只有在使用 latencyStats：{ histograms: true } 选项，输出中将省略计数为零的空范围。每份文档都有以下字段：

  字段	描述
  micros	一个 64 位整数，以微秒为单位表示当前延迟范围的时间上限。文档的范围介于上一个文档的微妙值（不包括）和本文档的微秒值（包括）之间。
  count	一个 64 位整数，表示延迟小于或等于微秒的操作次数。
  例如，如果collStats会返回如下直方图数据：

  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) }]
  

  这表明：

  • 10次操作耗时1微秒或更短
  • 在(1, 2]微秒范围内进行1次操作
  • 在(3072, 4096]微秒范围内进行1次操作
  • 在(12288, 16384]微秒范围内进行1000次操作
  • 在(32768, 49152]微秒范围内进行100次操作

例如，如果使用 latencyStats：{} 选项在matrices集合上运行：

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

该查询返回的结果类似于下面的内容：

{ "ns" : "test.matrices",
  "host" : mongo.example.net:27017",
  "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  "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" : [
            {
               "micros" : NumberLong(196608),
               "count" : NumberLong(1)
            }
          ],
          "latency" : NumberLong(0),
          "ops" : NumberLong(0) },
      "transactions" : {
         "histogram" : [ ],
         "latency" : NumberLong(0),
         "ops" : NumberLong(0)
      }
    }
}

storageStats文档

只有指定了storageStats选项，输出中才会出现storageStats嵌入文档。

该文档的内容取决于使用的存储引擎。有关此文档的参考信息，请参阅输出。

例如，在使用WiredTiger存储引擎的matrices集合上，使用storageStats：{}选项，运行$collStats：

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

该查询返回的结果类似于下面的内容：

{
  "ns" : "test.matrices",
  "host" : mongo.example.net:27017",
  "localTime" : ISODate("2020-03-06T01:44:57.437Z"),
  "storageStats" : {
    "size" : 608500363,
    "count" : 1104369,
    "avgObjSize" : 550,
    "storageSize" : 352878592,
    "freeStorageSize" : 2490380,  // Starting in MongoDB 4.4
    "capped" : false,
    "wiredTiger" : {
      ...
    },
    "nindexes" : 2,
    "indexDetails" : {
      ...
    },
    "indexBuilds" : [
       "_id_1_abc_1"
    ],
    "totalIndexSize" : 260337664,
    "totalSize" : 613216256,    // Starting in MongoDB 4.4
    "indexSizes" : {
      "_id_" : 9891840,
      "_id_1_abc_1" : 250445824
    },
    "scaleFactor" : 1
  }
}

在视图上使用 storageStats 选项执行 $collStats 会导致错误。

count字段

只有指定了count选项，输出中才会出现计数字段。

例如，在matrices集合上使用count:{}选项运行$collStats：

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

查询返回的结果如下：

{
  "ns" : "test.matrices",
  "host" : mongo.example.net:27017",
  "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  "count" : 1103869
}

当指定storageStats: {}时，storageStats.count会返回集合中的文档总数。

queryExecStats文档

只有指定了queryExecStats选项，输出中才会出现queryExecStats嵌入文档。collectionScans字段包含一个嵌入文档，其中包含以下字段：

字段名	描述
total	一个 64 位整数，表示执行集合扫描的查询总数。总数包括使用和未使用可跟踪游标的查询。
nonTailable	一个 64 位整数，表示执行未使用可跟踪游标的集合扫描的查询次数。

例如，在matrices集合上使用queryExecStats：{}选项运行：

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

查询返回的结果如下：

{
  "ns": "test.matrices",
  "host": "mongo.example.net:27017",
  "localTime": ISODate("2020-06-03T14:23:29.711Z"),
  "queryExecStats": {
      "collectionScans": {
          "total": NumberLong(33),
          "nonTailable": NumberLong(31)
      }
  }
}

分片集合的$collStats

在分片集合上运行时，$collStats会为每个分片输出一份文档。每个输出文档都包含一个分区字段，该字段包含文档对应的分区名称。

例如，如果在使用count：{}选项在名为matrices的集合上运行$collStats：：

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

查询返回的结果如下：

{
  "ns" : "test.matrices",
  "shard" : "s1",
  "host" : "s1-mongo1.example.net:27017",
  "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  "count" : 661705
}
{
  "ns" : "test.matrices",
  "shard" : "s2",
  "host" : "s2-mongo1.example.net:27017",
  "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  "count" : 442164
}