In search of a cluster health diagnosis: Introducing the Elasticsearch Health API
TL;DR · AI 摘要
Elasticsearch 8.7 新增 Health API，提供集群健康诊断与修复指导，支持根因分析和两种操作模式。
核心要点
- Health API 支持 verbose 参数切换高阶模式（green/yellow/red）与详细诊断模式
- 未分配分片的修复需修改 index.routing.allocation.enable 为 all
- 新 API 增加了针对索引和数据流的根因分析功能
结构提纲
按章节快速跳转。
- §引言
提出 Elasticsearch 集群健康诊断的挑战及新 API 的发布背景
通过未分配分片案例说明症状、影响与修复动作的对应关系
设计目标是提供可操作的集群健康状态反馈机制
- ›操作模式
区分高速模式与详细诊断模式的使用场景和性能差异
思维导图
用一张图看清主题之间的关系。
查看大纲文本（无障碍 / 无 JS 友好）
- Elasticsearch Health API
- 核心功能
- 根因分析
- 两种操作模式
- 使用场景
- 集群健康诊断
- 自动监控
金句 / Highlights
值得收藏与分享的关键句。
未分配主分片会导致摄入和备份功能受损，修复需设置 index.routing.allocation.enable=all
详细诊断模式通过 verbose=true 参数启用，但推荐自动监控使用高速模式
新 API 在现有集群健康状态基础上增加根因分析和修复建议功能
寻找集群健康诊断：介绍 Elasticsearch 健康 API | Elastic 博客
寻找集群健康诊断：介绍 Elasticsearch 健康 API
作者
Andrei Dan
2023 年 3 月 30 日
- 在 Twitter 上分享 在 Twitter 上分享
- 在 LinkedIn 上分享 在 LinkedIn 上分享
- 在 Facebook 上分享 在 Facebook 上分享
- 通过电子邮件分享 通过电子邮件分享
- 打印本页 打印
我的 Elasticsearch 集群是否健康？如何修复它？
这些问题很难回答，但作为 Elasticsearch 8.7 的一部分，我们推出了一款新的健康 API，帮助识别和修复 Elasticsearch 集群中的问题。
与现有的集群健康 API 不同（该 API 仅检查索引和数据流的健康状况），新健康 API 还会对不健康的索引和数据流执行根本原因分析，并引入一系列额外的特定功能健康检查。
健康问题的结构与解决方法
Elasticsearch 健康问题通常通过检查 Elasticsearch 分片状态来观察，更常见的是由于高级功能受到影响（例如搜索结果不完整或摄取速度缓慢）。
让我们进一步分析一个 Elasticsearch 健康问题，并介绍一些术语。
我们将以未分配的分片为例，帮助更好地理解这个问题。Elasticsearch 健康问题具有症状，即正在出现问题的可观察的低级 Elasticsearch 原语——在我们的案例中，我们可以观察到一个分片未分配。一个症状可能会对系统造成一个或多个影响。例如，未分配的主分片是一个症状，会导致摄取和备份功能受到影响。一旦发现问题，下一步就是理解问题的根本原因以及需要采取哪些措施来解决问题。在我们的示例中，分片未分配的原因可能是索引级别禁用了分配功能。要使分片重新分配，我们需要按照此分步故障排除指南中的说明，将 index.routing.allocation.enable 索引设置更改为 all。
健康 API 原则
我们构建了一个 API，能够以简单且可操作的方式表明集群如何受到问题的影响。我们希望确保用户能够自行执行必要的操作来修复其集群遇到的问题。
健康 API 的设计考虑了两种运行模式：
- 一种非常快速的高级模式，使用已建立的红色、黄色或绿色状态来指示集群的整体状态。
- 一种更详细的报告模式，同时执行根本原因分析，并将其作为诊断的一部分进行报告，同时附上恢复绿色健康所需的措施。
通过使用 verbose 查询参数可以在两种运行模式之间切换。我们默认使用详细报告模式（verbose=true）；但是，对于任何自动健康轮询，我们建议使用高级模式（verbose=false），因为执行根本原因分析可能是一项昂贵的操作。
高级模式将报告检测到的问题对系统的影响。这些影响使用更贴近用户在讨论 Elasticsearch 在其架构中所扮演角色时使用的术语进行描述（例如搜索、摄取或备份）。
我们利用模块化健康指标来跟踪通常会导致 Elasticsearch 健康问题的几个关键指标。可用的健康指标在此处有详细说明。我们为 Health API 设计的基础设施使得添加更多指标变得简单（对于勇于探索的工程师来说，实现 HealthIndicatorService 和 HealthPlugin 即可完成扩展），并且我们在设计每个新功能时都会评估通过 Health API 表示健康状态的可行性。
每个健康指标将分别报告其自身的状态（红色、黄色或绿色），并在状态非绿色时提供相应的解释。
当无法以高度确定性判断集群健康状态时，我们将通过未知状态进行标识。如果健康指标无法可靠跟踪其指定的指标，该指标会单独返回未知状态。例如，如果集群未选举出稳定的主节点，除 master_is_stable 指标外，所有其他指标都会返回未知状态，因为指标依赖的集群状态信息可能不够及时。
当某个指标报告红色状态时，集群处于需要立即干预的危险状态。这意味着集群稳定性、数据摄入、搜索或备份等功能当前受到严重影响（例如，未分配的主分片会影响数据摄入和搜索）。
黄色状态表示警告。如果不采取行动，集群功能最终可能会受到影响（例如，过去五次连续执行均未成功的 SLM 策略会影响备份，并使部署面临无法获得足够更新快照的风险）。
API 将报告集群的整体状态，该状态将代表所有健康指标中最严重的状态（即，如果任何指标报告黄色，整体状态将显示为黄色）。
示例演示
让我们看看 API 在不同场景下的表现。
绿色健康状态
在健康集群上调用 API 的响应如下：
> GET _health_report
/think
{
"status": "green",
"cluster_name": "d529cccc37ec4091950d92768225be17",
"indicators": {
"master_is_stable": {
"status": "green",
"symptom": "The cluster has a stable master node",
"details": {
"current_master": {
"node_id": "inOUckScRGqxuiw8i7E41w",
"name": "instance-0000000001"
},
"recent_masters": [{
"node_id": "inOUckScRGqxuiw8i7E41w",
"name": "instance-0000000001"
}]
}
},
"repository_integrity": {
"status": "green",
"symptom": "No corrupted snapshot repositories.",
"details": {
"total_repositories": 1
}
},
"shards_availability": {
"status": "green",
"symptom": "This cluster has all shards available.",
"details": {
"creating_primaries": 0,
"unassigned_replicas": 0,
"restarting_primaries": 0,
"restarting_replicas": 0,
"initializing_primaries": 0,
"started_replicas": 89,
"initializing_replicas": 0,
"unassigned_primaries": 0,
"started_primaries": 89
}
},
"disk": {
"status": "green",
"symptom": "The cluster has enough available disk space.",
"details": {
"indices_with_readonly_block": 0,
"nodes_with_enough_disk_space": 3,
"nodes_with_unknown_disk_status": 0,
"nodes_over_high_watermark": 0,
"nodes_over_flood_stage_watermark": 0
}
},
"ilm": {
"status": "green",
"symptom": "Index Lifecycle Management is running",
"details": {
"policies": 40,
"ilm_status": "RUNNING"
}
},
"slm": {
"status": "green",
"symptom": "Snapshot Lifecycle Management is running",
"details": {
"slm_status": "RUNNING",
"policies": 1
}
}
}
}复制到剪贴板
在响应中我们可以看到一些之前已经接触过的熟悉概念。我们有一个顶层的 status 字段，显示为绿色。indicators 对象包含跟踪不同 Elasticsearch 指标的各种健康指标。
我们之前已经提到过 master_is_stable 指标——它用于评估集群是否有一个已选主节点，并且该节点能够持续保持主节点状态（即集群拥有稳定的主节点）。repository_integrity 指标用于监控快照仓库，并报告是否有仓库损坏（通常是因为多个集群写入同一个快照仓库）。shards_availability 指标会报告任何未分配的主分片和副本分片。disk 指标会报告由于磁盘空间不足导致的健康问题（例如被标记为只读的索引）。ilm 指标会检查索引生命周期管理是否正在运行，最后 slm 指标会报告快照生命周期管理是否正在运行以及配置的策略是否连续成功执行。
查看这些指标，我们可以看到它们都报告了一个简要描述分析结果的症状和状态。
我们在调用 API 时没有使用任何查询参数，因此 API 以详细报告模式运行。我们可以看到每个指标都有一个 details 字段，如果将 verbose 参数配置为 false，则不会计算和返回该字段。让我们看看当 verbose=false 时的响应：
> GET _health_report?verbose=false
{ "status": "green", "cluster_name": "d529cccc37ec4091950d92768225be17", "indicators": { "master_is_stable": { "status": "green", "symptom": "集群拥有稳定的主节点" }, "repository_integrity": { "status": "green", "symptom": "未发现损坏的快照仓库。" }, "shards_availability": { "status": "green", "symptom": "集群所有分片均可用。" }, "disk": { "status": "green", "symptom": "集群拥有足够的可用磁盘空间。" }, "ilm": { "status": "green", "symptom": "索引生命周期管理功能正在运行" }, "slm": { "status": "green", "symptom": "快照生命周期管理功能正在运行" } } }
### 黄色健康状态
黄色状态表示存在系统问题，如果长时间不处理，可能导致严重的系统健康问题。我们来看一个健康API指示问题的示例：
/think
GET _health_report
{ "status": "yellow", "cluster_name": "d529cccc37ec4091950d92768225be17", "indicators": { "master_is_stable": { "status": "green", "symptom": "集群拥有稳定的主节点", "details": { "current_master": { "node_id": "inOUckScRGqxuiw8i7E41w", "name": "instance-0000000001" }, "recent_masters": [{ "node_id": "inOUckScRGqxuiw8i7E41w", "name": "instance-0000000001" }] } }, "repository_integrity": { "status": "green", "symptom": "未发现损坏的快照仓库。", "details": { "total_repositories": 1 } }, "shards_availability": { "status": "green", "symptom": "集群所有分片均可用。", "details": { "creating_primaries": 0, "unassigned_replicas": 0, "restarting_primaries": 0, "restarting_replicas": 0, "initializing_primaries": 0, "started_replicas": 89, "initializing_replicas": 0, "unassigned_primaries": 0, "started_primaries": 89 } }, "disk": { "status": "green", "symptom": "集群拥有足够的可用磁盘空间。", "details": { "indices_with_readonly_block": 0, "nodes_with_enough_disk_space": 3, "nodes_with_unknown_disk_status": 0, "nodes_over_high_watermark": 0, "nodes_over_flood_stage_watermark": 0 } }, "ilm": { "status": "green", "symptom": "索引生命周期管理正在运行", "details": { "policies": 40, "ilm_status": "RUNNING" } }, "slm": { "status": "yellow", "symptom": "发现 [1] 个不健康的快照生命周期管理策略。", "details": { "slm_status": "RUNNING", "policies": 1, "unhealthy_policies": { "invocations_since_last_success": { "<cloud-snapshot-{now/d}>": 8 }, "count": 1 } }, "impacts": [{ "id": "elasticsearch:health:slm:impact:stale_snapshots", "severity": 2, "description": "某些自动化快照最近未成功执行。从受影响快照恢复的索引可能不包含最新更改。", "impact_areas": [ "备份" ] }], "diagnosis": [{ "id": "elasticsearch:health:slm:diagnosis:check_recent_snapshot_failures", "cause": "自动化快照策略不健康：\n- [<cloud-snapshot-{now/d}>] 自 [2022-12-23T15:29:59.803Z] 起已发生 [8] 次重复失败且未成功执行", "action": "检查快照生命周期策略以获取详细失败信息：\n- /_slm/policy/cloud-snapshot-policy?human", "help_url": "https://ela.st/fix-recent-snapshot-failures", "affected_resources": { "slm_policies": [ "<cloud-snapshot-{now/d}>" ] } }] } } }
注意 slm 指标报告了黄色状态（这也会反映在顶层状态字段中）。由于我们报告了一个健康问题（非绿色状态），API 将返回诊断信息。
原因字段将描述问题的根本原因。在此情况下，由于自动化快照生命周期策略在八次连续执行中均未能成功创建快照。操作字段是对需要执行的操作步骤的简要概述，或指向获取更多问题信息的指引。
在 help_url 中，您将获得详细的故障排除指南。当问题被报告时，这是需要深入探索的入口。该指南针对 API 诊断的具体问题，包含修复问题的详细步骤、获取有关部署状态的更多信息，或联系我们的支持团队的指引。
最后，诊断结果可选择性地报告受影响资源列表（affected_resources）。这些是受健康状态直接影响的 Elasticsearch 内部抽象概念。我们可报告索引、节点、快照生命周期策略、索引生命周期策略、功能状态或快照仓库。
### 红色健康状态
红色健康状态表示需要立即解决的严重问题，因为它会严重影响一个或多个 Elasticsearch 功能。
让我们来看一个示例：
/example
GET _health_report
{ "status": "red", "cluster_name": "d529cccc37ec4091950d92768225be17", "indicators": { "master_is_stable": { "status": "green", "symptom": "集群拥有稳定的主节点", "details": { "current_master": { "node_id": "inOUckScRGqxuiw8i7E41w", "name": "instance-0000000001" }, "recent_masters": [ { "node_id": "inOUckScRGqxuiw8i7E41w", "name": "instance-0000000001" } ] } }, "repository_integrity": { "status": "green", "symptom": "未发现损坏的快照仓库", "details": { "total_repositories": 1 } }, "shards_availability": { "status": "red", "symptom": "集群有1个不可用的主分片，1个不可用的副本分片", "details": { "creating_primaries": 0, "unassigned_replicas": 1, "restarting_primaries": 0, "restarting_replicas": 0, "initializing_primaries": 0, "started_replicas": 89, "initializing_replicas": 0, "unassigned_primaries": 1, "started_primaries": 89 }, "impacts": [ { "id": "elasticsearch:health:shards_availability:impact:primary_unassigned", "severity": 1, "description": "无法向1个索引[my-index-000001]添加数据，搜索可能会返回不完整的结果", "impact_areas": [ "数据摄入", "搜索" ] }], "diagnosis": [ { "id": "elasticsearch:health:shards_availability:diagnosis:enable_index_allocations", "cause": "Elasticsearch被禁止为这些索引的某些分片进行分配，因为这些分片的分配已在索引级别被禁用", "action": "检查[index.routing.allocation.enable]索引设置是否已设置为[all]", "help_url": "http://ela.st/fix-index-allocation", "affected_resources": { "indices": [ "my-index-000001" ] } }] }, "disk": { "status": "green", "symptom": "集群拥有足够的可用磁盘空间", "details": { "indices_with_readonly_block": 0, "nodes_with_enough_disk_space": 3, "nodes_with_unknown_disk_status": 0, "nodes_over_high_watermark": 0, "nodes_over_flood_stage_watermark": 0 } }, "ilm": { "status": "green", "symptom": "索引生命周期管理正在运行", "details": { "policies": 40, "ilm_status": "RUNNING" } }, "slm": { "status": "green", "symptom": "快照生命周期管理正在运行", "details": { "slm_status": "RUNNING", "policies": 1 } } } }
在此情况下，健康API报告顶级状态为红色，因为分片可用性指标报告了红色状态。症状总结了红色状态的原因，即集群有一个未分配的主分片（集群还有一个未分配的副本分片；但状态为红色是由于主分片未分配）。
由于数据摄入和搜索功能受到直接影响，此健康状况需要立即采取行动以恢复这些功能。让我们检查诊断信息，看看是否能帮助我们解决问题并分配主分片。
原因部分已经提供了一些有用的信息。该索引的分配功能已被禁用。建议的操作是检查 `index.routing.allocation.enable` 设置的值，并将其配置为 `all`。在 `help_url` 键下返回的推荐故障排除指南将提供逐步说明，以检查和配置 `index.routing.allocation.enable` 索引设置的值。
我们可以看到，Health API 提供了对诊断条件的详细解释以及修复系统的逐步指南。诊断和详细信息之所以被计算并返回，是因为 `verbose` 参数的默认值为 `true`（我们只需执行了 `GET _health_report`）。同样，我们不建议在任何潜在的自动化或 API 轮询中使用 API 的详细版本，因为计算诊断可能会耗费大量资源。
让我们看看在未启用详细模式时 API 的输出结果：
GET _health_report?verbose=false
{ "status": "red", "cluster_name": "d529cccc37ec4091950d92768225be17", "indicators": { "master_is_stable": { "status": "green", "symptom": "集群拥有稳定的主节点" }, "repository_integrity": { "status": "green", "symptom": "没有损坏的快照仓库。" }, "shards_availability": { "status": "red", "symptom": "此集群有 1 个不可用的主分片，1 个不可用的副本分片。", "impacts": [ { "id": "elasticsearch:health:shards_availability:impact:primary_unassigned", "severity": 1, "description": "无法向 1 个索引 [my-index-000001] 添加数据。搜索可能会返回不完整的结果。", "impact_areas": [ "ingest", "search" ] }] }, "disk": { "status": "green", "symptom": "集群拥有足够的可用磁盘空间。" }, "ilm": { "status": "green", "symptom": "索引生命周期管理正在运行" }, "slm": { "status": "green", "symptom": "快照生命周期管理正在运行" } } }
即使这个简洁版本的 API 也能提供系统当前状态的深刻见解。`status`、`symptom` 和 `impacts` 字段共同提供了健康问题的总体概览以及立即受影响的区域/功能。
## 应用场景
Elastic 已经在 Elastic Cloud 中使用了 Health API。你可能已经见过“健康”页面，该页面由 Health API 支撑。健康页面首先显示部署健康状况的概览，并由非详细模式的健康 API 提供支持：
点击关键问题描述文本将调用 Health API 的详细模式（即 `GET _health_report?verbose=true`）以执行根本原因分析，并获取恢复绿色健康状态的步骤（即“处方”）：
每个诊断和影响都有一个在 `id` 字段中返回的标识符。这些标识符可用于记录部署中遇到的健康状况，或分析受影响最严重的区域。
此外，诊断 ID 可用于驱动“修复我”功能，其中返回的故障排除指南（`diagnosis.help_url`）中描述的必要步骤将自动执行每个受影响的资源（`diagnosis.affected_resource`）。
下次你遇到 Elasticsearch 集群问题时，请查看 Health API 以了解问题的影响、诊断和修复步骤。
祝你的部署一切顺利！
## 分享