AWS CLI 实战使用 aws cloudwatch get-metric-data 批量查询指标与 Metric Math 表达式【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cliaws cloudwatch get-metric-data是 AWS CLI 中通过一次请求批量获取多条 CloudWatch 指标时间序列、并支持对返回数据执行 metric math指标数学表达式运算的核心命令。本指南以仓库内 get-metric-data.rst 官方示例为主体结合 AWS CLI 内置的 CloudWatch 服务模型 service-2.json 进行源码级剖析帮助你掌握--metric-data-queries的完整 JSON 结构与各参数语义并学会用表达式聚合 EBS 读写 IOPS、监控 AWS 账单等真实场景。命令概览一条命令查询多组指标get-metric-data对应 CloudWatch 的GetMetricDataAPI。与一次只能查询单条指标、单种统计的get-metric-statistics不同它在单次调用中最多支持500 个MetricDataQuery结构每个结构既可以指定一条原始指标也可以是一个 metric math 表达式或 Metrics Insights 查询总数据点数上限为100,800该限制定义于 service-2.json 中GetMetricData操作的文档描述。命令的基本形态如下aws cloudwatch get-metric-data \ --metric-data-queries file://file.json \ --start-time 2024-09-29T22:10:00Z \ --end-time 2024-09-29T22:15:00Z三个必填参数为--metric-data-queries、--start-time与--end-time在服务模型中由GetMetricDataInput的required字段强制声明见 service-2.json。查询定义既可以像上面这样通过file://引用本地 JSON 文件也可以直接内联传入 JSON 字符串。示例一用 Metric Math 计算 EC2 平均总 IOPS原文给出的第一个示例是为 EC2 实例i-abcdef同时抓取EBSReadOpsEBS 读操作与EBSWriteOpsEBS 写操作两条指标再用表达式(m1m2)/300算出该时间窗口内的平均总 IOPS并只返回这个表达式的结果。查询文件结构--metric-data-queries指向的file.json内容如下[ { Id: m3, Expression: (m1m2)/300, Label: Avg Total IOPS }, { Id: m1, MetricStat: { Metric: { Namespace: AWS/EC2, MetricName: EBSReadOps, Dimensions: [ { Name: InstanceId, Value: i-abcdef } ] }, Period: 300, Stat: Sum, Unit: Count }, ReturnData: false }, { Id: m2, MetricStat: { Metric: { Namespace: AWS/EC2, MetricName: EBSWriteOps, Dimensions: [ { Name: InstanceId, Value: i-abcdef } ] }, Period: 300, Stat: Sum, Unit: Count }, ReturnData: false } ]这份 JSON 展示了MetricDataQuery的两种形态指标查询MetricStatm1与m2通过MetricStat描述要检索的原始指标。其中Metric部分声明Namespace命名空间、MetricName指标名与Dimensions维度数组每条维度由Name/Value键值对组成Period为数据点粒度300 秒即 5 分钟Stat为聚合统计SumUnit为单位Count。这两条查询的ReturnData均设为false表示它们只作为表达式的输入不直接出现在最终输出中。数学表达式Expressionm3通过Expression字段引用其他查询的Id参与运算。表达式里引用的m1、m2正是上面两条指标查询的Id这是 metric math 的关联机制——Id既是响应中的标识也是表达式中的变量名。Label为Avg Total IOPS作为人类可读的标签展示在结果中。执行与输出aws cloudwatch get-metric-data \ --metric-data-queries file://file.json \ --start-time 2024-09-29T22:10:00Z \ --end-time 2024-09-29T22:15:00Z输出如下{ MetricDataResults: [ { Id: m3, Label: Avg Total IOPS, Timestamps: [ 2024-09-29T22:10:0000:00 ], Values: [ 96.85 ], StatusCode: Complete } ], Messages: [] }由于m1、m2的ReturnData为falseMetricDataResults中只包含表达式m3的结果时间戳22:10:00处平均总 IOPS 为96.85StatusCode为Complete表示请求时间范围内所有数据点均已返回。从表达式(m1m2)/300可以反推计算逻辑两条Sum统计各代表 300 秒周期内的累计操作数相加后除以 300 秒即得到每秒平均 IOPS。关键参数语义解析依据 service-2.json 中MetricDataQuery结构的定义各字段语义如下字段是否必填语义与约束Id是唯一标识该查询的短名用于关联响应结果也可作为数学表达式中的变量。合法字符为字母、数字和下划线首字符必须是小写字母长度 1–255MetricStat二选一描述要检索的指标及统计方式。仅在查询原始指标时使用Expression二选一metric math 表达式如(m1m2)/300或 Metrics Insights 查询。表达式可通过其他查询的Id引用其数据或结果最长 2048 字符Label否该指标或表达式的人类可读标签会显示在 CloudWatch 仪表盘组件中省略时由 CloudWatch 生成默认标签ReturnData否是否在响应中返回该查询的时间戳与原始值。仅用于支撑表达式运算时设为false缺省为truePeriod否返回数据点的粒度秒。常规分辨率指标最短 60 秒且须为 60 的倍数高分辨率指标StorageResolution1发布可为 1、5、10、20、30、60 或 60 的倍数AccountId否指标所在账户 ID。在监控账户中执行GetMetricData时用它指定从哪个账户检索指标需要特别强调的是在同一个MetricDataQuery对象中MetricStat与Expression只能二选一不能同时出现——模型文档对此有明确约束。示例二监控 AWS 预估账单Billing 指标第二个示例演示从AWS/Billing命名空间查询EstimatedCharges指标用于监控账户的预估费用。与示例一不同这里把整个查询定义以内联 JSON 字符串的形式直接写在命令行中aws cloudwatch get-metric-data \ --metric-data-queries [{Id:m1,MetricStat:{Metric:{Namespace:AWS/Billing,MetricName:EstimatedCharges,Dimensions:[{Name:Currency,Value:USD}]},Period:21600,Stat:Maximum}}] \ --start-time 2024-09-26T12:00:00Z \ --end-time 2024-09-26T18:00:00Z \ --region us-east-1该查询只定义了一条MetricStat指标查询Namespace为AWS/BillingMetricName为EstimatedChargesDimensions指定CurrencyUSD币种为美元Period为21600 秒6 小时Stat为Maximum即返回每个 6 小时窗口内该指标的最大值显式指定--region us-east-1因为账单指标仅在us-east-1美东 1 区可用。输出结果{ MetricDataResults: [ { Id: m1, Label: EstimatedCharges, Timestamps: [ 2024-09-26T12:00:0000:00 ], Values: [ 542.38 ], StatusCode: Complete } ], Messages: [] }从结果可见2024-09-26 12:00:00 时刻对应的预估账单为542.38美元。此用法非常适合与put-metric-alarm配合构建费用超过阈值即告警的成本监控体系。深入理解时间范围、数据保留与分页StartTime 与 EndTime 的包含/排除语义GetMetricDataInput对两个时间参数有精确的语义界定见 service-2.jsonStartTime是包含inclusive的结果包含该时间戳对应的数据点且 CloudWatch 会向下取整——15 天内的数据取整到最近整分钟15–63 天前取整到最近 5 分钟刻度63 天前取整到最近整点EndTime是排除exclusive的结果只包含截止到该时间戳之前的数据点为了获得更好的性能建议让起止时间与指标的Period对齐如 5 分钟粒度的指标使用 12:05、12:30 这类整刻度时刻作为起止时间。数据保留周期CloudWatch 对不同粒度的数据点有不同的保留期限这在GetMetricData的操作文档中有明确规定数据点周期保留时长小于 60 秒高分辨率仅限自定义指标StorageResolution13 小时60 秒1 分钟15 天300 秒5 分钟63 天3600 秒1 小时455 天15 个月超过保留期后更短周期的数据会按更粗粒度聚合如 1 分钟数据在 15 天后只能按 5 分钟分辨率、63 天后只能按 1 小时分辨率检索查询时必须选择合适的Period才能取到数据。分页控制当返回数据点超过单次上限时可用以下参数控制分页ScanBy数据点返回顺序。TimestampDescending默认最新的在前或TimestampAscending最旧的在前MaxDatapoints分页前最多返回的数据点数缺省为100,800NextToken将上一次调用的返回值原样传入即可获取下一批数据点。响应中的StatusCode也与此相关Complete表示时间范围内数据点已全部返回PartialData表示仅返回了不完整的数据点可用NextToken继续请求InternalError表示出错需要重试。此外如果执行的是数学表达式则不会返回NextToken。顶层的Messages字段则承载与整个操作相关的提示信息例如超过允许的最大指标数。源码佐证服务模型如何定义 GetMetricData以上所有参数语义均可在 AWS CLI 内置的 CloudWatch 服务模型 service-2.json 中逐条核对GetMetricData操作#L376-L391为POST /请求唯一声明的错误是InvalidNextTokenGetMetricDataInput#L2364-L2401声明MetricDataQueries、StartTime、EndTime为必填并定义NextToken、ScanBy、MaxDatapoints、LabelOptions内含Timezone用于按本地时区显示标签时间MetricDataQuery#L3578-L3611与MetricDataResult#L3613-L3641分别约束了请求与响应两端的结构。从结构上看MetricDataQuery还被PutMetricAlarm复用在为基于 metric math 表达式的告警建模时数组中 20 个结构里必须有一个ReturnDatatrue的表达式结果作为告警监控对象其余全部设为false——这与get-metric-data中的ReturnData用法完全一致。从源码结构可以推断掌握MetricDataQuery这一结构等于同时掌握了批量取数与基于表达式的告警配置两套能力。与 get-metric-statistics 的对比何时选用哪个仓库中的另一个示例 get-metric-statistics.rst 展示了旧式取数命令的形态aws cloudwatch get-metric-statistics --metric-name CPUUtilization --start-time 2014-04-08T23:18:00Z --end-time 2014-04-09T23:18:00Z --period 3600 --namespace AWS/EC2 --statistics Maximum --dimensions NameInstanceId,Valuei-abcdef两者的关键差异维度get-metric-statisticsget-metric-data单次查询指标数单条指标、单种统计最多 500 个查询可混合指标、表达式与 Metrics Insights单次数据点上限1,440100,800指标数学表达式不支持支持通过Expression返回顺序不保证按时间排序可用ScanBy控制计费独立计费与GetMetricStatistics不同的计费结构从服务模型可见get-metric-statistics对应GetMetricStatistics见 service-2.json需要分别指定--namespace、--metric-name、--statistics、--period等扁平参数超过 1,440 个数据点即报错而get-metric-data将所有查询统一收敛到--metric-data-queries一个参数中天然适合批量取数与多指标联合计算。因此需要抓取单个指标的历史统计数据时可用前者而涉及多指标批量拉取、表达式运算或大时间窗口查询时应优先选择get-metric-data。小结aws cloudwatch get-metric-data是面向 CloudWatch 数据检索的批量级、表达式级能力批量取数单次最多 500 个MetricDataQuery、100,800 个数据点配合ScanBy/MaxDatapoints/NextToken完成分页遍历指标数学通过Expression引用其他查询的Id做四则运算与函数变换ReturnDatafalse可让中间指标只做输入不出现在结果中统一模型查询结构与PutMetricAlarm复用同一套MetricDataQuery取数与告警配置可以共享同一份 JSON 定义。文中两个可直接落地的示例均来自仓库 awscli/examples/cloudwatch/get-metric-data.rst服务模型字段与语义可对照 awscli/botocore/data/cloudwatch/2010-08-01/service-2.json 进一步核查更多 CloudWatch 命令示例告警、仪表盘、指标流等可在 awscli/examples/cloudwatch 目录下继续探索。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AWS CLI 实战：使用 aws cloudwatch get-metric-data 批量查询指标与 Metric Math 表达式
AWS CLI 实战使用 aws cloudwatch get-metric-data 批量查询指标与 Metric Math 表达式【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cliaws cloudwatch get-metric-data是 AWS CLI 中通过一次请求批量获取多条 CloudWatch 指标时间序列、并支持对返回数据执行 metric math指标数学表达式运算的核心命令。本指南以仓库内 get-metric-data.rst 官方示例为主体结合 AWS CLI 内置的 CloudWatch 服务模型 service-2.json 进行源码级剖析帮助你掌握--metric-data-queries的完整 JSON 结构与各参数语义并学会用表达式聚合 EBS 读写 IOPS、监控 AWS 账单等真实场景。命令概览一条命令查询多组指标get-metric-data对应 CloudWatch 的GetMetricDataAPI。与一次只能查询单条指标、单种统计的get-metric-statistics不同它在单次调用中最多支持500 个MetricDataQuery结构每个结构既可以指定一条原始指标也可以是一个 metric math 表达式或 Metrics Insights 查询总数据点数上限为100,800该限制定义于 service-2.json 中GetMetricData操作的文档描述。命令的基本形态如下aws cloudwatch get-metric-data \ --metric-data-queries file://file.json \ --start-time 2024-09-29T22:10:00Z \ --end-time 2024-09-29T22:15:00Z三个必填参数为--metric-data-queries、--start-time与--end-time在服务模型中由GetMetricDataInput的required字段强制声明见 service-2.json。查询定义既可以像上面这样通过file://引用本地 JSON 文件也可以直接内联传入 JSON 字符串。示例一用 Metric Math 计算 EC2 平均总 IOPS原文给出的第一个示例是为 EC2 实例i-abcdef同时抓取EBSReadOpsEBS 读操作与EBSWriteOpsEBS 写操作两条指标再用表达式(m1m2)/300算出该时间窗口内的平均总 IOPS并只返回这个表达式的结果。查询文件结构--metric-data-queries指向的file.json内容如下[ { Id: m3, Expression: (m1m2)/300, Label: Avg Total IOPS }, { Id: m1, MetricStat: { Metric: { Namespace: AWS/EC2, MetricName: EBSReadOps, Dimensions: [ { Name: InstanceId, Value: i-abcdef } ] }, Period: 300, Stat: Sum, Unit: Count }, ReturnData: false }, { Id: m2, MetricStat: { Metric: { Namespace: AWS/EC2, MetricName: EBSWriteOps, Dimensions: [ { Name: InstanceId, Value: i-abcdef } ] }, Period: 300, Stat: Sum, Unit: Count }, ReturnData: false } ]这份 JSON 展示了MetricDataQuery的两种形态指标查询MetricStatm1与m2通过MetricStat描述要检索的原始指标。其中Metric部分声明Namespace命名空间、MetricName指标名与Dimensions维度数组每条维度由Name/Value键值对组成Period为数据点粒度300 秒即 5 分钟Stat为聚合统计SumUnit为单位Count。这两条查询的ReturnData均设为false表示它们只作为表达式的输入不直接出现在最终输出中。数学表达式Expressionm3通过Expression字段引用其他查询的Id参与运算。表达式里引用的m1、m2正是上面两条指标查询的Id这是 metric math 的关联机制——Id既是响应中的标识也是表达式中的变量名。Label为Avg Total IOPS作为人类可读的标签展示在结果中。执行与输出aws cloudwatch get-metric-data \ --metric-data-queries file://file.json \ --start-time 2024-09-29T22:10:00Z \ --end-time 2024-09-29T22:15:00Z输出如下{ MetricDataResults: [ { Id: m3, Label: Avg Total IOPS, Timestamps: [ 2024-09-29T22:10:0000:00 ], Values: [ 96.85 ], StatusCode: Complete } ], Messages: [] }由于m1、m2的ReturnData为falseMetricDataResults中只包含表达式m3的结果时间戳22:10:00处平均总 IOPS 为96.85StatusCode为Complete表示请求时间范围内所有数据点均已返回。从表达式(m1m2)/300可以反推计算逻辑两条Sum统计各代表 300 秒周期内的累计操作数相加后除以 300 秒即得到每秒平均 IOPS。关键参数语义解析依据 service-2.json 中MetricDataQuery结构的定义各字段语义如下字段是否必填语义与约束Id是唯一标识该查询的短名用于关联响应结果也可作为数学表达式中的变量。合法字符为字母、数字和下划线首字符必须是小写字母长度 1–255MetricStat二选一描述要检索的指标及统计方式。仅在查询原始指标时使用Expression二选一metric math 表达式如(m1m2)/300或 Metrics Insights 查询。表达式可通过其他查询的Id引用其数据或结果最长 2048 字符Label否该指标或表达式的人类可读标签会显示在 CloudWatch 仪表盘组件中省略时由 CloudWatch 生成默认标签ReturnData否是否在响应中返回该查询的时间戳与原始值。仅用于支撑表达式运算时设为false缺省为truePeriod否返回数据点的粒度秒。常规分辨率指标最短 60 秒且须为 60 的倍数高分辨率指标StorageResolution1发布可为 1、5、10、20、30、60 或 60 的倍数AccountId否指标所在账户 ID。在监控账户中执行GetMetricData时用它指定从哪个账户检索指标需要特别强调的是在同一个MetricDataQuery对象中MetricStat与Expression只能二选一不能同时出现——模型文档对此有明确约束。示例二监控 AWS 预估账单Billing 指标第二个示例演示从AWS/Billing命名空间查询EstimatedCharges指标用于监控账户的预估费用。与示例一不同这里把整个查询定义以内联 JSON 字符串的形式直接写在命令行中aws cloudwatch get-metric-data \ --metric-data-queries [{Id:m1,MetricStat:{Metric:{Namespace:AWS/Billing,MetricName:EstimatedCharges,Dimensions:[{Name:Currency,Value:USD}]},Period:21600,Stat:Maximum}}] \ --start-time 2024-09-26T12:00:00Z \ --end-time 2024-09-26T18:00:00Z \ --region us-east-1该查询只定义了一条MetricStat指标查询Namespace为AWS/BillingMetricName为EstimatedChargesDimensions指定CurrencyUSD币种为美元Period为21600 秒6 小时Stat为Maximum即返回每个 6 小时窗口内该指标的最大值显式指定--region us-east-1因为账单指标仅在us-east-1美东 1 区可用。输出结果{ MetricDataResults: [ { Id: m1, Label: EstimatedCharges, Timestamps: [ 2024-09-26T12:00:0000:00 ], Values: [ 542.38 ], StatusCode: Complete } ], Messages: [] }从结果可见2024-09-26 12:00:00 时刻对应的预估账单为542.38美元。此用法非常适合与put-metric-alarm配合构建费用超过阈值即告警的成本监控体系。深入理解时间范围、数据保留与分页StartTime 与 EndTime 的包含/排除语义GetMetricDataInput对两个时间参数有精确的语义界定见 service-2.jsonStartTime是包含inclusive的结果包含该时间戳对应的数据点且 CloudWatch 会向下取整——15 天内的数据取整到最近整分钟15–63 天前取整到最近 5 分钟刻度63 天前取整到最近整点EndTime是排除exclusive的结果只包含截止到该时间戳之前的数据点为了获得更好的性能建议让起止时间与指标的Period对齐如 5 分钟粒度的指标使用 12:05、12:30 这类整刻度时刻作为起止时间。数据保留周期CloudWatch 对不同粒度的数据点有不同的保留期限这在GetMetricData的操作文档中有明确规定数据点周期保留时长小于 60 秒高分辨率仅限自定义指标StorageResolution13 小时60 秒1 分钟15 天300 秒5 分钟63 天3600 秒1 小时455 天15 个月超过保留期后更短周期的数据会按更粗粒度聚合如 1 分钟数据在 15 天后只能按 5 分钟分辨率、63 天后只能按 1 小时分辨率检索查询时必须选择合适的Period才能取到数据。分页控制当返回数据点超过单次上限时可用以下参数控制分页ScanBy数据点返回顺序。TimestampDescending默认最新的在前或TimestampAscending最旧的在前MaxDatapoints分页前最多返回的数据点数缺省为100,800NextToken将上一次调用的返回值原样传入即可获取下一批数据点。响应中的StatusCode也与此相关Complete表示时间范围内数据点已全部返回PartialData表示仅返回了不完整的数据点可用NextToken继续请求InternalError表示出错需要重试。此外如果执行的是数学表达式则不会返回NextToken。顶层的Messages字段则承载与整个操作相关的提示信息例如超过允许的最大指标数。源码佐证服务模型如何定义 GetMetricData以上所有参数语义均可在 AWS CLI 内置的 CloudWatch 服务模型 service-2.json 中逐条核对GetMetricData操作#L376-L391为POST /请求唯一声明的错误是InvalidNextTokenGetMetricDataInput#L2364-L2401声明MetricDataQueries、StartTime、EndTime为必填并定义NextToken、ScanBy、MaxDatapoints、LabelOptions内含Timezone用于按本地时区显示标签时间MetricDataQuery#L3578-L3611与MetricDataResult#L3613-L3641分别约束了请求与响应两端的结构。从结构上看MetricDataQuery还被PutMetricAlarm复用在为基于 metric math 表达式的告警建模时数组中 20 个结构里必须有一个ReturnDatatrue的表达式结果作为告警监控对象其余全部设为false——这与get-metric-data中的ReturnData用法完全一致。从源码结构可以推断掌握MetricDataQuery这一结构等于同时掌握了批量取数与基于表达式的告警配置两套能力。与 get-metric-statistics 的对比何时选用哪个仓库中的另一个示例 get-metric-statistics.rst 展示了旧式取数命令的形态aws cloudwatch get-metric-statistics --metric-name CPUUtilization --start-time 2014-04-08T23:18:00Z --end-time 2014-04-09T23:18:00Z --period 3600 --namespace AWS/EC2 --statistics Maximum --dimensions NameInstanceId,Valuei-abcdef两者的关键差异维度get-metric-statisticsget-metric-data单次查询指标数单条指标、单种统计最多 500 个查询可混合指标、表达式与 Metrics Insights单次数据点上限1,440100,800指标数学表达式不支持支持通过Expression返回顺序不保证按时间排序可用ScanBy控制计费独立计费与GetMetricStatistics不同的计费结构从服务模型可见get-metric-statistics对应GetMetricStatistics见 service-2.json需要分别指定--namespace、--metric-name、--statistics、--period等扁平参数超过 1,440 个数据点即报错而get-metric-data将所有查询统一收敛到--metric-data-queries一个参数中天然适合批量取数与多指标联合计算。因此需要抓取单个指标的历史统计数据时可用前者而涉及多指标批量拉取、表达式运算或大时间窗口查询时应优先选择get-metric-data。小结aws cloudwatch get-metric-data是面向 CloudWatch 数据检索的批量级、表达式级能力批量取数单次最多 500 个MetricDataQuery、100,800 个数据点配合ScanBy/MaxDatapoints/NextToken完成分页遍历指标数学通过Expression引用其他查询的Id做四则运算与函数变换ReturnDatafalse可让中间指标只做输入不出现在结果中统一模型查询结构与PutMetricAlarm复用同一套MetricDataQuery取数与告警配置可以共享同一份 JSON 定义。文中两个可直接落地的示例均来自仓库 awscli/examples/cloudwatch/get-metric-data.rst服务模型字段与语义可对照 awscli/botocore/data/cloudwatch/2010-08-01/service-2.json 进一步核查更多 CloudWatch 命令示例告警、仪表盘、指标流等可在 awscli/examples/cloudwatch 目录下继续探索。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考