日志警报的工作原理托管的计划查询生命周期日志报警配置日志查询聚合表达式多贡献者警报缺失数据处理评估状态警报更新操作和通知最佳实践和故障排除

日志警报

日志警报监控使用计划查询按计划运行的 CloudWatch Logs Insights 查询的结果。该警报将聚合表达式应用于查询结果以生成数值，当该聚合值违反配置的阈值时，警报将转换为 ALARM 状态并运行配置的操作。

与需要指标筛选条件作为中间步骤的指标警报不同，日志警报直接使用用于临时分析的相同 Logs Insights 查询语言对日志数据进行评估。

日志警报的工作原理

以下步骤介绍了日志警报的工作原理：

您可以通过查询、聚合表达式、计划和阈值创建日志警报。
CloudWatch 会自动创建一个 AWS 托管的计划查询，该查询会按照指定的计划运行查询。
每次查询执行都会产生聚合结果（单个值或多个贡献值）。
CloudWatch 对最近的查询执行使用 M-out-of-N 评估来根据阈值评估聚合结果。
如果违反阈值，警报将转换为 ALARM 状态并运行配置的操作（如 Amazon SNS 通知）。

注意

日志警报会评估最近 N 次查询执行。当这 N 次执行中有 M 次违反阈值时，警报会转换为 ALARM。

要创建日志警报，请参阅创建日志警报。

托管的计划查询生命周期

当您创建日志警报时，CloudWatch 会自动创建一个 AWS 托管的计划查询，该查询会按照指定的计划运行查询。不需要单独创建计划查询

AWS 托管的计划查询具有以下特征：

它在 CloudWatch Logs 控制台的“计划查询”下可见。
不能直接修改它。要更改查询或其配置，请更新日志警报。
当您删除警报时，CloudWatch 会删除 AWS 托管的计划查询。

日志报警配置

日志报警配置了以下参数：

QueryString 是要运行的 CloudWatch Logs Insights 查询。
LogGroupIdentifiers 是要查询的日志组。请指定日志组名称或日志组 ARN。
ScheduledQueryRoleARN 是 IAM 角色的 ARN，该角色允许 CloudWatch Logs 代表您运行计划查询。
AggregationExpression 定义如何将查询结果聚合为数值以进行阈值评估。
ScheduleExpression 定义查询的运行频率（如 rate(5 minutes)）。
StartTimeOffset 定义每次执行查询的回溯窗口（以秒为单位）。
EndTimeOffset 将查询时间范围的结束定义为与当前时间的偏移量（以秒为单位）。
ComparisonOperator 是将聚合结果与阈值进行比较的方式。有效值：GreaterThanThreshold、GreaterThanOrEqualToThreshold、LessThanThreshold、LessThanOrEqualToThreshold。
Threshold 是要比较的数值。
QueryResultsToEvaluate 是要评估的最近查询执行次数（M-out-of-N 中的 N）。
QueryResultsToAlarm 是触发 ALARM 所需的违规结果数（M-out-of-N 中的 M）。
TreatMissingData 定义评估期间如何处理缺失的查询结果。

有关参数和创建说明的完整列表，请参阅创建日志警报。

日志查询

日志警报查询是一个 CloudWatch Logs Insights 查询，其会选择和筛选要评估的日志数据。该查询在 LogGroupIdentifiers 中指定的日志组上运行，时间范围由 StartTimeOffset 和 EndTimeOffset 定义。

该查询使用 CloudWatch Logs Insights 查询语法。有关为日志警报编写高效查询的指南，请参阅最佳实践和故障排除。

聚合表达式

聚合表达式定义 CloudWatch 如何将查询结果汇总为数值以进行阈值评估。该表达式使用与 CloudWatch Logs Insights 中的 stats 命令相同的语法。

聚合表达式的语法如下：


statistic_func_expression [by field1, field2, ...] [| sort asc|desc]

只能指定一个聚合表达式。下表列出了支持的聚合函数。

