企业官网建设流程全解析

AWS CLI 实战：使用 aws cloudwatch describe-alarm-history 查询告警完整历史

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

导读

aws cloudwatch describe-alarm-history是 AWS CLI 中用于检索 Amazon CloudWatch 告警（Alarm）历史记录的专用命令。它能够按告警名称、历史类型、时间范围等条件查询每一次状态变更、配置更新与告警动作，是排查“告警为什么触发/恢复”、审计告警行为、回放监控事件的核心工具。本文以当前仓库 describe-alarm-history.rst 为骨架，结合仓库内 CloudWatch 服务模型 service-2.json 与分页配置 paginators-1.json，完整讲解该命令的参数、输出结构与实战用法，读完即可上手查询并解读任意告警的历史轨迹。

命令概览与最简用法

原示例文档给出的最典型用法是：按告警名称查询，并过滤出“状态更新”类型的历史记录：

aws cloudwatch describe-alarm-history --alarm-name "myalarm" --history-item-type StateUpdate

命令执行后返回 JSON 格式的AlarmHistoryItems数组，每个元素对应一条历史记录。原示例输出如下：

{ "AlarmHistoryItems": [ { "Timestamp": "2014-04-09T18:59:06.442Z", "HistoryItemType": "StateUpdate", "AlarmName": "myalarm", "HistoryData": "{\"version\":\"1.0\",\"oldState\":{\"stateValue\":\"ALARM\",\"stateReason\":\"testing purposes\"},\"newState\":{\"stateValue\":\"OK\",\"stateReason\":\"Threshold Crossed: 2 datapoints were not greater than the threshold (70.0). The most recent datapoints: [38.958, 40.292].\",\"stateReasonData\":{\"version\":\"1.0\",\"queryDate\":\"2014-04-09T18:59:06.419+0000\",\"startDate\":\"2014-04-09T18:44:00.000+0000\",\"statistic\":\"Average\",\"period\":300,\"recentDatapoints\":[38.958,40.292],\"threshold\":70.0}}}", "HistorySummary": "Alarm updated from ALARM to OK" }, { "Timestamp": "2014-04-09T18:59:05.805Z", "HistoryItemType": "StateUpdate", "AlarmName": "myalarm", "HistoryData": "{\"version\":\"1.0\",\"oldState\":{\"stateValue\":\"OK\",\"stateReason\":\"Threshold Crossed: 2 datapoints were not greater than the threshold (70.0). The most recent datapoints: [38.839999999999996, 39.714].\",\"stateReasonData\":{\"version\":\"1.0\",\"queryDate\":\"2014-03-11T22:45:41.569+0000\",\"startDate\":\"2014-03-11T22:30:00.000+0000\",\"statistic\":\"Average\",\"period\":300,\"recentDatapoints\":[38.839999999999996,39.714],\"threshold\":70.0}},\"newState\":{\"stateValue\":\"ALARM\",\"stateReason\":\"testing purposes\"}}", "HistorySummary": "Alarm updated from OK to ALARM" } ] }

从输出可见，每条记录包含了时间戳、历史类型、告警名称、摘要（HistorySummary）以及一个 JSON 字符串形式的结构化数据（HistoryData）。下文将逐项拆解。

请求参数详解（含取值与默认行为）

该命令的输入结构DescribeAlarmHistoryInput定义在 service-2.json，全部为可选参数，可按需组合：

关键默认行为（来自服务模型文档）：

• 未指定告警名称时，返回“所有指标告警”或（配合AlarmTypes）“所有复合告警”的历史；
• 未指定AlarmTypes时，只返回指标告警；
• CloudWatch 会一直保留告警的历史记录，即使告警本身已被删除——这意味着你可以在告警删除后依然审计其历史行为。

历史类型（HistoryItemType）与告警类型（AlarmTypes）

--history-item-type的合法枚举值定义在 service-2.json：

--alarm-types则用于限定告警类别（指标告警 / 复合告警 / 日志告警），其 shape 定义在 service-2.json。两者配合即可精确圈定查询范围。

时间范围与排序控制

实际排查问题时通常需要缩小时间窗口：

# 查询指定告警在某个时间窗口内的所有状态变更，最新记录在前 aws cloudwatch describe-alarm-history \ --alarm-name "myalarm" \ --history-item-type StateUpdate \ --start-date 2026-09-01T00:00:00Z \ --end-date 2026-09-15T00:00:00Z \ --scan-by TimestampDescending

• --start-date/--end-date用于过滤日期范围，适合回放某段时间的监控事件；
• --scan-by控制返回顺序，枚举值为TimestampDescending（默认方向，最新在前）与TimestampAscending（最旧在前），定义于 service-2.json。按时间正序（TimestampAscending）读取时，可以逐条还原告警从 OK → ALARM → OK 的完整生命周期。

分页：MaxRecords 与 NextToken

当告警历史记录较多时，一次请求无法返回全部数据。该命令的分页配置位于仓库 paginators-1.json：

"DescribeAlarmHistory": { "input_token": "NextToken", "output_token": "NextToken", "limit_key": "MaxRecords", "result_key": "AlarmHistoryItems" }

即：请求参数--max-records控制每页条数，--next-token传入上一页返回的NextToken获取下一页，翻页数据存放在响应中的AlarmHistoryItems。

手动翻页示例：

# 第一页：每页最多 50 条 aws cloudwatch describe-alarm-history \ --alarm-name "myalarm" \ --max-records 50 # 第二页：把上一页响应中的 NextToken 传入 aws cloudwatch describe-alarm-history \ --alarm-name "myalarm" \ --max-records 50 \ --next-token "PASTE_NEXT_TOKEN_HERE"

