CAT 观测 - 检索分析服务Elasticsearch版

CAT API 适合人工观察和故障排查。日常总览先查看 Collection；容量或分片异常时再查看 Backing；定位特定命名空间的数据分布和文档数时查看 Slice。应用业务请求不应依赖 CAT 输出。

重要

Slice CAT 会查询数据并统计文档数，可能跨多个 Backing 执行搜索和聚合，不能作为入门验证、业务请求或高频巡检的固定步骤。 排查时尽量指定单个 Slice 或 Backing，并控制调用频率。h 只筛选返回的列，即使不显示 docs.count，服务端仍会执行文档统计。仅需获取 Slice 名单时，使用分页列出 Slice接口，无需统计文档数。

观察层级	API	主要信息
Collection	`GET /_cat/slice_collection[/{name}]`	生命周期状态、Backing 数、Slice 数、容量、文档数和数据集大小
Backing	`GET /_cat/slice_collection/{collection}/backings[/{backing}]`	健康状态、是否接收新 Slice、分片、副本、容量、存储大小和未分配分片数
Slice	`GET /_cat/slice_collection/{collection}/slices[/{slice}]`	Slice 所在 Backing、目标分片、副本数和文档数

默认列：

观察层级	默认列
Collection	`collection`、`state`、`backings`、`slices`、`capacity`、`remaining`、`docs.count`、`dataset.size`
Backing	`backing`、`health`、`assign`、`pri`、`rep`、`slices`、`capacity`、`remaining`、`docs.count`、`pri.store.size`、`store.size`、`unassigned`
Slice	`slice`、`backing`、`shardIds`、`rep`、`docs.count`

通用查询参数：

参数	说明
`v`	是否显示表头。
`format`	输出格式，例如 `json`、`yaml` 或 `text`。
`h`	只返回指定列。
`s`	按指定列排序，例如 `docs.count:desc`。
`bytes`	指定存储大小单位。
`help`	显示可用列。

面向程序处理时，建议使用 format=json 并显式指定列，不要依赖默认列永久不变：

GET /_cat/slice_collection/knowledge-chunks?format=json&h=collection,state,backings,slices,docs.count,dataset.size

Collection 和 Backing 说明

{name} 支持精确名称、逗号列表和通配符；Backing 和 Slice CAT 的 {collection} 必须是精确名称。
dataset.size 是所有 Backing 的主分片数据集大小之和，每个分片只统计主分片，不会按副本数放大。
Backing 的 remaining 不等于“必然还会分配”的数量。assign=disabled 时，即使 remaining 大于 0，该 Backing 也不会接收新 Slice。
主分片尚未全部 started 时，docs.count 和 pri.store.size 可能为空。应结合 health 和 unassigned 判断，不要把空值当作 0。
pri.store.size 和 store.size 表示已索引数据大小，不等同于无状态节点的本地磁盘占用，也不包含对象存储中等待清理的历史数据。
Collection 摘要和 Backing 列表展开范围超过 10000 个 Backing 时返回 HTTP 400，应使用更精确的 Collection 范围。

Slice 列表的专用参数

参数或写法	行为
`/{slice}`	精确查询一个 Slice；不存在时返回 HTTP 404。
`backing={backing}`	只看一个完整 Backing 名下的 Slice。
`backing={backing}&shard={id1,id2,...}`	只返回该 Backing 中搜索路由会命中任一指定主分片 ID 的 Slice。`shard` 支持逗号分隔的多值，且必须与精确的 `backing` 同时提供。
默认排序	按 `slice` 升序返回。
`s=docs.count:asc` 或 `s=docs.count:desc`，同时指定 `backing`	在该 Backing 上按文档数方向选择并返回。
`s=docs.count:asc` 或 `s=docs.count:desc`，同时指定 `allow_expensive_search=true`	在全部 Backing 上按文档数方向选择并返回。

按分片过滤示例：

GET /_cat/slice_collection/knowledge-chunks/backings?v

再使用返回的完整 Backing 名称筛选 Slice：

GET /_cat/slice_collection/knowledge-chunks/slices?backing=<完整的Backing名称>&shard=0,1&h=slice,backing,shardIds&format=json

先从第一条请求的结果中取得完整的 backing 名称，替换第二条请求中的占位符。该名称仅用于本次运维过滤，应用读写仍通过 Collection 和 _slice 访问。

shard 必须落在 0 到 index.number_of_shards 减 1 的范围内，超出范围返回 HTTP 400；只传 shard 而不传 backing 也返回 HTTP 400。多个分片 ID 按 OR 语义匹配。当 docs.count（或别名 dc）是 s 的第一个排序字段时，shard 不能与该排序同时使用。

s=docs.count 的默认方向是升序。只要 docs.count 是第一个排序字段，升序和降序都会先在目标 Backing 上聚合再选择结果；不指定 backing 时会扫描 Collection 的全部 Backing，因此未显式设置 allow_expensive_search=true 时返回 HTTP 400，该开关只对当前请求生效。其他字段作为第一个排序条件时，只对已经按 Slice 名选出的结果排序，不计算全局排名。

文档数为 0 的 Slice 不会出现在文档数排序结果中，但仍会出现在默认列表或精确 Slice 查询中。

CAT 使用建议

结果超过行数上限时不分页，而是返回上限行数并通过 HTTP Warning header 提示结果不完整。
文档数排序结果使用分布式聚合。如果排序或计数可能存在误差，也会通过 Warning header 提示。
CAT 是近实时视图，刚写入但尚未 Refresh 的文档可能尚未计入 docs.count。
当前版本不提供单 Slice 存储大小，也不支持按 Slice 存储大小排序。需要单 Slice 文档数时，使用查询单个 Slice 的 include_doc_count=true。
使用 Branch Slice（Beta）时，多行 CAT 列表和文档数排序不会完整计入继承数据，应按该篇说明单独查询目标的文档数。

实例监控指标和控制台入口见集群监控。