CloudWatchメトリクスのデータポイントをAWS CLIで取得する

こんにちは、CX事業本部 IoT事業部の若槻です。

今回は、Amazon CloudWatchメトリクスのデータポイントをAWS CLIで取得する機会があったので方法を確認してみました。

取得対象のメトリクス

以前書いた下記エントリで作成した構成で発行されるメトリクスから取得してみます。

• AWS Step FunctionsステートマシンでCloudWatchメトリクスを発行する | DevelopersIO

メトリクスは下記の通りです。

• NameSpace：StateMachinePublish
• MericName：temperature
• Dimension：
  • Name：Site
  • Value：site_01
• 発行間隔：1分

やってみる

AWS CLIで取得してみます。get-metric-statisticsでは一度のAPIコールで最大1440のデータポイントが取得可能です。

• get-metric-statistics — AWS CLI 1.22.14 Command Reference

Synopsisは下記の通りです。

  get-metric-statistics
--namespace <value>
--metric-name <value>
[--dimensions <value>]
--start-time <value>
--end-time <value>
--period <value>
[--statistics <value>]
[--extended-statistics <value>]
[--unit <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]

必須となっているパラメータを指定して実行してみると、エラーとなりました。

$ aws cloudwatch get-metric-statistics \
  --namespace 'StateMachinePublish' \
  --metric-name 'temperature' \
  --start-time '2021-11-30T14:00:00Z' \
  --end-time '2021-11-30T15:00:00Z' \
  --period 60

An error occurred (InvalidParameterCombination) when calling the GetMetricStatistics operation: At least one of the parameters Statistics and ExtendedStatistics must be specified.

StatisticsまたはExtendedStatisticsパラメータのいずれかの指定が必須のようです。また指定可能なのは下記となります。

• SampleCount
• Average
• Sum
• Minimum
• Maximum

今回は1分毎に1つのメトリクスがPutされるのでstatisticsオプションでMaximumを指定して実行してみます。

$ aws cloudwatch get-metric-statistics \
  --namespace 'StateMachinePublish' \
  --metric-name 'temperature' \
  --start-time '2021-11-30T14:00:00Z' \
  --end-time '2021-11-30T15:00:00Z' \
  --period 60 \
  --statistics Maximum

{
    "Label": "temperature",
    "Datapoints": []
}

するとコマンドはエラーなく実行できましたがデータポイントは一つも取得できませんでした。どうやらディメンジョンを持つメトリクスの場合は明示的にName/Valueを指定する必要があるようです。

dimensionsオプションを指定して実行してみます。

$ aws cloudwatch get-metric-statistics \
  --namespace 'StateMachinePublish' \
  --metric-name 'temperature' \
  --start-time '2021-11-30T14:00:00Z' \
  --end-time '2021-11-30T15:00:00Z' \
  --period 60 \
  --statistics Maximum \
  --dimensions Name=Site,Value=site_01

{
    "Label": "temperature",
    "Datapoints": [
        {
            "Timestamp": "2021-11-30T14:20:00+00:00",
            "Maximum": 3.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:28:00+00:00",
            "Maximum": 3.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:21:00+00:00",
            "Maximum": 9.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:30:00+00:00",
            "Maximum": 4.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:29:00+00:00",
            "Maximum": 9.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:31:00+00:00",
            "Maximum": 10.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:22:00+00:00",
            "Maximum": 12.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:23:00+00:00",
            "Maximum": 26.0,
            "Unit": "None"
        },
        （中略） 
    ]
}

すると今度こそデータポイントを取得できました。ちなみにデータポイントの並び順はTimestamp順とはなっていなかったので行いたい処理によってはソートが必要そうです。

statisticsを同時に複数指定する

statisticsは複数の値をリスト形式で同時に指定可能です。periodを120秒とし、statisticsに全種類の値を指定して実行してみます。

$ aws cloudwatch get-metric-statistics \
  --namespace 'StateMachinePublish' \
  --metric-name 'temperature' \
  --start-time '2021-11-30T14:50:00Z' \
  --end-time '2021-11-30T15:00:00Z' \
  --period 120 \
  --dimensions Name=Site,Value=site_01 \
  --statistics SampleCount Average Sum Minimum Maximum

{
    "Label": "temperature",
    "Datapoints": [
        {
            "Timestamp": "2021-11-30T14:50:00+00:00",
            "SampleCount": 2.0,
            "Average": 12.5,
            "Sum": 25.0,
            "Minimum": 7.0,
            "Maximum": 18.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:52:00+00:00",
            "SampleCount": 2.0,
            "Average": 9.0,
            "Sum": 18.0,
            "Minimum": 6.0,
            "Maximum": 12.0,
            "Unit": "None"
        },
        {
            "Timestamp": "2021-11-30T14:54:00+00:00",
            "SampleCount": 2.0,
            "Average": 24.5,
            "Sum": 49.0,
            "Minimum": 24.0,
            "Maximum": 25.0,
            "Unit": "None"
        }
    ]
}

データポイントごとに各種Statisticの値が取得できていますね。

GetMetricStatisticsとGetMetricDataを使い分ける

メトリクスのデータを取得するAPIには、GetMetricStatisticsの他にGetMetricDataというものがあり、こちらの方の使用が推奨されているとのことです。

• GetMetricData または GetMetricStatistics を使用して CloudWatch メトリクスからデータポイントを取得する

理由は下記のほかに1APIコールで取得できるメトリクス数が、GetMetricStatisticsが1つなのに対しGetMetricDataは500取得できます。

GetMetricStatistics ではなく GetMetricData API を使用するのがベストプラクティスです。なぜなら、GetMetricData を使用すると、大規模かつより高速にデータを取得できるからです。 また、GetMetricData は Metric Math をサポートしているほか、順番付けされページ分割された結果を返します。

ただしGetMetricDataはデータポイントを取得するためのクエリをローカルにJsonファイルで定義する必要があります。場合によってはこのクエリの指定方法が手間となることもあるので、大規模な取得でないのであればGetMetricStatisticsで済ませるという使い分けで良いかと思います。

以上