更推荐直接使用 CLI 内建分页机制，让工具自动翻页并汇总全部结果：

aws cloudwatch describe-alarm-history \ --alarm-name "myalarm" \ --history-item-type StateUpdate \ --max-items 100 \ --output json

说明：--max-items是 AWS CLI 通用分页参数（对应服务端MaxRecords），配合--starting-token可继续拉取后续页；两者与仓库分页配置中的limit_key、input_token一一对应。

输出结构逐字段解读

每个历史记录元素对应AlarmHistoryItem结构，成员定义于 service-2.json：

响应顶层还包含NextToken，用于判断是否还有更多数据（见上文分页部分）。

深入解读 HistoryData：还原状态变更现场

HistoryData是字符串化的 JSON，是整条记录里信息密度最高的部分。以原示例第一条为例，展开后结构如下：

{ "version": "1.0", "oldState": { "stateValue": "ALARM", "stateReason": "testing purposes" }, "newState": { "stateValue": "OK", "stateReason": "Threshold Crossed: 2 datapoints were not greater than the threshold (70.0). The most recent datapoints: [38.958, 40.292].", "stateReasonData": { "version": "1.0", "queryDate": "2014-04-09T18:59:06.419+0000", "startDate": "2014-04-09T18:44:00.000+0000", "statistic": "Average", "period": 300, "recentDatapoints": [38.958, 40.292], "threshold": 70.0 } } }

分析要点：

• oldState/newState：分别记录状态变更前后的状态值（OK / ALARM / INSUFFICIENT_DATA）与变更原因，直接回答“从什么状态变成了什么状态、为什么”；
• newState.stateReason：自然语言描述，如示例中明确写到“2 个数据点未超过阈值 70.0，最近数据点为 [38.958, 40.292]”，一眼即可定位是恢复（数据回落到阈值以下）而非配置变更；
• stateReasonData：机器可读的判据快照，包含统计类型（statistic=Average）、评估周期（period=300 秒）、最近数据点（recentDatapoints）与阈值（threshold=70.0）。这些数据可以用来复核“告警判定是否准确”，例如确认恢复时刻最近两个数据点确实低于阈值；
• 第二条记录展示了反向变更（OK → ALARM），oldState携带阈值跨越原因、newState携带 “testing purposes”，说明这是一次人工测试触发的状态置位（对应set-alarm-state命令的典型场景，参见仓库 set-alarm-state.rst）。

在 shell 中可借助 jq 直接提取可读信息：

aws cloudwatch describe-alarm-history --alarm-name "myalarm" \ --query "AlarmHistoryItems[].{Time:Timestamp, Summary:HistorySummary}" \ --output table

权限要求与注意事项

根据服务模型文档：

• 查询告警历史需要cloudwatch:DescribeAlarmHistory权限；
• 若要返回复合告警（composite alarm）的信息，该权限必须作用域为*（即不能收窄到特定资源），否则无法读取复合告警的历史；
• 告警历史会在告警删除后继续保留，这既是优点（可审计），也意味着历史记录可能随时间持续累积，配合--max-records与时间范围过滤能有效控制数据量。

实战场景：用历史记录做告警体检

综合上面的能力，可以组合出几类高频用法：

1. 排查“告警为什么误报/漏报”

aws cloudwatch describe-alarm-history \ --alarm-name "HighCPUAlarm" \ --history-item-type StateUpdate \ --start-date 2026-09-13T00:00:00Z \ --end-date 2026-09-14T00:00:00Z \ --scan-by TimestampAscending

按时间正序回放状态变迁，结合每条HistoryData里的recentDatapoints、threshold、period复核当时的判定依据，判断是数据突刺、阈值设置不当还是统计周期过短。

2. 审计告警动作是否生效

aws cloudwatch describe-alarm-history \ --alarm-name "HighCPUAlarm" \ --history-item-type Action

只拉取Action类型记录，核对每次状态变更后配置的 SNS/自动伸缩动作是否被正确触发。

3. 区分人工操作与真实事件

HistoryData中stateReason为 “testing purposes” 的记录通常来自set-alarm-state命令（见仓库 set-alarm-state.rst）或控制台测试，与真实的阈值跨越记录（stateReason 为 “Threshold Crossed: ...” 格式）区分开，避免把测试流量当成线上故障。

4. 多条件组合做全量审计

aws cloudwatch describe-alarm-history \ --alarm-types MetricAlarm \ --history-item-type ConfigurationUpdate \ --max-items 200

不指定--alarm-name，配合--alarm-types与--history-item-type ConfigurationUpdate，可审计账号下所有指标告警的配置变更轨迹——这正是服务模型文档描述的“未指定告警名称时返回所有指标告警历史”的用法。

结语

aws cloudwatch describe-alarm-history是 CloudWatch 告警体系的“黑匣子记录仪”：通过--alarm-name、--history-item-type、--start-date/--end-date、--scan-by的组合过滤，配合--max-records与NextToken分页，可以完整还原每一次状态切换、配置变更与动作触发的现场数据。建议将它与仓库中的 describe-alarms.rst（查看告警当前状态）、put-metric-alarm.rst（创建/修改告警）、set-alarm-state.rst（手动置位测试）配合使用，即可在告警的“创建 — 变更 — 触发 — 恢复 — 删除”全生命周期内拥有完整的可审计记录。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli