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

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 CLIawscli 仓库中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等查询操作中可见。同时服务模型明确给出了该请求的底层形态HTTPPOSTrequestUri为/并声明支持 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 必填与选填字段说明根据服务模型中PutMetricDataInputservice-2.json与MetricDatum结构的定义字段必填说明Namespace顶层是指标命名空间仅支持 ASCII 字符控制字符除外为避免与 AWS 服务自带指标冲突不应以AWS/开头MetricName是指标名称长度 1–255 字符Value二选一指标数值类型为 Double取值范围必须在 -2^360 到 2^360 之间不支持 NaN、Infinity、-Infinity 等特殊值ValuesCounts二选一用数值数组 出现次数数组的方式一次性上报最多150 个去重数值可用于计算百分位统计percentileTimestamp否数据点的时间戳可回溯到当前日期之前最多两周也可指向当前时间之后最多 2 小时Unit否指标单位取值见下文单位枚举一节Dimensions否维度数组最多30 个维度StatisticValues否统计集合Sum/Min/Max/SampleCount适用于已知聚合结果的上报StorageResolution否存储分辨率1表示高分辨率指标亚分钟级仅自定义指标可用60为常规分辨率默认 60提示Value与Values/Counts属于同一数据点的两种表达方式按需选择其一即可二者在同一 MetricDatum 中同时使用可能触发参数组合校验错误。3. 方式二命令行直接指定指标、单位与多维度官方示例还提供了完全通过命令行参数完成上报的写法不依赖 JSON 文件aws cloudwatch put-metric-data --metric-name Buffers --namespace MyNameSpace --unit Bytes --value 231434333 --dimensions InstanceID1-23456789,InstanceTypem1.small这里展示了put-metric-data的命令行参数用法--metric-name Buffers指定指标名称--namespace MyNameSpace指定命名空间--unit Bytes指定单位为字节--value 231434333直接给出数值--dimensions InstanceID1-23456789,InstanceTypem1.small指定多个维度。每个维度用NameValue表达多个维度之间用英文逗号分隔。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.jsonSeconds、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: 1CloudWatch 会将其作为高分辨率自定义指标存储最小支持 1 秒粒度未设置时默认按 60 秒的常规分辨率存储。查询侧需注意高分辨率指标在get-metric-statistics中的 Period 可取 1、5、10、20、30、60 秒等值见服务模型中MetricStat.Period的说明而常规指标 Period 最短为 60 秒。4. 命令执行与数据可观测性限制在真正落地使用时需要了解服务模型明确记载的几项重要限制避免踩坑单请求体积上限每个PutMetricData请求最多 1 MBHTTP 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错误典型触发原因InvalidParameterValueException参数值非法如数值超出 -2^360 到 2^360、包含 NaN 等特殊值MissingRequiredParameterException缺少必填参数最常见的是漏掉Namespace或MetricNameInvalidParameterCombinationException参数组合冲突如同时提供Value与Values/CountsInternalServiceFaultCloudWatch 服务端内部错误可稍后重试调试建议先在本地构造好 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考