在安装 ES 的一章中，我们介绍并且安装了 Cerebro，Cerebro 为我们提供了简单的集群管理功能，这些监控、管理的功能都是通过 ES 提供的 API 来实现的，那今天我们就来认识一下 ES 提供的集群监控、管理相关的 API 吧。

今天的内容主要有：

  1. 使用 _cat（Compact and aligned text） APIs 查看集群相关的信息。
  2. 通过集群管理 API 进行信息查看和修改集群设置。

一、_cat APIs

_cat APIs 为用户提供查看集群相关信息的同时，其特别之处在于它返回的结果不是 JSON，而是非常适合人类阅读的格式。

当使用 _cat 时其后面不跟任何子节点，其返回结果将会是各个 API 的目录（URL），当我们忘记有啥接口的时候，这个功能非常好用。其示例如下：

  1. # 使用 _cat API 获取所有可用的目录
  2. GET /_cat/
  4. # 结果
  5. /_cat/allocation
  6. /_cat/shards
  7. /_cat/shards/{index}
  8. /_cat/master
  9. /_cat/nodes
  10. /_cat/tasks
  11. /_cat/indices
  12. /_cat/indices/{index}
  13. /_cat/segments
  14. /_cat/segments/{index}
  15. /_cat/count
  16. /_cat/count/{index}
  17. ......

如上示例可以看到，_cat APIs 返回了多个 API 的目录，这些 API 都可以加入下面几个参数：

  • v 参数：每个命令都可以使用 v 参数来打印详细信息。如：GET /_cat/nodes?v。
  • h 参数：使用 h 参数可以强制只显示某些列。如：GET /_cat/nodes?h=node.role,port,name。
  • help 参数：使用 help 参数可以输出这个接口可用的列名和其解析。如：GET /_cat/master?help。

_cat APIs 中为用户提供了非常多的 API，由于这些 API 都比较简单，而且这些 API 都是见名知其意的，所以下面只展示部分接口的使用示例，更多关于 _cat APIs 的使用示例，可以参考官方文档。

1. 查看索引文档总数和整个集群文档总数

  1. # 获取索引 books 的文档总数
  2. GET /_cat/count/books?v
  4. #结果
  5. epoch      timestamp count
  6. 1641971532 07:12:12  7
  9. # 获取整个集群所有索引的文档总数
  10. GET /_cat/count?v
  12. #结果
  13. epoch      timestamp count
  14. 1641971546 07:12:26  109

如上示例，使用了 /_cat/count 来获取索引的文档数量，从返回结果可以看出，其格式是适合人类阅读的，而不是适合计算机解析的 JSON 格式。

2. 查看集群健康状态

  1. # 查看集群健康状态
  2. GET /_cat/health?v
  3. GET /_cat/health?v&ts=false
  5. # 结果
  6. cluster status node.total node.data ......
  7. my_app  green           3         3 ......

如上示例，使用 /_cat/health?v 可以获取集群的健康状态，其返回结果中可以看到，此时集群的状态为 green，共有 3 个节点，而且都是数据节点。ts=false 的参数是返回结果中去除时间戳。

3. 查看磁盘使用情况

  1. # 获取各个节点磁盘的使用情况
  2. GET /_cat/allocation?v
  4. # 结果
  5. shards disk.indices disk.used disk.avail disk.total disk.percent ... node
  6.     13      152.4mb    71.6gb      123gb    194.7gb           36     my_node_1
  7.     13      150.1mb    71.6gb      123gb    194.7gb           36     my_node_2
  8.     12        2.2mb    71.6gb      123gb    194.7gb           36     my_node_3

如上示例，我们查看了各个节点磁盘的使用情况，可以看到 my_node_1 节点共 194.7 gb 空间，用了 71.6 gb，my_node_1 中分配了 13 个分片，索引的数据用了 152.4 mb。

二、集群管理 API

集群管理的 API 提供了获取或者更改集群信息的功能，例如集群节点过滤、查看集群信息、查看节点信息、更新集群设置、重置路由等。

1. 集群节点过滤

如果我们需要查看某些节点的信息时，就需要用到过滤节点的功能了，如下图是 Cerebro 中进行节点筛选的功能。

节点筛选.png

要过滤集群节点可以使用 ES 提供的节点过滤的 API，其简单示例如下：

  1. # 获取所有简单
  2. GET /_nodes/_all

如上示例，其返回结果是一大串 JSON 内容（这里就不列出来了），包含了所有节点相关的信息。

