observability-service-health

APM 服务健康状况

使用可观测性 API、针对 APM 索引的 ES|QL、Elasticsearch API，以及（用于关联分析和 APM 特定逻辑）Kibana 仓库，评估 APM 服务健康状况。使用 SLO、触发中的告警、ML 异常、吞吐量、延迟（平均值/p95/p99）、错误率和依赖项健康状况。

查看位置

• 可观测性 API（可观测性 API）：使用 SLO API（Stack | Serverless）获取 SLO 定义、状态、消耗速率 和错误预算。使用告警 API （Stack | Serverless）列出和管理服务的告警规则及其告警。需要时，使用 APM annotations API 创建或搜索注释。
• ES|QL 和 Elasticsearch： 使用 ES|QL 查询 traces*apm*,traces*otel* 和 metrics*apm*,metrics*otel*（参见 使用 ES|QL 查询 APM 指标），以进行吞吐量、延迟、错误率和依赖关系类聚合。按 Elasticsearch 仓库中的说明使用 Elasticsearch API（例如，使用 POST _query 执行 ES|QL，或使用 Query DSL）查询索引和搜索。
• APM 关联分析： 运行 apm-correlations 脚本，获取与指定服务的高延迟或失败事务相关联的属性。该脚本会先尝试 Kibana 内部的 APM 关联分析 API，然后回退到针对 traces*apm*,traces*otel* 执行 Elasticsearch significant_terms 查询。参见 APM Correlations 脚本。
• 基础设施： 通过跟踪中的资源属性（例如 k8s.pod.name、container.id、host.name）进行关联；使用 ES|QL/Elasticsearch 查询基础设施或指标索引，查看 CPU 和内存。OOM 和 CPU 限流会直接影响 APM 健康状况。
• 日志： 使用 ES|QL 或 Elasticsearch 搜索日志索引，并通过 service.name 或 trace.id 进行筛选，以解释行为和根本原因。
• Observability Labs： 查看 Observability Labs 和 APM 标签，了解相关模式和故障排查方法。

健康状况标准

在以下信号可用时，综合评估健康状况：

信号	检查内容
SLO	消耗速率、状态（健康/降级/违反）和错误预算。
触发中的告警	服务或依赖项当前打开或最近触发的告警。
ML 异常	异常检测任务；延迟、吞吐量或错误率的分数和严重程度。
吞吐量	请求速率；与基线或上一时段进行比较。
延迟	平均值、p95、p99；与 SLO 目标或历史数据进行比较。
错误率	失败请求数/总请求数；是否出现峰值或持续升高。
依赖项健康状况	下游延迟、错误率、可用性（ES|QL、API、Kibana 仓库）。
基础设施	CPU 使用率、内存；Pod/容器/主机是否发生 OOM 和 CPU 限流。
日志	按服务或跟踪 ID 筛选的应用日志，用于了解上下文和根本原因。

如果 SLO 被违反、关键告警正在触发，或 ML 异常表明出现严重降级，则将服务视为不健康。结合基础设施（OOM、CPU 限流）、依赖项和日志（服务/跟踪上下文）进行关联分析，以说明_原因_并提出后续步骤。

使用 ES|QL 查询 APM 指标

从 Elasticsearch 查询 APM 数据（traces*apm*,traces*otel*、metrics*apm*,metrics*otel*）时，在可用的情况下，默认使用 ES|QL。

• 可用性： Elasticsearch 8.11+ 提供 ES|QL（技术预览版；8.14 起正式发布）。Elastic Observability Serverless Complete tier 始终提供 ES|QL。
• 限定服务范围： 始终按 service.name 筛选（并在相关时按 service.environment 筛选）。同时按 @timestamp 限定时间范围：

WHERE service.name == "my-service-name" AND service.environment == "production"
  AND @timestamp >= "2025-03-01T00:00:00Z" AND @timestamp <= "2025-03-01T23:59:59Z"

• 示例模式： 随时间变化的吞吐量、延迟和错误率：参见 Kibana trace_charts_definition.ts（getThroughputChart、getLatencyChart、getErrorRateChart）。使用 from(index) → where(...) → stats(...) / evaluate(...)，并搭配 BUCKET(@timestamp, ...) 和 WHERE service.name == "<service_name>"。
• 性能： 添加 LIMIT n 以限制行数和令牌用量。仅需查看趋势时，优先使用较粗的 BUCKET(@timestamp, ...)（例如 1 小时）；更细的时间桶会增加工作量和结果大小。

APM Correlations 脚本

如果只有一部分事务出现高延迟或失败，请运行 apm-correlations 脚本，列出与这些事务相关的属性（例如主机、服务版本、Pod、区域）。该脚本会先尝试调用 Kibana 内部的 APM correlations API；如果不可用（例如返回 404），则回退到 Elasticsearch 的 significant_terms，查询 traces*apm*,traces*otel*。