支持的聚合函数
函数	说明	示例
`count(*)`	所有匹配日志行的计数。	`count(*)`
`avg(field)`	指定字段的平均值。	`avg(duration)`
`sum(field)`	指定字段的总和。	`sum(bytesSent)`
`min(field)`	指定字段的最小值。	`min(latency)`
`max(field)`	指定字段的最大值。	`max(latency)`

bin() 函数在聚合表达式的 by 子句中不受支持。但是，您可以在查询字符串本身中使用 bin()。

多贡献者警报

当您在聚合表达式中包含 by 子句时，警报会独立评估字段值的每个唯一组合（称为贡献者）。如果任何贡献者违反了阈值，警报将转换为 ALARM 状态。

例如，下面的表达式按服务名称对错误计数进行分组：


count(*) by serviceName

serviceName 的每个唯一值都会根据阈值独立进行评估。如果任何服务在 N 次查询执行中的 M 次超过阈值，则警报会进入 ALARM 状态。

下面的限制适用于多贡献者警报：

by 子句中最多 5 个字段。
每次查询执行最多返回 500 个贡献者结果。
最多同时跟踪 100 个处于 ALARM 状态的贡献者。

默认情况下，贡献者按字母顺序排序，每次查询执行仅返回前 500 个。要改为按聚合值对贡献者进行排序，请在聚合表达式中指定 | sort asc 或 | sort desc（如 avg(latency) by serviceName | sort desc）。当总数超过 500 时，基于值的排序可确保首先评估最重要的贡献者。

对于多贡献者警报，Amazon SNS 和 Lambda 操作在贡献者级别运行（每个违规贡献者一次）。Systems Manager OpsItem 操作在警报级别运行。

注意

日志警报不支持 Systems Manager Incident Manager 和调查操作。

如果某个贡献者从查询结果中消失（例如，临时资源被终止），则无论缺失数据处理设置如何，该贡献者都会转换为 OK 状态。

缺失数据处理

当计划的查询执行没有产生可以根据阈值进行评估的值时，就会发生数据丢失。这发生在以下情况下：

不存在日志：日志组在查询时间范围内不包含任何日志事件。

查询未返回任何适用结果：存在日志，但聚合表达式无法产生值。以下情况下会发生这种情形：

根据查询筛选条件，不存在匹配的查询结果。
聚合表达式中引用的字段在查询结果中不存在。例如 count(error-codes)，其中 error-codes 不存在于返回的日志事件中。

请注意，对空结果集执行 count(*) 会返回 0，这是一个有效的数据点，不会被视为缺失。

您可以使用 TreatMissingData 参数配置警报如何处理缺失数据。下表介绍了可用选项。

缺失数据处理选项
值	行为
`missing`	将数据点视为缺失。这是默认值。
`notBreaching`	将缺失的数据点视为未违反阈值。
`breaching`	将缺失的数据点视为违反阈值。
`ignore`	忽略缺失的数据点，仅评估可用数据。

评估状态

除了标准 OK、ALARM 和 INSUFFICIENT_DATA 状态外，日志警报还可以在 EvaluationState 字段中报告以下评估状态。这些状态提供有关警报为何处于当前状态的更多背景信息。

日志警报评估状态
州	说明
`EVALUATION_FAILURE`	暂时的 CloudWatch 服务问题导致无法进行评估。当服务因服务错误而在评估查询结果时遇到问题，或者当部分（但不是全部）查询结果失败时，就会发生这种情况。警报会转换为 `INSUFFICIENT_DATA`。我们建议手动监控，直到问题得到解决。
`EVALUATION_ERROR`	客户端配置错误导致无法进行评估。这可能是由于权限不足、查询无效或所有查询结果均失败造成的。警报会立即转换为 `INSUFFICIENT_DATA`。有关详细信息，请参阅 `StateReason` 字段。
`PARTIAL_DATA`	查询返回了最多 500 个贡献者组，但匹配的组更多。警报会评估可用的贡献者，但结果可能不完整。

警报更新

当您更新日志警报的查询、聚合表达式、计划或日志组时，警报会转换为 INSUFFICIENT_DATA，直到收集到足够的新数据点。更改阈值或 M-out-of-N 值不会触发此重置。

