企业官网建设流程全解析

AWS CLIcloudwatch put-metric-data实战指南：向 Amazon CloudWatch 发布自定义指标

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

导读

本文围绕 AWS CLI（awscli 仓库）中aws cloudwatch put-metric-data命令的官方示例文档展开，系统讲解如何将业务应用的自定义指标发布到 Amazon CloudWatch，包括通过 JSON 文件批量上报、命令行直接指定维度与数值两种典型用法。读完本文，你将掌握该命令的完整参数语义、JSON 数据结构、单位（Unit）与高分辨率指标（StorageResolution）的取值规范，以及上报后的验证手段，能够独立将自定义监控指标接入 CloudWatch 并支撑后续告警与统计查询。

1. 命令概览：put-metric-data 解决什么问题

put-metric-data是 AWS CLI 中 CloudWatch 服务的核心写操作命令，对应 CloudWatch API 的PutMetricData动作。它的作用是向 CloudWatch 发布一条或多条自定义指标数据。根据仓库内的服务模型定义（awscli/botocore/data/cloudwatch/2010-08-01/service-2.json）中的PutMetricData说明：

"If the specified metric does not exist, CloudWatch creates the metric."

也就是说，发布指标时如果该指标尚不存在，CloudWatch 会自动创建它，随后在控制台、list-metrics等查询操作中可见。同时服务模型明确给出了该请求的底层形态：HTTPPOST，requestUri为/，并声明支持 gzip 请求体压缩（"requestcompression":{"encodings":["gzip"]}）。这解释了为什么大批量数据上报时可以通过压缩降低网络开销。

put-metric-data适合以下场景：

• 应用自定义业务指标（如本文示例中的 "New Posts" 帖子数、"Buffers" 缓冲区大小）；
• 从脚本、定时任务中上报服务状态与性能数据；
• 为后续的告警（put-metric-alarm）、统计查询（get-metric-statistics）和仪表盘提供数据源。

2. 方式一：通过 JSON 文件发布自定义指标

官方示例（awscli/examples/cloudwatch/put-metric-data.rst）给出了最基本也是最常用的用法——把指标数据写入 JSON 文件，再通过file://前缀引用：

aws cloudwatch put-metric-data --namespace "Usage Metrics" --metric-data file://metric.json

其中：

• --namespace：指标的命名空间，用来区分不同的指标来源（例如区分"业务指标"和"AWS 服务指标"）。本示例使用Usage Metrics。
• --metric-data：指标数据数组，从metric.json文件读取。

示例中metric.json的内容如下：

[ { "MetricName": "New Posts", "Timestamp": "Wednesday, June 12, 2013 8:28:20 PM", "Value": 0.50, "Unit": "Count" } ]

该数组的每个元素对应一个MetricDatum结构。一个 JSON 文件中可以包含多个指标数据点，例如同时上报多个指标：

[ { "MetricName": "New Posts", "Value": 12.0, "Unit": "Count", "StorageResolution": 60 }, { "MetricName": "Page Views", "Value": 243.0, "Unit": "Count", "Dimensions": [ { "Name": "Page", "Value": "/index.html" } ] } ]

2.1 必填与选填字段说明

根据服务模型中PutMetricDataInput（service-2.json）与MetricDatum结构的定义：

提示：Value与Values/Counts属于同一数据点的两种表达方式，按需选择其一即可，二者在同一 MetricDatum 中同时使用可能触发参数组合校验错误。

3. 方式二：命令行直接指定指标、单位与多维度

官方示例还提供了完全通过命令行参数完成上报的写法（不依赖 JSON 文件）：

aws cloudwatch put-metric-data --metric-name Buffers --namespace MyNameSpace --unit Bytes --value 231434333 --dimensions InstanceID=1-23456789,InstanceType=m1.small

这里展示了put-metric-data的命令行参数用法：

• --metric-name Buffers：指定指标名称；
• --namespace MyNameSpace：指定命名空间；
• --unit Bytes：指定单位为字节；
• --value 231434333：直接给出数值；
• --dimensions InstanceID=1-23456789,InstanceType=m1.small：指定多个维度。每个维度用Name=Value表达，多个维度之间用英文逗号分隔。

3.1 维度（Dimensions）的语义

从服务模型的Dimension结构（service-2.json）看，维度是"指标身份的一部分"：

"Because dimensions are part of the unique identifier for a metric, whenever you add a unique name/value pair to one of your metrics, you are creating a new variation of that metric."

即维度是构成指标唯一标识的关键要素。例如 EC2 的CPUUtilization指标以InstanceId为维度，不同实例对应不同的指标序列。本示例用InstanceID和InstanceType两个维度将"Buffers"指标按实例切分，便于后续按实例维度聚合查询。

