企业官网建设流程全解析

AWS CLIcloudwatch list-metrics完全指南：基于 AWS/SNS 命名空间的实际用法与源码解析

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

导读

aws cloudwatch list-metrics是 AWS CLI 中用于枚举 CloudWatch 中现有指标（Metrics）的核心命令。本篇指南以 awscli/examples/cloudwatch/list-metrics.rst 中"列出 Amazon SNS 指标"的官方示例为主线，完整还原命令与输出样例，并结合本仓库中 CloudWatch 服务模型（awscli/botocore/data/cloudwatch/2010-08-01/service-2.json）与分页配置（paginators-1.json），逐一解析--namespace、--metric-name、--dimensions、--recently-active等参数及底层 API 语义。读完本文，你将能熟练地按命名空间、名称与维度过滤指标，理解返回结果中的 Metric/Dimension 结构，并在大结果集下正确使用分页参数。

命令基础：列出 Amazon SNS 的全部指标

官方示例使用--namespace "AWS/SNS"过滤出 Amazon SNS 服务发布到 CloudWatch 的全部指标。命令如下：

aws cloudwatch list-metrics \ --namespace "AWS/SNS"

关键点是：--namespace是精确匹配（exact match）而非前缀匹配。服务模型 service-2.json 对Namespace参数的说明明确指出："The metric namespace to filter against. Only the namespace that matches exactly will be returned."（按命名空间过滤，只有精确匹配的命名空间才会返回）。因此输入AWS/SNS只会返回AWS/SNS命名空间下的指标，而不会顺带返回AWS/SNS-Analytics等其他命名空间。命名空间本身在模型中定义为最长 255 个字符、至少 1 个字符、且不能以冒号开头的字符串（见 Namespace shape）。

完整输出解析

官方示例的真实输出如下（JSON 格式）：

{ "Metrics": [ { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "NotifyMe" } ], "MetricName": "PublishSize" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "CFO" } ], "MetricName": "PublishSize" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "NotifyMe" } ], "MetricName": "NumberOfNotificationsFailed" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "NotifyMe" } ], "MetricName": "NumberOfNotificationsDelivered" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "NotifyMe" } ], "MetricName": "NumberOfMessagesPublished" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "CFO" } ], "MetricName": "NumberOfMessagesPublished" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "CFO" } ], "MetricName": "NumberOfNotificationsDelivered" }, { "Namespace": "AWS/SNS", "Dimensions": [ { "Name": "TopicName", "Value": "CFO" } ], "MetricName": "NumberOfNotificationsFailed" } ] }

这个输出本身就是一个绝佳的"指标身份（Metric Identity）"教学样本：同一命名空间AWS/SNS下，NumberOfMessagesPublished、NumberOfNotificationsDelivered、NumberOfNotificationsFailed、PublishSize等指标，因为TopicName维度取值不同（NotifyMe与CFO两个 SNS 主题），被 CloudWatch 视为不同的指标。这正是服务模型中对 Dimension 的经典定义所解释的行为。

深入理解返回结构：Metric、Namespace 与 Dimension

Metric 的三元身份

list-metrics返回的每个条目都是一个Metric对象。在服务模型中，Metric结构由三个成员构成（见 service-2.json 中 Metric shape）：

输出结构ListMetricsOutput（见 service-2.json）除Metrics列表外，还可能包含NextToken（用于继续翻页）与OwningAccounts（跨账户可观测性场景下各指标所属账户 ID）。

Dimension：构成指标唯一身份的键值对

服务模型对Dimension的说明非常关键（见 service-2.json 中 Dimension shape）：

A dimension is a name/value pair that is part of the identity of a metric. 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 指标以InstanceId为维度名、实际实例 ID 为维度值，SNS 则以TopicName为维度名、主题名称为维度值。

维度约束（同样来自服务模型）：

• Name：1–255 字符，必须为 ASCII，至少包含一个非空白字符，不能以冒号（:）开头，不支持 ASCII 控制字符；
• Value：1–1024 字符，必须为 ASCII，至少包含一个非空白字符，不支持 ASCII 控制字符；
• 单个指标最多可分配 30 个维度（Dimensions列表 max=30）。

正因如此，示例输出中NotifyMe与CFO两个主题各自拥有独立的NumberOfMessagesPublished等指标条目——它们是同一指标名在不同维度取值下的不同变体，可分别进行告警与统计。

过滤参数详解：缩小查询范围

list-metrics的输入结构ListMetricsInput（见 service-2.json）支持以下过滤参数：

按指标名称过滤

当命名空间范围仍然过大时，可叠加--metric-name精确过滤：

aws cloudwatch list-metrics \ --namespace "AWS/SNS" \ --metric-name "NumberOfMessagesPublished"

该参数同样是精确匹配：只有名称完全一致的指标才会返回。MetricName在模型中的定义是 1–255 字符的字符串（见 service-2.json）。

按维度过滤

--dimensions接受Name=Value键值对列表，每个过滤项只要求Name必填（DimensionFilter结构仅将Name列为 required，见 service-2.json）。当只给名称不给值时，匹配"包含该维度名"的所有指标；同时给出名称与值时，则匹配维度名与值都一致的指标。

