使用 AWS CLIput-metric-stream创建 CloudWatch 指标流：完整参数解析与实战指南
【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli
导读
本文以 aws-cli 仓库中 put-metric-stream 官方示例 为骨架，系统讲解如何通过aws cloudwatch put-metric-stream命令创建 CloudWatch 指标流（Metric Stream），将账户内的 CloudWatch 指标实时投递到 Amazon Kinesis Data Firehose，再进一步转发至 Amazon S3 或第三方监控/可观测性平台。读完本文，你将掌握该命令的全部参数含义、IAM 与 Firehose 前置条件、输出格式（JSON 与 OpenTelemetry）的选择逻辑，以及如何用get-metric-stream、delete-metric-stream等配套命令完成指标流的全生命周期管理。
一、命令概览与官方示例
put-metric-stream对应的底层 API 为PutMetricStream，其官方文档描述为"创建或更新一个指标流，自动将 CloudWatch 指标流式传输到 AWS 目标（包括 Amazon S3）以及众多第三方解决方案"（见 service-2.json 中的 API 定义）。
仓库自带的官方示例文件 put-metric-stream.rst 给出了一个最简可用的创建命令：
aws cloudwatch put-metric-stream \ --name QuickFull-GuaFbs \ --firehose-arn arn:aws:firehose:us-east-1:123456789012:deliverystream/MetricStreams-QuickFull-GuaFbs-WnySbECG \ --role-arn arn:aws:iam::123456789012:role/service-role/MetricStreams-FirehosePutRecords-JN10W9B3 \ --output-format json \ --no-include-linked-accounts-metrics执行成功后返回：
{ "Arn": "arn:aws:cloudwatch:us-east-1:123456789012:metric-stream/QuickFull-GuaFbs" }该示例虽短，但恰好覆盖了创建指标流的四个必填参数（Name、FirehoseArn、RoleArn、OutputFormat）。从 service-2.json 的PutMetricStreamInput定义 可以看出，required列表恰好是这四个参数，其余均为可选。
二、参数详解（基于 API 模型源码）
以下内容均可在 PutMetricStreamInput 结构体 中找到权威依据。
2.1 必填参数
| 参数 | CLI 写法 | 约束与说明 |
|---|---|---|
| 指标流名称 | --name | 新建时命名；更新时指定已有流名称。账户与区域内不得与其他指标流重名。合法字符为A-Z、a-z、0-9、-、_，长度 1~255（MetricStreamName类型，见 service-2.json） |
| Firehose 投递流 ARN | --firehose-arn | 指向已存在的 Amazon Kinesis Data Firehose 投递流，且必须与指标流处于同一账户 |
| IAM 角色 ARN | --role-arn | 指标流用于访问 Firehose 资源的 IAM 角色，必须已存在且与指标流同账户；角色需包含firehose:PutRecord与firehose:PutRecordBatch两个权限 |
| 输出格式 | --output-format | 合法值见下节MetricStreamOutputFormat枚举 |
2.2 输出格式枚举
根据 MetricStreamOutputFormat 定义，--output-format支持三个取值：
json：CloudWatch 原生 JSON 格式，指标流默认携带MAX、MIN、SUM、SAMPLECOUNT四种统计量；opentelemetry1.0：OpenTelemetry 协议 1.0 版本；opentelemetry0.7：OpenTelemetry 协议 0.7 版本。
选型提示：若下游是原生 Prometheus、Grafana 或其他支持 OTLP 的可观测性系统，建议使用 OpenTelemetry 格式；若下游是自定义 JSON 解析管道，则使用json即可。
2.3 可选参数
--include-filters：白名单过滤，仅发送指定 metric namespace 下的指标。IncludeFilters与ExcludeFilters不能同时出现。--exclude-filters：黑名单过滤，发送除指定 namespace 之外的所有指标。同样不能与IncludeFilters混用。--include-linked-accounts-metrics：在监控账户（monitoring account）中创建指标流时，设为true可把源账户的指标一并纳入流中。示例中使用--no-include-linked-accounts-metrics显式关闭（CLI 对布尔参数提供--include-*/--no-include-*双写法）。--tags：为指标流附加标签，最多 50 个键值对；仅新建时生效，更新已有流时会被忽略（改标签请用tag-resource/untag-resource）。--statistics-configurations：默认只发送四种基础统计量；通过该参数可为指定指标追加额外统计量，数组最多 100 项。
三、过滤器与统计量配置的底层约束
3.1 过滤器结构（MetricStreamFilter）
从 MetricStreamFilter 定义 可知每个过滤器包含两个成员：
Namespace：指标命名空间，仅含 ASCII 可打印字符（32~126），且必须包含至少一个非空白字符；MetricNames：可选，指定命名空间下需要包含/排除的具体指标名列表；省略时表示该命名空间下所有指标全部命中。
配额要点：指标流全部过滤器的"命名空间名 + 指标名"总和上限为1000 个名称（例如 10 个 namespace 过滤器各带 99 个指标名，或 20 个 namespace 各带 49 个指标名）。
3.2 追加统计量（StatisticsConfigurations）
根据 MetricStreamStatisticsConfiguration 定义：
- 每个配置项由
IncludeMetrics（指标名 + 命名空间对，最多 100 对，匹配所有维度）与AdditionalStatistics（最多 20 个统计量）组成； OutputFormat为json时，可追加任意 CloudWatch 支持的统计量（如tm98、wm90、PR(:300)等）；OutputFormat为opentelemetry0.7/opentelemetry1.0时，只能追加百分位统计量（如p90、p99、p99.9）。
一个带过滤器和追加统计量的完整示例：
aws cloudwatch put-metric-stream \ --name my-metric-stream \ --firehose-arn arn:aws:firehose:us-east-1:123456789012:deliverystream/my-firehose \ --role-arn arn:aws:iam::123456789012:role/service-role/MetricStreams-FirehosePutRecords-JN10W9B3 \ --output-format opentelemetry1.0 \ --include-filters Namespace=AWS/EC2,MetricNames=CPUUtilization \ --statistics-configurations 'IncludeMetrics=[{Namespace=AWS/EC2,MetricName=CPUUtilization}],AdditionalStatistics=[p90,p99]' \ --tags '{"Environment":"production"}'四、前置条件与权限
PutMetricStream的 API 文档（见 service-2.json）明确列出两条硬性前置：
- 调用者必须登录到具有
iam:PassRole权限的账户； - 同时具备
CloudWatchFullAccess策略或cloudwatch:PutMetricStream单项权限。
此外，指标流运行所需的 IAM 角色必须内联以下两个 Firehose 权限（官方示例中的角色 ARN 形如MetricStreams-FirehosePutRecords-*）：
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["firehose:PutRecord", "firehose:PutRecordBatch"], "Resource": "*" } ] }五、生命周期管理配套命令
指标流创建后，可用同目录下的其他官方示例完成全流程管理：
- 查看详情：get-metric-stream 示例 —— 返回
Arn、Name、FirehoseArn、RoleArn、State（如running）、CreationDate、LastUpdateDate、OutputFormat、IncludeLinkedAccountsMetrics等字段，便于核对创建结果； - 列出所有流：
aws cloudwatch list-metric-streams； - 删除指标流：delete-metric-stream 示例 ——
aws cloudwatch delete-metric-stream --name <stream-name>，命令无输出，删除后数据不再投递； - 启停指标流：
aws cloudwatch start-metric-streams/stop-metric-streams（对应 API 在 service-2.json 中定义）； - 标签管理：
tag-resource/untag-resource/list-tags-for-resource。
上述全部命令由 CLI 服务命令注册表统一暴露，命令入口可追溯至 awscli/botocore/data/cloudwatch/2010-08-01/service-2.json 中对应的 API 定义，以及仓库中同目录下的 其余 cloudwatch 示例文件（含delete-metric-stream.rst、get-metric-stream.rst、list-metric-streams.rst等），可在本地仓库中继续研读。
六、注意事项与最佳实践
- 命名与区域隔离：指标流名称在同一账户同一区域内唯一，跨区域可重名；名称只允许字母、数字、
-、_。 - Firehose 与角色同账户：
--firehose-arn与--role-arn指向的资源必须与指标流同账户，跨账户投递需借助监控账户与源账户的--include-linked-accounts-metrics机制。 - 更新语义：
put-metric-stream同时承担"创建"与"更新"两种语义——对已存在名称再次调用即为更新；更新时Tags参数被忽略。 - 过滤优先于成本：默认流送全部命名空间的全部指标，指标量大会直接推高 Firehose 投递费用与下游存储成本；建议先用
--include-filters收窄到关键命名空间（如AWS/EC2、AWS/Lambda），再按需放宽。 - 验证输出格式：使用 OpenTelemetry 格式时，确保下游消费者支持 OTLP；使用
json格式时，默认四统计量之外的需求通过--statistics-configurations显式声明。
【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