# Latency correlations (attributes over-represented in slow transactions)
node skills/observability/service-health/scripts/apm-correlations.js latency-correlations --service-name <name> [--start <iso>] [--end <iso>] [--last-minutes 60] [--transaction-type <t>] [--transaction-name <n>] [--space <id>] [--json]

# Failed transaction correlations
node skills/observability/service-health/scripts/apm-correlations.js failed-correlations --service-name <name> [--start <iso>] [--end <iso>] [--last-minutes 60] [--transaction-type <t>] [--transaction-name <n>] [--space <id>] [--json]

# Test Kibana connection
node skills/observability/service-health/scripts/apm-correlations.js test [--space <id>]

环境变量： Kibana 使用 KIBANA_URL 和 KIBANA_API_KEY（或 KIBANA_USERNAME/KIBANA_PASSWORD）；回退查询使用 ELASTICSEARCH_URL 和 ELASTICSEARCH_API_KEY。使用与调查相同的时间范围。

工作流

Service health progress:
- [ ] Step 1: Identify the service (and time range)
- [ ] Step 2: Check SLOs and firing alerts
- [ ] Step 3: Check ML anomalies (if configured)
- [ ] Step 4: Review throughput, latency (avg/p95/p99), error rate
- [ ] Step 5: Assess dependency health (ES|QL/APIs / Kibana repo)
- [ ] Step 6: Correlate with infrastructure and logs
- [ ] Step 7: Summarize health and recommend actions

步骤 1：确定服务

确认服务名称和时间范围。根据请求确定服务；如果涉及多个服务，则选择最相关的服务。使用 ES|QL 查询 traces*apm*,traces*otel* 或 metrics*apm*,metrics*otel*（例如 WHERE service.name == "<name>"），或使用 Kibana 仓库中的 APM 路由获取服务级数据。如果用户未提供时间范围，则假设为最近 1 小时。

步骤 2：检查 SLO 和触发中的告警

SLO： 调用 SLOs API，获取该服务的 SLO 定义和状态（延迟、可用性），包括健康、退化或违反状态、消耗速率和错误预算。告警： 对于活动的 APM 告警，调用 /api/alerting/rules/_find?search=apm&search_fields=tags&per_page=100&filter=alert.attributes.executionStatus.status:active。 检查单个服务时，同时包含 params.serviceName 与该服务匹配的规则，以及未设置 params.serviceName 的规则（适用于所有服务的规则）。检查活动状态时，不要查询 .alerts* 索引。结合 SLO 违反情况或指标变化进行分析。

步骤 3：检查 ML 异常

如果使用了 ML 异常检测，则通过 Elasticsearch ML API 或索引查询该服务和时间范围内的 ML 作业结果或异常记录。记录高严重性异常（延迟、吞吐量、错误率）；使用异常时间窗口缩小步骤 4–5 的调查范围。

步骤 4：查看吞吐量、延迟和错误率

针对该服务和时间范围，使用 ES|QL 查询 traces*apm*,traces*otel* 或 metrics*apm*,metrics*otel*，获取吞吐量（例如，每分钟请求数）、延迟（平均值、p95、p99）和错误率（失败数/总数或 5xx 数/总数）。示例： FROM traces*apm*,traces*otel* | WHERE service.name == "<service_name>" AND @timestamp >= ... AND @timestamp <= ... | STATS ...。 与上一时段或 SLO 目标进行比较。参见使用 ES|QL 查询 APM 指标。

步骤 5：评估依赖健康状况

通过 traces*apm*,traces*otel*/metrics*apm*,metrics*otel* 上的 ES|QL（例如，下游服务/Span 聚合）获取依赖和服务映射数据，或通过 Kibana 仓库中公开依赖/服务映射数据的 APM 路由处理程序获取。对于相应服务和时间范围，记录下游延迟和错误率；将缓慢或故障的依赖标记为可能原因。

步骤 6：与基础设施和日志关联

• APM 相关性分析（仅当部分用户群受到影响时）： 运行 node skills/observability/service-health/scripts/apm-correlations.js latency-correlations|failed-correlations --service-name <name> [--start ...] [--end ...] 获取相关属性。按这些属性筛选，并获取跟踪样本或错误以确认根本原因。参见 APM 相关性分析脚本。
• 基础设施： 使用跟踪中的资源属性（例如 k8s.pod.name、container.id、host.name），并通过 ES|QL 或 Elasticsearch 查询基础设施/指标索引中的 CPU 和内存。OOM 和 CPU 限流会直接影响 APM 健康状况；将它们发生的时间段与 APM 性能下降情况关联起来。
• 日志： 使用日志索引上的 ES|QL 或 Elasticsearch，通过 service.name == "<service_name>" 或 trace.id == "<trace_id>" 查询，以解释行为和根本原因（异常、超时、重启）。

步骤 7：总结并提出建议

说明健康状况（健康 / 性能下降 / 不健康）及原因；列出具体的后续步骤。

示例

示例：针对特定服务运行 ES|QL

