考古|ES 5.0 的 cat API 改了列名还删了 total,监控脚本最先遭殃

5.0 的 cat API 变了不少:用 Accept 头取代 Content-Type 决定响应格式、cat nodes 删掉 host 列、cat recovery 一批列名重命名、cat fielddata 从每字段一列改成每字段一行并删掉 total 列。最麻烦的是这些改动不报错,只是取不到值。本文按 v5.6.16 逐条给出原文与行号,并补上 cat API 的通用参数——format=json、h、help 这几个能把这类问题一次性看出来的工具。

说明

实测环境:本地起的 Elasticsearch 5.6.16 单节点实例(官方 tar 包直接跑,堆内存 512MB,机器学习关闭),curl 连本地 9200 端口。本文「实测」小节的命令和输出都出自这个实例。

来源和边界先交代:本文的依据出自 v5.6.16 标签下的官方文件(cat.asciidoc、cat.asciidoc),文中引用的原文均来自这些文件。示例取自官方示例;哪些是文档写明、哪些是我的推断,正文里逐处标注。

图 1:官方文件 cat.asciidoc(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 cat.asciidoc

升级后最先发现不对的是监控脚本

cat API 的定位是"给人看的",但很多脚本直接拿来解析。5.0 这批改动里,有的是列名改了、有的是列直接没了——不会报错,只是取不到值或取到空。

以下全部出自 5.0 迁移文档(migrate_5_0/cat.asciidoc)。

用 Accept 头,不再用 Content-Type

Previous versions of Elasticsearch accepted the Content-type header field for controlling the media type of the response in the cat API. This is in opposition to the HTTP spec which specifies the Accept header field for this purpose. Elasticsearch now uses the Accept header field and support for using the Content-Type header field for this purpose has been removed.

(第 4–11 行)

原来的做法违反 HTTP 规范:Content-Type 描述的是请求体,期望的响应类型该用 Accept。5.0 改成标准做法,并且移除了对 Content-Type 的支持。

# 5.0 之前
curl -H 'Content-Type: application/json' 'localhost:9200/_cat/nodes'

# 5.0 起
curl -H 'Accept: application/json' 'localhost:9200/_cat/nodes'

这里要说清楚:老脚本靠 Content-Type 拿 JSON,5.0 之后拿到的还是默认文本格式,字段解析会全线错位——而且 HTTP 状态码是 200,看不出问题。

除了 Accept 头,cat API 也支持 format 查询参数指定响应格式:text(默认)、json、smile、yaml、cbor(cat.asciidoc 第 23 行起,示例是 curl 'localhost:9200/_cat/indices?format=json&pretty')。我的建议是脚本解析直接用 format=json,不依赖请求头。

图 2:官方页面 rest.asciidoc(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 docs/reference/migration/migrate_5_0/rest.asciidoc

cat nodes 没有 host 列了

The host field has been removed from the cat nodes API as its value is always equal to the ip field. The name field is available in the cat nodes API and should be used instead of the host field.

(第 13–17 行)

去掉的理由很直接:host 的值总是等于 ip,属于冗余列。文档建议用 name 代替。

cat recovery 改了一批列名

新增两列(第 19–23 行):

The fields bytes_recovered and files_recovered have been added to the cat recovery API. These fields, respectively, indicate the total number of bytes and files that have been recovered.

重命名(第 25–32 行):

5.0 之前5.0 起
total_filesfiles_total
total_bytesbytes_total
translogtranslog_ops_recovered(短别名 tor)
translog_totaltranslog_ops(短别名 to)
translog_percenttranslog_ops_percent(短别名 top)

translog 这三列的语义其实更清楚了:旧名字 translog 到底指"已恢复的操作数"还是"总数"看不出来,新名字加了 _ops、_recovered、_percent 后缀。

脚本里如果用的是短别名(tor、to、top),也要一起改。

图 3:官方页面 http.asciidoc(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 docs/reference/migration/migrate_5_0/http.asciidoc

cat nodes 的角色列变了

The cat nodes endpoint returns m for master eligible, d for data, and i for ingest. A node with no explicit roles will be a coordinating only node and marked with -. A node can have multiple roles. The master column has been adapted to return only whether a node is the current master (*) or not (-).

(第 34–40 行)

两点变化:

  • 节点可以有多个角色,所以这列是组合值(比如 di、mi),不再是单一角色;
  • master 列只回答"是不是当前 master":* 或 -。

想判断"哪些节点是候选 master",要看角色列里有没有 m,不能看 master 列。

这和 5.0 删除 node.client、角色改成 node.master / node.data / node.ingest 分开配置是配套的:角色从"互斥分类"变成"可组合开关",cat 输出的口径也跟着变。

cat fielddata 从宽表变长表

The cat field data endpoint adds a row per field instead of a column per field.

The total field has been removed from the field data API. Total field data usage per node can be got by cat nodes API.

(第 42–47 行)

原来是"每个字段一列",现在是"每个字段一行"。字段一多的时候,原来的输出会宽到没法看;改成长表之后列数固定,解析也更稳。

同时删掉了 total 列:每个节点的 fielddata 总用量改从 cat nodes 取。所以原来从 cat fielddata 读 total 的监控,要么改成读 cat nodes 的对应列,要么把各字段行加起来。

升级前该查什么

检查项说明
脚本里是否用 Content-Type 要 JSON改成 Accept,或直接用 ?format=json
是否取 _cat/nodes 的 host换成 ip 或 name
是否解析 _cat/recovery 的列名按上表改;短别名也要一起改
是否按 master 列判断候选主节点改成看角色列里的 m
是否按列解析 _cat/fielddata改成按行解析;total 改从 cat nodes 取

为什么脚本解析 cat API 本身就危险

这批改动暴露了一个更普遍的问题:cat API 是给人看的,不该被脚本当数据源用。

cat API 的设计目标写在文档开头(cat.asciidoc 第 9–11 行):JSON 适合机器,但在终端里人眼需要紧凑、对齐的文本,cat API 就是为满足这个需求而存在的。列名是简写、输出是文本表格、列会按需增减。5.0 这次就是一次集中变动,文档没有对它做"列名不会变"的承诺。

脚本真正该用的是对应的 JSON API:

想要什么别用改用
节点信息_cat/nodesGET _nodes
索引信息_cat/indicesGET _cluster/state
分片分配_cat/shardsGET _cluster/state;排障用 GET _cluster/allocation/explain
恢复进度_cat/recoveryGET _index/_recovery

换成 JSON API 之后,字段路径是稳定的、有类型、有文档。cat API 留给交互式排查用就好。

历史脚本一时改不完,现实做法是分两步:先把列名对一遍让它能跑(本文列的这些改动),再逐步迁移到 JSON API。但要清楚 cat API 的输出不属于稳定契约——这次改了列名,下次也可能改。

升级核对的具体做法

在升级前后各抓一次 cat 输出,直接对比表头:

# 升级前
curl -s 'localhost:9200/_cat/nodes?format=json' | python3 -c "
import sys,json; d=json.load(sys.stdin); print(sorted(d[0].keys()) if d else '')" > cat_nodes_before.txt

# 升级后再跑一次,然后 diff
diff cat_nodes_before.txt cat_nodes_after.txt

format=json 让它变成结构化数据,取键名排序后对比。diff 里消失的列就是要处理的地方。

几个要点:

  • 每个用到的 cat 端点都要单独抓(nodes、indices、shards、recovery…),它们的改动互不相干;
  • ?help 能列出该端点当前支持的所有列(cat.asciidoc 第 32 行),比查文档快;?v 会显示表头,方便人工看;?h= 用来指定要哪些列(第 15 行附近);
  • 注意 Accept 头那条:如果脚本用 Content-Type 拿 JSON,现在拿到的是文本,键名对比会完全不同——这个问题在 diff 里表现为"整体都对不上",一眼能看出来。

做完这一步,cat API 相关的升级风险基本就覆盖了。成本就是几条命令加一次 diff,比升级后等监控告警便宜得多。

在 5.6.16 上跑一遍

同一个 cat 接口,换列名:

图 4:本地 5.6.16 单节点实例上的实测输出。上:新列名 docs.count;下:老列名 total

curl -s "http://localhost:9200/_cat/indices/c1?h=index,docs.count"
curl -s "http://localhost:9200/_cat/indices/c1?h=index,total"

echo "--- 对照:v 参数下列名都是什么 ---"
curl -s "http://localhost:9200/_cat/indices/c1?v" | head -1

docs.count 那次输出 c1 2;换成 total 之后只输出 c1,那一列是空的。

关键在于它不报错。cat 接口对不认识的列名既不报 400 也不输出提示,只是那一列什么都不给。监控脚本里如果是按列位置取值的,拿到的是空字符串,接着被当成 0 参与计算——磁盘告警、文档数告警都会"看起来正常"。

第三行对照给出了 5.6.16 上完整的列名:health status index uuid pri rep docs.count docs.deleted store.size pri.store.size。迁移时拿这份清单和脚本里的 h= 参数逐个对齐,比读文档快。

结论是:升级后先跑一次 ?v 把列名打出来存基线,再和脚本里写死的列逐个比;cat 这类接口的变更不会报错,只能靠比对发现。

写在最后

cat API 的改动不报错,这是它比 REST API 变更更隐蔽的地方——升级后脚本静默取空。

优先改用 format=json 而不是按列位置解析文本,能避开这一类问题。真要长期稳定取数据,改用对应的 REST API:cat 的列名本来就允许调整,监控、巡检这类需要长期运行的脚本,我的判断是一律不要依赖它的列位置。

排查时 ?help 和 format=json 是最省事的两个工具:一个告诉你现在有哪些列,一个让输出变成可解析的结构。升级前后各跑一次做 diff,变化的列一眼可见。

参考

以上列名与原文均取自本地 elasticsearch 仓库 v5.6.16 标签下的 5.0 迁移文档。

本文对照 Elasticsearch v5.6.16 标签的官方文档核对,引文逐字取自原文。图 4 的列名对照来自本地 5.6.16 单节点实例。

0
0
0
0
评论
未登录
暂无评论