操作和通知

日志警报支持以下操作：

Amazon SNS 通知
Lambda 函数调用
Systems Manager OpsItem 创建

有关完整的操作支持矩阵，请参阅警报操作。

当日志警报转换状态时，操作通知包含下面的信息：

标准警报配置更改信息（警报名称、描述、配置详细信息）。
状态更改信息（新状态、状态原因、时间戳）。
Amazon SNS 电子邮件通知还包括指向 CloudWatch Logs Insights 控制台的深度链接，其中显示了完整的查询结果。

以下示例显示了单值日志警报（不含 BY 子句）的 Amazon SNS 电子邮件通知：


{
    "AlarmName": "HighErrorCount",
    "NewStateValue": "ALARM",
    "NewStateReason": "Threshold Crossed: 3 out of the last 5 query results [142.0 (10/06/26 12:15:00), 135.0 (10/06/26 12:10:00), 120.0 (10/06/26 12:05:00)] were greater than the threshold (100.0) (minimum 3 datapoints for OK -> ALARM transition).",
    "NewStateReasonData": {
        "version": "1.0",
        "queryDate": "2026-06-10T12:15:30.000+0000",
        "threshold": 100.0,
        "queryResultsToEvaluate": 5,
        "queryResultsToAlarm": 3,
        "results": [
            {
                "queryResultId": "scheduled-query-execution-id-3",
                "status": "COMPLETE",
                "timestamp": "2026-06-10T12:15:00.000+0000",
                "value": 142.0
            }
            // Additional results...
        ]
    },
    "StateChangeTime": "2026-06-10T12:15:30.000+0000",
    "OldStateValue": "OK"
    // Additional fields...
}

以下示例显示了多贡献者日志警报（含 BY 子句）的 Amazon SNS 电子邮件通知。每个违规贡献者都会生成一条单独的通知：


{
    "AlarmName": "EndpointLatency",
    "NewStateValue": "ALARM",
    "NewStateReason": "5 out of 10 contributors evaluated to ALARM",
    "StateChangeTime": "2026-06-10T12:20:15.000+0000",
    "OldStateValue": "OK",
    "AlarmContributorId": "a1b2c3d4e5f6g7h8",
    "AlarmContributorAttributes": {
        "endpoint": "/api/orders"
    }
    // Additional fields...
}

在通知中包括日志行

您可以通过将 ActionLogLineCount 参数设置为 1 到 50 之间的值，选择性地将原始查询结果日志行包括在警报通知中。这些是用于评估聚合表达式的底层日志事件，而不是聚合值。默认值为 0，意味着不包括任何日志行。

注意

日志行仅包括在 Amazon SNS 电子邮件通知中。Lambda 操作在其有效载荷中不包括日志行。

重要

在通知中包括日志行可能会在 Amazon SNS 消息中暴露日志中的敏感数据。启用此功能之前，请先查看日志内容。

要包括日志行，日志行角色必须具有 logs:GetQueryResults 权限。通知中包括的日志行数受请求计数、可用结果总数和 Amazon SNS 有效载荷大小限制的约束。

最佳实践和故障排除

最佳实践

查询优化

在将查询用于日志警报之前，请先在 CloudWatch Logs Insights 中手动测试查询，以验证其性能和预期结果。
在查询的早期使用筛选命令以减少处理的数据量。
限制查询时间范围（StartTimeOffset）以避免大量日志组超时。
使用字段索引来优化查询性能。

计划规划

选择一个允许查询在下次执行之前完成的计划频率。对于大量日志组，请使用更长的间隔（例如 10 分钟而不是 5 分钟）。
设置 StartTimeOffset 时，请考虑日志摄取延迟。EndTimeOffset 和当前时间之间的小差距有助于避免评估不完整的数据。
将日志警报计划分散到账户中，以避免达到计划查询并发限制。账户中的并发查询执行次数不能超过 100 次。在创建具有重叠计划的多个日志警报时，请考虑此配额。

阈值调整