维度的约束包括：

• Name与Value均必填；
• 只能包含 ASCII 字符，必须至少包含一个非空白字符；
• 维度名称不能以冒号（:）开头，不支持 ASCII 控制字符；
• 每个指标最多 30 个维度。

3.2 单位（Unit）枚举

--unit参数的合法取值来自服务模型的StandardUnit枚举（service-2.json）：

Seconds、Microseconds、Milliseconds、Bytes、Kilobytes、Megabytes、Gigabytes、Terabytes、Bits、Kilobits、Megabits、Gigabits、Terabits、Percent、Count、Bytes/Second、Kilobytes/Second、Megabytes/Second、Gigabytes/Second、Terabytes/Second、Bits/Second、Kilobits/Second、Megabits/Second、Gigabits/Second、Terabits/Second、Count/Second、None

选择单位时建议与实际量纲一致，例如流量类指标使用Bytes/Second，比例类指标使用Percent，计数类指标使用Count。

3.3 高分辨率指标（StorageResolution）

若需要亚分钟级精度（如 5 秒、10 秒采集一次），可在数据点中设置StorageResolution: 1，CloudWatch 会将其作为高分辨率自定义指标存储，最小支持 1 秒粒度；未设置时默认按 60 秒的常规分辨率存储。查询侧需注意：高分辨率指标在get-metric-statistics中的 Period 可取 1、5、10、20、30、60 秒等值（见服务模型中MetricStat.Period的说明），而常规指标 Period 最短为 60 秒。

4. 命令执行与数据可观测性限制

在真正落地使用时，需要了解服务模型明确记载的几项重要限制，避免踩坑：

• 单请求体积上限：每个PutMetricData请求最多 1 MB（HTTP POST 请求体），可通过 gzip 压缩载荷。
• 单请求指标数量上限：每次请求最多1000 个不同指标（MetricData与EntityMetricData合计）。
• 新指标可见延迟：CloudWatch 创建新指标后，最多可能需要 15 分钟才会出现在ListMetrics结果中。
• 数据可用延迟：时间戳距今 24 小时以上的数据点，提交后至少需要 48 小时才能在get-metric-data/get-metric-statistics中查询到；时间戳在 3 到 24 小时之间的数据点，最长可能需要 2 小时。
• 时间戳范围：最早可回溯两周，最晚可指向当前时间之后 2 小时。
• 数值范围：Double 值必须在 -2^360 到 2^360 之间，不支持 NaN 与 ±Infinity。

5. 发布后的验证：list-metrics 与 get-metric-statistics

发布指标后，可以用同一仓库中提供的配套示例命令来验证数据是否写入成功：

• 使用 list-metrics 查看命名空间下已存在的指标：

aws cloudwatch list-metrics --namespace "Usage Metrics"

• 使用 get-metric-statistics 拉取指定时间窗内的统计值，验证数据点是否已可查询：

aws cloudwatch get-metric-statistics \ --namespace "Usage Metrics" \ --metric-name "New Posts" \ --statistics Sum \ --period 300 \ --start-time 2026-09-15T00:00:00Z \ --end-time 2026-09-15T01:00:00Z

• 数据稳定后，可继续通过 put-metric-alarm 基于该指标创建告警，实现阈值触发的自动通知。

6. 错误处理与调试建议

服务模型为PutMetricData定义了四类错误（见 service-2.json 中PutMetricData.errors）：

调试建议：

• 先在本地构造好 JSON 文件，用--output json或直接观察命令退出码判断是否提交成功（put-metric-data成功时无返回内容，退出码为 0）；
• 大批量上报时优先使用file://metric.json方式，便于审计与版本管理；
• 若指标长时间未出现在查询结果中，对照上文"数据可观测性限制"核对时间戳与延迟窗口。

7. 小结

aws cloudwatch put-metric-data是将自定义监控数据接入 Amazon CloudWatch 的入口命令，支持"JSON 文件批量上报"与"命令行直接指定"两种模式。通过合理设置命名空间、维度、单位与存储分辨率，并理解请求体积、指标数量、时间戳与可见延迟等限制，即可稳定、高效地完成自定义指标的上报，为后续的指标查询、仪表盘与告警体系奠定数据基础。本文所有参数语义与限制说明均可对照仓库中的服务模型文件 awscli/botocore/data/cloudwatch/2010-08-01/service-2.json 以及官方示例 awscli/examples/cloudwatch/put-metric-data.rst 进一步深入查阅。

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