除了 _all 外，ES 支持的节点过滤器有如下几个：

  • _all：列出所有节点。
  • _local：列出本地节点。
  • _master：列出主节点
  • IP 或者主机名字：列出指定 IP 或者主机名字的节点。
  • 节点 ID 或者名称：列出指定 ID 或者名称的节点。
  • *：IP、主机名字、节点 ID、名称都可以包括通配符。
  • master:true/false：列出主节点 / 不列出主节点。
  • data:true/false：列出数据节点 / 不列出数据节点。
  • ingest:true/false：列出索引预处理节点 / 不列出索引预处理节点。
  • coordinating_only:true/false：列出协调节点 / 不列出协调节点。

下面的示例可以实现上图的节点过滤效果：

  1. # 节点类型过滤
  2. GET /_nodes/master:true,data:true,ingest:true,coordinating:true

如上示例，我们过滤出了 master、data、ingest、coordinating 节点的信息，其返回结果是一大串 JSON，这里省略。

如果只想返回某个节选部分的结果，可以使用以下示例：

  1. # 列出 process 节选信息
  2. GET /_nodes/master:true,data:true,ingest:true,coordinating:true/process

如上示例就是列出了 process 部分的信息。更多的使用示例你可以参考官方文档。

2. 查看集群信息

可以使用集群信息查看的接口查看集群健康状态、集群状态、集群统计信息、集群的设置等，它们的使用示例如下：

  1. # 查看集群健康状态
  2. GET /_cluster/health
  4. # 查看集群状态
  5. GET /_cluster/state
  7. # 查看集群统计信息
  8. GET /_cluster/stats?human&pretty
  10. # 查看集群的设置
  11. GET /_cluster/settings?include_defaults=true

3. 查看节点信息

查看节点信息的 API 比较简单，其示例如下：

  1. # 获取节点信息的请求格式
  2. GET /_nodes
  3. GET /_nodes/<node_id>
  4. GET /_nodes/<metric>
  5. GET /_nodes/<node_id>/<metric>
  7. # 获取节点信息的示例
  8. GET /_nodes
  9. GET /_nodes/node_id1,node_id2 # 获取 node_id1 和 node_id2 的信息
  10. GET /_nodes/stats 
  11. GET /_nodes/node_id1,node_id2/stats # 获取 node_id1 和 node_id2 的统计信息

其中 metric 可以指定获取结果中的每个部分，其选项比较多，你可以参考官方文档。

4. 更新集群设置

更新集群设置的示例如下：

  1. PUT /_cluster/settings
  2. {
  3.   "persistent": {
  4.     "indices.recovery.max_bytes_per_sec": "100m"
  5.   }
  6. }

如上示例，我们设置了集群恢复时的吞吐量，其默认值为 0 的时候为无限制。

5. 重置路由

reroute API 可以允许用户手动修改集群中分片的分配情况。使用 reroute API 可以将一个分片从某个节点移到另一个节点，也可以将未分配的分片指定分配到某个节点。下面是来自官方的示例：

  1. POST /_cluster/reroute
  2. {
  3.   "commands": [
  4.     {
  5.       "move": {
  6.         "index": "test", "shard": 0,
  7.         "from_node": "node1", "to_node": "node2"
  8.       }
  9.     },
  10.     {
  11.       "allocate_replica": {
  12.         "index": "test", "shard": 1,
  13.         "node": "node3"
  14.       }
  15.     }
  16.   ]
  17. }

如上示例，使用 “move” 指令，将索引 “test” 的分片 0 从节点 “node1” 移动到了 “node2”。使用 “allocate_replica” 指令将 “test” 索引未分配的分片 1 的副本分配到节点 “node3”。

需要注意的是，在执行了任何路由重置指令后， ES 将会执行重新平衡数据的操作来保持平衡状态，但是这个操作受 cluster.routing.rebalance.enable（是否允许重新平衡） 设置值的影响。

reroute API 在 ES 集群运维的时候经常用到，更详细的使用示例你可以参考官方文档。

四、总结

今天为你介绍了集群管理相关的 API 和它们的使用示例。

由于 JSON 的格式不太适合我们人类的阅读，ES 为我们提供了 _cat API 来获取集群的信息，其返回的结果的格式紧凑，适合我们阅读。当我们忘记了 _cat API 集合里有啥 API 时，可以在使用 _cat 时其后面不跟任何子节点，其返回结果将会是各个 API 的目录（URL）。

相对于 _cat API， 集群管理的 API 返回的结果都是 JSON 的，其更适合给程序进行处理。我们可以利用集群管理的 API 获取集群的信息，并且可以修改集群配置。

好了今天的内容到此为止，今天介绍的集群管理 API 是比较常用的功能了，ES 提供的集群管理 API 也是非常丰富的，更多的使用例子可以参考官方文档。