例如，只查看NotifyMe主题的相关指标：

aws cloudwatch list-metrics \ --namespace "AWS/SNS" \ --dimensions "Name=TopicName,Value=NotifyMe"

值得注意的语义细节：服务模型指出，"If you specify one dimension name and a metric has that dimension and also other dimensions, it will be returned."——只要指标包含你指定的维度（即使它还带有其他维度）也会被返回。这一点与GetMetricData/GetMetricStatistics中必须精确给出全部维度才能取数的行为不同，list-metrics的维度过滤更像一种"包含式"筛选。

只列出近期活跃的指标

--recently-active PT3H可以过滤出过去 3 小时内仍有数据点写入的指标，非常适合清理长期无数据的陈旧指标。RecentlyActiveshape 的唯一合法枚举值就是PT3H（见 service-2.json）。注意服务模型的说明：返回结果是"近似值"，存在一定概率包含数据最后写入时间比指定区间多出最多 50 分钟的指标。

分页与结果量限制

list-metrics属于分页型 API。官方服务模型文档明确：单次调用最多返回 500 条结果（"Up to 500 results are returned for any one call. To retrieve additional results, use the returned token with subsequent calls."）。当指标数量超过 500 时，响应会携带NextToken，将其传给下一次调用的--next-token即可继续取下一页：

aws cloudwatch list-metrics \ --namespace "AWS/SNS" \ --next-token "TOKEN_FROM_PREVIOUS_RESPONSE"

CLI 层面对分页的封装体现在 paginators-1.json 中：

"ListMetrics": { "input_token": "NextToken", "output_token": "NextToken", "result_key": [ "Metrics", "OwningAccounts" ] }

这意味着list-metrics是原生分页操作，而awscli的通用分页机制（见 awscli/customizations/paginate.py）会自动为其注入三个便捷参数：

• --max-items：限制返回的条目总数，配合NextToken自动逐页拉取，直到取满指定数量或数据耗尽；
• --page-size：控制每次底层 API 调用拉取的页大小（最大 500），用于在服务器端限制单页体积；
• --starting-token：等效于手动传NextToken的另一种写法，便于在多次命令之间无缝衔接翻页进度。

例如，只想看前 10 条 SNS 指标：

aws cloudwatch list-metrics \ --namespace "AWS/SNS" \ --max-items 10

另一个值得注意的数据可见性约束同样来自官方服务模型：ListMetrics不返回过去两周内未上报过数据的指标（"ListMetrics doesn't return information about metrics if those metrics haven't reported data in the past two weeks"）。如果需要检索这类历史指标，应改用GetMetricData或GetMetricStatistics直接按已知指标取数。

跨账户可观测性（Cross-Account Observability）

启用 CloudWatch 跨账户可观测性后，list-metrics可在监控账户中列出关联源账户的指标，相关参数语义如下：

• --include-linked-accounts：设为true后返回数据中会混入源账户指标；
• --owning-account：配合前者使用，将结果收敛到指定源账户 ID；
• 响应中的OwningAccounts数组与Metrics数组一一对应（1:1 映射），标明每个指标所属的账户 ID（见 service-2.json）。

aws cloudwatch list-metrics \ --namespace "AWS/SNS" \ --include-linked-accounts \ --owning-account "123456789012"

从列出指标到获取统计数据：与相邻命令的衔接

list-metrics的价值在于"发现"，其结果可直接作为GetMetricData/GetMetricStatistics的输入。官方服务模型在ListMetrics操作文档中明确写道：返回的指标可与GetMetricData或GetMetricStatistics配合使用以获取统计值，且指标创建后最多需要约 15 分钟才会出现在列表中；如需更早看到统计值，应直接使用后两个命令。

本仓库配套的相邻示例可帮助你衔接完整工作流：

• 用 get-metric-statistics.rst 拉取单个指标的时间序列统计；
• 用 get-metric-data.rst 批量查询多条指标数据；
• 用 describe-alarms-for-metric.rst 查看已针对某指标配置的告警；
• 需要上报自定义指标后再验证是否出现时，可参考 put-metric-data.rst。

实用技巧小结

1. 命名空间、指标名都是精确匹配，写错大小写或多了空格就会返回空结果；
2. 维度组合决定指标身份，同一指标名在不同TopicName下是不同指标，过滤时务必带上维度；
3. 超过 500 条结果时记得翻页，优先使用--max-items让 CLI 自动翻页；
4. 两周无数据的指标默认不可见，需要历史数据请改用取数类命令；
5. 维度过滤是"包含式"匹配，指定单个维度名即可命中同时带有其他维度的指标，这与取数时必须给全维度的规则不同。

相关资源

• 官方示例原文：awscli/examples/cloudwatch/list-metrics.rst
• CloudWatch 服务模型（全部操作与 shape 定义）：awscli/botocore/data/cloudwatch/2010-08-01/service-2.json
• 分页配置（NextToken与 result_key 声明）：awscli/botocore/data/cloudwatch/2010-08-01/paginators-1.json
• CLI 分页参数注入实现（--max-items/--page-size/--starting-token）：awscli/customizations/paginate.py
• CloudWatch 全部 CLI 示例目录：awscli/examples/cloudwatch/

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