作者：来自 Elastic Jeffrey Rengifo
Elastic 集成提供告警规则模板，每个模板都是一个已经设置阈值的 ES|QL 查询。你可以在几分钟内创建 Elasticsearch 告警规则，根据你的流量进行调整，并提前发现无声的数据流。
NGINX OpenTelemetry Assets 集成提供 6 个告警规则模板。每个模板都是一个已经调优阈值的 ES|QL 查询。安装该集成后，你可以从其中一个模板创建规则，并调整阈值以匹配你的流量。这样，你可以在几分钟内获得可用的告警，而无需从头编写规则。本教程涵盖完整设置、阈值调优，以及如何使用空闲数据流规则来发现停止发送数据的服务。
Elastic 集成告警规则模板的前提条件
Elastic Stack 9.4.0 或更高版本。
告警规则模板从 9.2.1 开始提供，位于集成 Assets 标签页下。本文介绍了三个需要 9.4.0 的功能：专用的 Alerting 标签页、空闲数据流规则，以及处于技术预览阶段的 NGINX OpenTelemetry Assets 软件包。
步骤 1：使用 OpenTelemetry 将 NGINX 日志和指标发送到 Elasticsearch
首先，将 NGINX 指标和日志发送到 Elasticsearch。
启用 NGINX stub_status 模块，并确保采集器可以读取访问日志和错误日志。然后，配置 EDOT 或上游 OpenTelemetry Collector，使用 nginx 和 filelog 接收器，将指标和日志导出到 Elasticsearch。
集成设置中包含完整的接收器和管道配置。
如果你想复现此示例，可以使用配套代码仓库。
两 类 信号对于告警都很重要，并且每组模板读取不同的数据流：
- 基于日志的模板（4xx 和 5xx 错误率、错误日志峰值）查询 logs-nginx.access.otel-* 和 logs-nginx.error.otel-*，这些数据流来自 filelog 接收器。
- 基于指标的模板（活动连接数、丢弃连接数）查询 metrics-nginxreceiver.otel-*，这些数据流来自 nginx 接收器。
这里很容易出错：Fleet Nginx（OpenTelemetry）输入软件包只收集 stub_status 指标。它对应的日志集成是经典 Nginx 集成，该集成写入基于 ECS 的 nginx.access 和 nginx.error 数据集，而不是日志模板所查询的 .otel- 数据流。如果你只依赖这一组合，基于日志的规则将没有任何数据可评估，并且会静默地永远不会触发。请同时运行 filelog 接收器，而不仅仅是 nginx 接收器。
步骤 2：安装 NGINX OpenTelemetry Assets 集成
NGINX OpenTelemetry Assets 是一个仅包含内容的软件包。它提供仪表板、告警规则模板和 SLO 模板，但自身不会采集数据。数据来自你在步骤 1 中设置的采集器。
你无需手动安装它。当步骤 1 中的 NGINX OTel 数据开始到达后，Elastic 会检测到这些数据，并自动为你安装 Assets 软件包，这通常需要一到两分钟。在管理 > 集成 > 已安装集成中确认，那里应该会显示 NGINX OpenTelemetry Assets。
步骤 3：根据规则模板创建 Elasticsearch 告警规则
打开该集成并选择 Alerting 标签页。
该软件包提供 6 个模板：高 4xx 和 5xx 错误率、高活动连接数、错误日志峰值、丢弃连接数，以及一个通用的"按服务统计的高错误率"模板。该通用模板指向一个占位符索引 logs-myservicereceiver.otel-*，你可以重新指定目标索引并重命名。
其中 5 个 NGINX 规则每分钟运行一次 ES|QL，并根据 host.name 对结果进行分组，因此告警会指出出现问题的主机。通用模板则根据 service.name 进行分组，因为它的设计目标是重新指定到你选择的任意服务。
选择一个模板，例如 [Nginx OTel] High 5xx error rate。Kibana 会打开一个预填充的基于 Elasticsearch 查询规则的创建规则表单。它会按照计划运行模板中的 ES|QL，并在查询返回结果行时触发告警。
查询如下：
scss
`
1. FROM logs-nginx.access.otel-*
2. // Flag each access log entry as a server error (5xx) or not
3. | EVAL is_5xx = CASE(http.response.status_code >= 500, 1, 0)
4. // Aggregate total requests and 5xx count per NGINX host
5. | STATS total = COUNT(*), errors_5xx = SUM(is_5xx) BY host.name
6. // Minimum sample size to avoid noisy low-traffic hosts
7. | WHERE total > 50
8. // Calculate 5xx error rate as a percentage
9. | EVAL error_rate_pct = ROUND(TO_DOUBLE(errors_5xx) / TO_DOUBLE(total) * 100.0, 2)
10. // Alert threshold: adjust to tune sensitivity
11. | WHERE error_rate_pct > 5.0
12. | SORT error_rate_pct DESC
13. | LIMIT 10
`AI写代码它会统计每个主机的请求数量和 5xx 响应数量，保留具有足够流量的重要主机，并返回错误率超过 5% 的主机。
在表单打开期间，需要注意以下三点：
- 首先发送数据 。ES|QL 会根据查询运行时已存在的索引验证列名。在任何 NGINX 数据被采集之前打开模板，编辑器会报告
Unknown column "http.response.status_code"，并且表单会显示错误。一旦数据开始流入（步骤 1），同一个查询就会通过验证，错误也会消失，因此请先采集数据，再创建规则。 - 将时间字段设置为
@timestamp。 - 保持选择 "为每一行创建一个告警"（Create an alert for each row）。由于查询根据
host.name进行分组，这会让每个受影响的主机分别触发自己的告警。
添加一个连接器和一个操作，使告警能够发送到 Slack、电子邮件或 PagerDuty，然后保存并启用该规则。
步骤 4：在 ES|QL 中调整告警规则模板阈值
这些阈值只是起始值，因此需要根据你自己的流量情况进行确认。阈值位于 ES|QL 的 WHERE 子句中。
要使规则更加严格，将 error_rate_pct > 5.0 修改为 error_rate_pct > 2.0。如果希望在触发前要求更多流量，则提高 total > 50 的值。在保存之前，使用规则表单中的"测试查询"（Test query）确认修改后的查询能够解析并返回结果行。
还有三个设置值得关注：
- 时间窗口：查询运行时回溯的时间范围。较短的窗口响应更快，但在突发流量情况下会产生更多噪声。
- 规则计划：查询运行的频率，默认每分钟运行一次。
- 告警延迟：在创建告警之前，条件必须连续满足的运行次数，用于过滤单次运行中的短暂异常。
如何在 Elasticsearch 中检测空闲数据流？
阈值规则只有在数据持续到达时才会触发。当某个 agent 离线或输出出现故障时，数据会停止，阈值规则就没有可评估的内容。
许多 Elastic 集成都包含一个针对这种情况动态生成的空闲数据流模板。它名为 [{Integration name}] [Idle data streams](https://www.elastic.co/docs/reference/fleet/alerting-rule-templates "Idle data streams")，会出现在相同的 Alerting 标签页中，不过它是自动生成的，而不是集成中打包提供的。当在设定时间段内没有数据写入该集成的数据流模式时，它会触发告警。
NGINX OpenTelemetry 软件包不包含空闲数据流模板，因此在步骤 3 的 Alerting 标签页中不会看到此类模板。本节末尾会介绍替代方案。
默认时间周期为 24 小时，这通常太长。生产服务可能大半天都处于静默状态，而你仍然无法及时发现。
创建规则时，将周期缩短到符合你所需响应速度的范围。对于关键服务，15 分钟到 1 小时通常比较合适。对于批处理任务，将周期设置为明显长于其运行间隔的时间，这样任务运行之间的空闲间隔不会触发告警。
那么为什么这个示例没有包含它？该模板是根据集成定义的数据流模式生成的，并且不会为仅输入类型的软件包生成。像 NGINX OpenTelemetry Assets 这样的仅内容软件包也不会定义自己的数据流。要在这样的基于采集器的设置中检测数据停止，需要手动使用 Elasticsearch 查询规则重新创建该规则。使用查询 DSL 或 KQL 版本，而不是 ES|QL，因为 ES|QL 规则会在返回结果行时触发，而无法针对数据不存在的情况发出告警。
将规则指向 OTel 数据流（logs-nginx.access.otel-* 或 metrics-nginxreceiver.otel-*），并将触发条件设置为：在例如最近 15 分钟的时间窗口内，匹配文档数量低于 1 时触发。这样就能复现空闲数据流模板的行为，并将范围限定在采集器写入的数据流上。
开始使用 Elastic 集成告警规则模板
告警规则模板将告警配置简化为几个步骤：发送数据、安装集成、根据模板创建规则，以及调整阈值。应将内置阈值视为需要确认的默认值，而不是可以盲目信任的数字。如果存在空闲数据流模板，应降低其默认的 24 小时时间周期，以便在服务停止发送数据时快速发现。
资源
-
配套代码仓库，用于生成本文使用的 NGINX 示例数据
-
Elastic Agent 内置告警，用于监控 agent 自身
原文：Alerting rule templates in Elastic integrations --- Elastic Observability Labs