企业官网建设流程全解析

AWS CLI 实战指南：使用 cloudwatch put-metric-alarm 创建与更新 CloudWatch 指标告警

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

本文围绕 AWS CLI 中cloudwatch put-metric-alarm命令展开，结合当前仓库 awscli/examples/cloudwatch/put-metric-alarm.rst 中的官方示例，讲解如何基于静态阈值创建 EC2 CPU 利用率告警、通过 SNS 触发邮件通知、以及如何为单条指标指定多个维度。读完本文，你将能够独立编写可复用的 put-metric-alarm 命令，并理解各参数在底层 API 中的约束与取值来源。

命令定位：PutMetricAlarm 在 CloudWatch 告警体系中的作用

put-metric-alarm对应 CloudWatch API 中的PutMetricAlarm操作。从 awscli/botocore/data/cloudwatch/2010-08-01/service-2.json 的模型定义（PutMetricAlarm，见第 673 行起）可以看出，它承担两类职责：

• 创建告警：为指定指标、指标数学表达式、异常检测模型、Metrics Insights 查询或 PromQL 查询创建一条新的告警；
• 更新告警：如果同名告警已存在，直接以新配置覆盖。

值得注意的是该操作对告警初始状态的定义：普通指标告警创建后，告警状态会立即被置为INSUFFICIENT_DATA，随后系统开始评估并根据数据将其调整为实际状态；基于 PromQL 的告警则初始置为OK。理解这一点有助于排查"刚创建告警为何看不到 ALARM 状态"的疑问。

官方文档中给出的两个示例正是这个命令最典型的两种用法：

1. CPU 利用率超过 70% 时发送 SNS 邮件通知；
2. 为指标指定多个维度（Name/Value 对）。

下面分别深入拆解。

示例一：CPU 利用率超过 70% 时发送 SNS 邮件通知

原文档给出如下完整命令（put-metric-alarm.rst 第 5 行）：

aws cloudwatch put-metric-alarm \ --alarm-name cpu-mon \ --alarm-description "Alarm when CPU exceeds 70 percent" \ --metric-name CPUUtilization \ --namespace AWS/EC2 \ --statistic Average \ --period 300 \ --threshold 70 \ --comparison-operator GreaterThanThreshold \ --dimensions "Name=InstanceId,Value=i-12345678" \ --evaluation-periods 2 \ --alarm-actions arn:aws:sns:us-east-1:111122223333:MyTopic \ --unit Percent

该命令成功执行后不会输出任何 JSON 结果，直接返回命令行提示符。如果已存在名为cpu-mon的告警，这条命令会以新参数将其整体覆盖——这也是put-metric-alarm作为"创建或更新"二合一操作的核心语义。

逐参数说明与底层取值约束

结合 service-2.json 中PutMetricAlarmInput（第 4272 行起）的成员定义，逐项说明上述参数：

• --alarm-name：必填参数，告警名称在同一 Region 内必须唯一；只允许 UTF-8 字符，且不能包含 ASCII 控制字符（模型定义）。
• --alarm-description：告警描述，纯说明性内容。
• --metric-name/--namespace：分别指定指标名（如CPUUtilization）与命名空间（如AWS/EC2）。API 要求每次PutMetricAlarm必须且只能三选一：提供MetricName、提供Metrics数组（指标数学表达式），或提供EvaluationCriteria。
• --statistic：聚合统计量。模型中的Statistic枚举（第 4805 行起）固定为SampleCount、Average、Sum、Minimum、Maximum五选一；若需分位数统计（如p90），必须改用--extended-statistic，两者不能同时指定。
• --period：每次评估指标的数据周期（秒）。合法值为 10、20、30 以及 60 的任意倍数。仅当指标通过PutMetricData以StorageResolution=1（亚分钟分辨率）存储时才应使用 10/20/30，否则告警会频繁落入INSUFFICIENT_DATA状态；指定 10/20/30 还会使该告警成为高分辨率告警（计费更高）。同时存在硬性约束：Period × EvaluationPeriods不得超过 604800 秒（7 天），且当Period小于 3600 秒（1 小时）时，总评估周期不得超过 86400 秒（1 天）。
• --threshold：静态阈值告警的阈值，即统计量与之比较的基准值。
• --comparison-operator：比较运算符，作为第一操作数的是指标统计值。ComparisonOperator枚举（第 1214 行起）共 7 个取值：GreaterThanOrEqualToThreshold、GreaterThanThreshold、LessThanThreshold、LessThanOrEqualToThreshold，以及仅用于异常检测模型告警的LessThanLowerOrGreaterThanUpperThreshold、LessThanLowerThreshold、GreaterThanUpperThreshold。示例中的GreaterThanThreshold即"严格大于阈值"。
• --evaluation-periods：需要多少个周期的数据点与阈值比较。若希望"连续 N 个数据点越界才触发"，此值就是 N；若配置"M out of N"告警，此值是 N。
• --alarm-actions：告警进入ALARM状态时执行的动作，每个动作以 ARN 表示。SNS 通知的 ARN 形如arn:aws:sns:<region>:<account-id>:<topic-name>（即示例用法）。同一参数位置还支持 EC2 自动化动作（如arn:aws:automate:<region>:ec2:stop）、Auto Scaling 策略、Lambda 函数、SSM OpsItem 等；对应地，还有--ok-actions（进入OK状态时执行）与--insufficient-data-actions（进入INSUFFICIENT_DATA状态时执行）两组同类参数（AlarmActions 定义）。
• --unit：统计量的度量单位。StandardUnit枚举（第 4727 行起）包含Seconds、Bytes、Percent、Count、Count/Second、None等 28 个取值，示例使用Percent。需要特别留意模型的建议：若某指标被以多种单位发布而你又未指定--unit，告警行为不可预期；若指定了未发布的错误单位，告警会卡在INSUFFICIENT_DATA。因此官方建议通常省略--unit，仅在确认需要时显式指定。