从较高的 QueryResultsToEvaluate（N）值开始，以减少瞬态峰值产生的警报噪音。
对于稀疏事件（例如很少发生的错误），请将 TreatMissingData 设置为 notBreaching，以便在没有日志匹配时保持警报处于 OK 状态。
对于连续信号（例如流量日志），请考虑将 TreatMissingData 设置为 breaching，以检测预期日志数据何时停止到达。

多贡献者设计

为 BY 子句选择有意义的字段，这些字段代表要独立监控的不同资源或维度。
请注意，每次查询执行仅返回前 500 个贡献者。如果希望返回更多贡献者，请缩小查询范围或使用更少的 BY 子句字段。
当达到 500 个贡献者限制时，请在聚合表达式中使用 | sort desc 或 | sort asc 后缀，以根据比较运算符优先考虑最高值或最低值。

问题排查

警报停留在 INSUFFICIENT_DATA

可能的原因	解决方案
计划查询执行角色缺少权限	验证角色是否具有 `logs:StartQuery`、`logs:StopQuery`、`logs:GetQueryResults` 和 `logs:DescribeLogGroups` 权限，且范围限于正确的日志组。
日志组不存在或已被删除	验证警报配置中的日志组 ARN 是否正确且可访问。
最近创建或更新的警报	创建或配置更新后，警报将保持在 INSUFFICIENT_DATA 状态，直到完成足够的查询执行以满足 M-out-of-N 评估窗口。
计划查询未运行	在 CloudWatch Logs 控制台中检查 AWS 托管的计划查询，以验证其是否按计划执行。
查询结果中不存在聚合字段	聚合表达式中引用的字段必须存在于查询结果中。例如，如果聚合是 `avg(latency)`，请确保查询生成一个 `latency` 字段。如果该字段不存在，则结果会被视为缺失数据。
日志摄取延迟	计划查询只能评估在其运行之前已摄取的日志事件。`StartTimeOffset` 和 `EndTimeOffset` 定义相对于执行时间 T（T - StartTimeOffset，T - EndTimeOffset）的查询窗口，但它们并未考虑摄取延迟。如果查询的窗口内仍有事件正在被摄取，则查询会在事件可用之前运行并跳过这些事件。使用 `EndTimeOffset` 将窗口向后移动足够远，以便完成整个范围的摄取。例如：假设事件发生后，日志最多需要 2 分钟才能可查询。 `StartTimeOffset=60, EndTimeOffset=0`：窗口 [T−60s, T]。窗口在执行时结束，因此最近的事件尚未被摄取，因而被错过。 `StartTimeOffset=180, EndTimeOffset=120`：窗口 [T−180s, T−120s]。窗口在过去 2 分钟结束，此时所有事件都已被摄取并且可评估。

警报显示 EVALUATION_ERROR

这表明客户端配置存在问题。请查看 StateReason 字段了解详情。常见原因：

查询语法无效或格式错误。
计划查询执行角色的权限不足。
所有查询执行失败（例如，日志组权限已撤销）。

警报显示 EVALUATION_FAILURE

这表明存在暂时性 CloudWatch 服务问题。问题解决后，警报会自动恢复。如果问题持续超过几分钟，请查看 CloudWatch 服务运行状况控制面板。

警报显示 PARTIAL_DATA

查询返回了最多 500 个贡献者组，但匹配的组更多。警报会评估可用的贡献者，但结果可能不完整。请考虑缩小查询范围或减少 BY 子句字段的数量。

通知中未显示日志行

验证 ActionLogLineCount 是否设置为 1 到 50 之间的值。
验证日志行角色是否具有 logs:GetQueryResults 权限且范围限于正确的日志组。
日志行仅包括在 Amazon SNS 电子邮件通知中。其他操作类型不包括日志行。
使用 unmask() 的查询不能在通知中包括日志行（创建时被拒绝）。

有关查询优化、监控和授权的其他最佳实践，请参阅《Amazon CloudWatch Logs 用户指南》中的 Scheduled Queries best practices。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

PromQL 警报

复合警报