使用 WHERE service.name == "<service_name>" 和时间范围限定查询。吞吐量和错误率（按 1 小时分桶；LIMIT 用于限制行数和 Token 数量）：

FROM traces*apm*,traces*otel*
| WHERE service.name == "api-gateway"
  AND @timestamp >= "2025-03-01T00:00:00Z" AND @timestamp <= "2025-03-01T23:59:59Z"
| STATS request_count = COUNT(*), failures = COUNT(*) WHERE event.outcome == "failure" BY BUCKET(@timestamp, 1 hour)
| EVAL error_rate = failures / request_count
| SORT @timestamp
| LIMIT 500

延迟百分位数和确切字段名称：参见 Kibana trace_charts_definition.ts。

示例：“服务 X 是否健康？”

1. 确定服务 X 和时间范围。调用 SLO API 和 告警 API；在 traces*apm*,traces*otel*/metrics*apm*,metrics*otel* 上运行 ES|QL，查询吞吐量、延迟和错误率；查询 依赖/服务映射数据（通过 ES|QL 或 Kibana 仓库）。
2. 评估 SLO 状态（是否违规/性能下降？）、正在触发的规则、ML 异常和依赖健康状况。
3. 给出答复：健康 / 性能下降 / 不健康，并说明原因和后续步骤（例如， Observability Labs）。

示例：“服务 Y 为什么这么慢？”

1. 确定服务 Y 和响应缓慢的时间范围。调用 SLO API 和 告警 API；对 Y 及其依赖运行 ES|QL； 查询 ML 异常结果。
2. 通过 ES|QL 将延迟（平均值/p95/p99）与前一时间段进行比较；根据依赖数据找出延迟高或发生故障的依赖。
3. 总结（例如，p99 升高；依赖 Z 延迟升高）并提出建议（调查 Z；使用 Observability Labs 排查延迟）。

示例：将服务与基础设施关联（OpenTelemetry）

使用 Span/跟踪中的资源属性，获取服务对应的运行环境（Pod、容器、主机）。然后，在与 APM 问题相同的时间范围内检查这些资源的 CPU 和内存：

• 从服务的跟踪或指标中读取资源属性，例如 k8s.pod.name、k8s.namespace.name、 container.id 或 host.name。
• 使用这些资源值和事故时间范围作为筛选条件，通过 ES|QL 或 Elasticsearch 搜索基础设施/指标索引。检查 CPU 使用率和内存消耗（例如 system.cpu.total.norm.pct）；查找与 APM 延迟或错误率激增时间相吻合的 OOMKilled 事件、CPU 限流，或持续偏高的 CPU/内存占用。

示例：按服务或跟踪 ID 筛选日志

要了解特定服务或单个跟踪的行为，请相应地筛选日志：

• 按服务筛选： 在日志索引上运行 ES|QL 或 Elasticsearch 搜索，使用 service.name == "<service_name>" 和时间范围获取服务上下文中的应用日志（错误、警告、重启）。
• 按跟踪 ID 筛选： 调查特定请求时，从 APM 跟踪中获取 trace.id，并按 trace.id == "<trace_id>"（或日志架构中的等效字段）筛选日志。包含该跟踪 ID 的日志会显示完整的请求路径，并有助于解释故障或延迟。

指南

• 使用 Observability API（SLO API、Alerting API）以及对 traces*apm*,traces*otel*/metrics*apm*,metrics*otel* 使用 ES|QL（8.11+ 或 Serverless），并按 service.name（以及相关时的 service.environment）筛选。要查找活跃的 APM 告警，请调用 /api/alerting/rules/_find?search=apm&search_fields=tags&per_page=100&filter=alert.attributes.executionStatus.status:active。检查单个服务时，请评估两种规则类型：params.serviceName 与目标服务匹配的规则，以及缺少 params.serviceName 的规则（适用于所有服务）。在判定服务健康状况之前，应将这两种规则都视为适用于该服务。确定当前活跃的告警时，请勿查询 .alerts* 索引；应以上述 Alerting API 响应为准。对于 APM 关联分析，请运行 apm-correlations 脚本（见 APM Correlations 脚本）；对于依赖项/服务映射数据，请使用 ES|QL 或 Kibana 仓库路由处理程序。有关 Elasticsearch 索引和搜索行为，请参阅 Elasticsearch 仓库中的 Elasticsearch API。
• 始终使用用户指定的时间范围；如果问题发生在过去，请勿假设时间范围为“最近 1 小时”。
• 如果存在 SLO，请以 SLO 状态和消耗速率为健康摘要的依据；如果不存在，则依据告警、异常、吞吐量、延迟、错误率和依赖项。
• 仅分析通过 OpenTelemetry 摄取的应用指标时，请使用 ES|QL TS（时间序列）命令高效查询指标。TS 命令在 Elasticsearch 9.3+ 中可用，并且在 Elastic Observability Serverless 中始终可用。
• 摘要：用一句简短的话给出健康结论，并用项目符号列出证据和后续步骤。