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 与 DimensionMetric 的三元身份list-metrics返回的每个条目都是一个Metric对象。在服务模型中Metric结构由三个成员构成见 service-2.json 中 Metric shape字段类型说明Namespace字符串1–255 字符指标所属命名空间如AWS/SNS、AWS/EC2、AWS/LambdaMetricName字符串1–255 字符必填指标名称如NumberOfMessagesPublishedDimensions列表最多 30 个该指标的维度数组输出结构ListMetricsOutput见 service-2.json除Metrics列表外还可能包含NextToken用于继续翻页与OwningAccounts跨账户可观测性场景下各指标所属账户 ID。Dimension构成指标唯一身份的键值对服务模型对Dimension的说明非常关键见 service-2.json 中 Dimension shapeA 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为维度名、主题名称为维度值。维度约束同样来自服务模型Name1–255 字符必须为 ASCII至少包含一个非空白字符不能以冒号:开头不支持 ASCII 控制字符Value1–1024 字符必须为 ASCII至少包含一个非空白字符不支持 ASCII 控制字符单个指标最多可分配 30 个维度Dimensions列表 max30。正因如此示例输出中NotifyMe与CFO两个主题各自拥有独立的NumberOfMessagesPublished等指标条目——它们是同一指标名在不同维度取值下的不同变体可分别进行告警与统计。过滤参数详解缩小查询范围list-metrics的输入结构ListMetricsInput见 service-2.json支持以下过滤参数参数对应 shape行为说明--namespaceNamespace按命名空间精确匹配--metric-nameMetricName按指标名称精确匹配Only the metrics with names that match exactly will be returned--dimensionsDimensionFilters按维度过滤支持最多 10 个维度过滤项见 DimensionFilters shape--next-tokenNextToken上一次调用返回的分页令牌--recently-activeRecentlyActive仅支持唯一合法值PT3H只返回过去 3 小时内发布过数据点的指标--include-linked-accountsIncludeLinkedAccounts在监控账户中使用时设为true将关联源账户的指标一并返回默认false--owning-accountAccountId在监控账户中指定某个源账户 ID仅返回该账户的指标需同时将--include-linked-accounts设为true按指标名称过滤当命名空间范围仍然过大时可叠加--metric-name精确过滤aws cloudwatch list-metrics \ --namespace AWS/SNS \ --metric-name NumberOfMessagesPublished该参数同样是精确匹配只有名称完全一致的指标才会返回。MetricName在模型中的定义是 1–255 字符的字符串见 service-2.json。按维度过滤--dimensions接受NameValue键值对列表每个过滤项只要求Name必填DimensionFilter结构仅将Name列为 required见 service-2.json。当只给名称不给值时匹配包含该维度名的所有指标同时给出名称与值时则匹配维度名与值都一致的指标。例如只查看NotifyMe主题的相关指标aws cloudwatch list-metrics \ --namespace AWS/SNS \ --dimensions NameTopicName,ValueNotifyMe值得注意的语义细节服务模型指出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_RESPONSECLI 层面对分页的封装体现在 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 doesnt return information about metrics if those metrics havent 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。实用技巧小结命名空间、指标名都是精确匹配写错大小写或多了空格就会返回空结果维度组合决定指标身份同一指标名在不同TopicName下是不同指标过滤时务必带上维度超过 500 条结果时记得翻页优先使用--max-items让 CLI 自动翻页两周无数据的指标默认不可见需要历史数据请改用取数类命令维度过滤是包含式匹配指定单个维度名即可命中同时带有其他维度的指标这与取数时必须给全维度的规则不同。相关资源官方示例原文awscli/examples/cloudwatch/list-metrics.rstCloudWatch 服务模型全部操作与 shape 定义awscli/botocore/data/cloudwatch/2010-08-01/service-2.json分页配置NextToken与 result_key 声明awscli/botocore/data/cloudwatch/2010-08-01/paginators-1.jsonCLI 分页参数注入实现--max-items/--page-size/--starting-tokenawscli/customizations/paginate.pyCloudWatch 全部 CLI 示例目录awscli/examples/cloudwatch/【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考