底层语义：创建即置 INSUFFICIENT_DATA

文档明确该命令在成功时直接返回。结合 service-2.json 中PutMetricAlarm的操作说明（第 673 行起）：创建告警后，普通指标告警的状态被立即设为INSUFFICIENT_DATA，随后才按评估周期逐步进入OK或ALARM。这意味着示例中--evaluation-periods 2配合--period 300的含义是：以 5 分钟为周期、连续 2 个周期的 CPU 平均值（Average）都大于 70% 时，告警进入 ALARM 并触发 SNS 邮件，从而有效避免瞬时抖动的误报。

示例二：为同一指标指定多个维度

原文档第二个示例演示了多维度指标的写法（put-metric-alarm.rst 第 13 行）：

aws cloudwatch put-metric-alarm \ --alarm-name "Default_Test_Alarm3" \ --alarm-description "The default example alarm" \ --namespace "CW EXAMPLE METRICS" \ --metric-name Default_Test \ --statistic Average \ --period 60 \ --evaluation-periods 3 \ --threshold 50 \ --comparison-operator GreaterThanOrEqualToThreshold \ --dimensions Name=key1,Value=value1 Name=key2,Value=value2

这里的语法要点正是 CLI 的 shorthand 语法规则：

• 每个维度是一个Name/Value对，写作Name=key1,Value=value1；
• 多个维度之间以空格分隔，直接并列传入同一个--dimensions参数；
• 该写法与仓库中其他 CloudWatch 示例保持一致，例如 get-metric-statistics.rst 中的--dimensions Name=InstanceID,Value=i-abcdef Name=InstanceType,Value=m1.small，以及 describe-alarms-for-metric.rst 中的单维度写法，可以交叉印证语法的通用性。

从 API 模型看，Dimensions是MetricName所对应指标的维度过滤条件（Dimensions 定义），告警只会基于与所有维度键值完全匹配的数据点进行评估。同时该示例也补充了第一个示例未覆盖的运算符GreaterThanOrEqualToThreshold（大于等于阈值），在 CPU 告警中同样常用。

进阶参数：让告警更精准

除两个示例涉及的参数外，PutMetricAlarmInput还定义了若干高频进阶参数，可在此一并掌握：

• --actions-enabled：布尔值，是否在告警状态变化时执行动作，默认TRUE。
• --datapoints-to-alarm：配合--evaluation-periods实现"M out of N"告警——N 个周期内只要有 M 个数据点越界即触发，不必连续。
• --treat-missing-data：缺失数据点的处理策略，合法值为breaching、notBreaching、ignore、missing（默认missing）。注意两条特例：评估AWS/DynamoDB命名空间指标的告警总是按ignore处理；该参数不适用于 PromQL 告警。
• --evaluate-low-sample-count-percentile：仅用于分位数告警，取值evaluate或ignore，控制数据点过少时是否仍然评估。
• --metrics：指标数学表达式告警的查询数组，使用该参数时不能再同时指定Namespace、MetricName、Dimensions、Period、Unit、Statistic、ExtendedStatistic。
• --tags：创建告警时附加标签（最多 50 个），需要同时具备cloudwatch:PutMetricAlarm与cloudwatch:TagResource权限；更新已有告警时该参数会被忽略。
• --evaluation-window：评估窗口类型（滑动窗口或固定时钟窗口），省略时默认滑动窗口。
• --evaluation-criteria/--evaluation-interval：面向 PromQL 告警的评估条件与评估频率（10、20、30 或 60 的倍数），二者与MetricName/Metrics模式互斥。

这些参数共同构成一条完整告警的可调面，建议在实际创建前用aws cloudwatch put-metric-alarm --generate-cli-skeleton生成完整 JSON 骨架，再按需填充，避免漏参。

验证与配套操作

告警创建完成后，可通过仓库中的配套示例命令验证：

# 查看与某指标关联的所有告警 aws cloudwatch describe-alarms-for-metric \ --metric-name CPUUtilization --namespace AWS/EC2 \ --dimensions Name=InstanceId,Value=i-12345678 # 查询该指标的历史统计值，确认阈值设置是否合理 aws cloudwatch get-metric-statistics \ --metric-name CPUUtilization --namespace AWS/EC2 \ --start-time 2026-09-14T00:00:00Z --end-time 2026-09-15T00:00:00Z \ --period 300 --statistics Average \ --dimensions Name=InstanceId,Value=i-12345678

对应示例分别见 describe-alarms-for-metric.rst 与 get-metric-statistics.rst。此外，CloudWatch 告警动作会写入 SNS 主题，若邮件未如期到达，可从 SNS 主题的投递状态与 CloudWatch 告警状态历史（describe-alarm-history）两个方向排查。

小结

cloudwatch put-metric-alarm是 AWS CLI 中管理静态阈值告警的核心命令。本文基于官方示例拆解了两个最常用场景——SNS 邮件告警与多维度指标告警，并结合 service-2.json 中PutMetricAlarmInput的完整模型，澄清了Period × EvaluationPeriods的时间窗约束、Statistic与ExtendedStatistic的互斥关系、--unit的省略建议，以及 "M out of N"、缺失数据处理等进阶能力。掌握这些细节后，无论是从零创建监控告警，还是维护已有告警，都能避免最常见的"建了不生效"与"频繁误报"两类问题。

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