メトリクスを指定する4つの要素

CloudWatch のメトリクスは、次の4つを組み合わせて指定する。コンソールのグラフで見ている値も、裏ではこの組み合わせで取り出されている。

要素意味例
名前空間(Namespace)どのサービスのメトリクスかAWS/EC2
メトリクス名(MetricName)何を測ったかCPUUtilization
ディメンション(Dimensions)どのリソースかInstanceId=i-0123…
期間と統計(Period / Stat)何秒単位で、どう集計するか300秒ごとの Average

よく使うメトリクスとディメンションは次のとおりだ。

サービス名前空間主なメトリクスディメンション
EC2AWS/EC2CPUUtilization、NetworkIn、NetworkOutInstanceId
RDSAWS/RDSCPUUtilization、FreeStorageSpace、DatabaseConnectionsDBInstanceIdentifier
LambdaAWS/LambdaInvocations、Errors、Duration、ThrottlesFunctionName
ALBAWS/ApplicationELBRequestCount、HTTPCode_Target_5XX_CountLoadBalancer
S3AWS/S3BucketSizeBytes、NumberOfObjects(1日1回)BucketName、StorageType

ディメンションの名前や値が分からないときは、list_metrics で実際に存在する組み合わせを調べる。メモリ使用率のように CloudWatch エージェントを入れないと存在しないメトリクスもあるので、まずここで確かめるとよい。

list_metrics.py
import boto3

session = boto3.Session(profile_name="dev", region_name="ap-northeast-1")
cw = session.client("cloudwatch")

paginator = cw.get_paginator("list_metrics")
for page in paginator.paginate(Namespace="AWS/RDS", MetricName="CPUUtilization"):
    for m in page["Metrics"]:
        print(m["Dimensions"])
出力例
[{'Name': 'DBInstanceIdentifier', 'Value': 'app-db'}]
[{'Name': 'EngineName', 'Value': 'postgres'}]
[{'Name': 'DatabaseClass', 'Value': 'db.t4g.medium'}]

同じ CPUUtilization でも、インスタンス単位・エンジン単位・クラス単位と、ディメンションの違う複数のメトリクスがあることが分かる。list_metrics が返すのは、直近2週間にデータがあったメトリクスだけである点にも注意したい。

get_metric_data と get_metric_statistics

値を取り出すAPIは2つある。新しく書くなら get_metric_data を使う。

get_metric_statisticsget_metric_data
1回で取れるメトリクス1つ最大500(クエリの数)
計算式不可可(例: エラー数 ÷ 呼び出し数 × 100)
ページングなし(1回の上限は1,440データポイント)あり(Paginator 対応)
課金APIリクエスト数(無料枠あり)取得したメトリクス数(無料枠の対象外)

インスタンスが50台あれば、get_metric_statistics は50回の呼び出しが必要だが、get_metric_data は1回にまとめられる。料金の単価は改定されることがあるので、最新の値は CloudWatch の料金ページで確認してほしい。

実践:CPU使用率が低いEC2を洗い出す

起動中のEC2について、過去14日間の CPU 使用率の平均と最大を求め、最大でも10%未満のインスタンスをサイズダウンの候補として出力する。get_metric_data の1回のクエリに全インスタンスを詰め込むのがポイントだ。

cpu_report.py
"""起動中のEC2の過去14日間のCPU使用率(平均・最大)を出し、低負荷の候補を表示する。"""
from datetime import datetime, timedelta, timezone

import boto3

DAYS = 14
THRESHOLD = 10.0   # 最大CPU使用率(%)がこれ未満なら候補

session = boto3.Session(profile_name="dev", region_name="ap-northeast-1")
ec2 = session.client("ec2")
cw = session.client("cloudwatch")

# 1) 起動中のインスタンスを集める
instances = {}
running = [{"Name": "instance-state-name", "Values": ["running"]}]
for inst in ec2.get_paginator("describe_instances").paginate(Filters=running).search("Reservations[].Instances[]"):
    name = next((t["Value"] for t in inst.get("Tags", []) if t["Key"] == "Name"), "")
    instances[inst["InstanceId"]] = {"name": name, "type": inst["InstanceType"]}

# 2) インスタンスごとに Average と Maximum のクエリを作る(Id は英小文字で始める)
queries = []
for n, iid in enumerate(instances):
    for stat in ("Average", "Maximum"):
        queries.append({
            "Id": f"{stat.lower()}_{n}",
            "Label": f"{iid}|{stat}",
            "MetricStat": {
                "Metric": {"Namespace": "AWS/EC2", "MetricName": "CPUUtilization",
                           "Dimensions": [{"Name": "InstanceId", "Value": iid}]},
                "Period": 86400,      # 1日ごとの値
                "Stat": stat,
            },
        })

# 3) 500 クエリずつ取得する(日時はタイムゾーン付きで渡す)
end = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0)
start = end - timedelta(days=DAYS)
values = {}
for i in range(0, len(queries), 500):
    paginator = cw.get_paginator("get_metric_data")
    for page in paginator.paginate(MetricDataQueries=queries[i:i + 500], StartTime=start, EndTime=end):
        for res in page["MetricDataResults"]:
            values.setdefault(res["Label"], []).extend(res["Values"])

# 4) 14日間の平均と最大を出す
print(f"{'InstanceId':20} {'Name':16} {'Type':10} {'Avg%':>6} {'Max%':>6}")
for iid, info in instances.items():
    avg_days = values.get(f"{iid}|Average", [])
    max_days = values.get(f"{iid}|Maximum", [])
    if not avg_days:
        print(f"{iid:20} {info['name']:16} {info['type']:10}  (データなし)")
        continue
    avg, peak = sum(avg_days) / len(avg_days), max(max_days)
    mark = "  ← 候補" if peak < THRESHOLD else ""
    print(f"{iid:20} {info['name']:16} {info['type']:10} {avg:6.1f} {peak:6.1f}{mark}")
出力例
InstanceId           Name             Type         Avg%   Max%
i-0123456789abcdef0  web-01           t3.micro     12.4   63.0
i-0fedcba9876543210  batch-01         m5.large      1.8    6.2  ← 候補
i-0aaaaaaaaaaaaaaaa  test-old         t3.medium     0.3    1.1  ← 候補

日ごとの平均値をさらに平均しているので厳密な14日間の平均とは少しずれるが、候補を見つける目的には十分だ。バッチ用のサーバーのように月末だけ負荷が上がるものもあるので、候補が見つかったら期間を延ばして確認してから判断する。

期間(Period)と保持期間・UTC

CloudWatch は、古いデータほど粗い単位にまとめて保存する。長い期間を指定するときは、Period をそれに合わせないとデータが返らない。

データの単位保持期間
60秒未満(高解像度メトリクス)3時間
60秒(1分)15日
300秒(5分)63日
3,600秒(1時間)455日(約15か月)
  • 日時はすべて UTC:StartTime / EndTime は datetime.now(timezone.utc) のようにタイムゾーン付きで渡す。タイムゾーンのない datetime.now() を渡すと、日本時間の値がUTCとして解釈され、9時間ずれる
  • 返る値は新しい順:Timestamps と Values は既定で新しい順に並ぶ。古い順がよければ ScanBy="TimestampAscending" を指定する
  • EC2 の基本モニタリングは5分間隔:Period に60を指定しても、詳細モニタリングを有効にしていなければ5分ごとの値しかない

Cost Explorer を使う前に

Cost Explorer の API は、使い始める前にいくつか確認が必要だ。

  • Cost Explorer を有効にする:一度もコンソールで開いたことがないアカウントでは、コンソールの「Billing and Cost Management」から Cost Explorer を有効にする。有効化してからデータが使えるようになるまで、最大24時間ほどかかる
  • エンドポイントは us-east-1:client は session.client("ce", region_name="us-east-1") と作る
  • IAM アクション:ce:GetCostAndUsage(予測を取るなら ce:GetCostForecast)。IAM ユーザーやロールが請求情報を見るには、ルートユーザーで「請求情報への IAM アクセス」を有効にしておく必要がある
  • APIは1リクエストごとに有料:記事作成時点で 1リクエストあたり 0.01 USD。ページングの続きを取る呼び出しも1回と数える

⚠️ ループの中で Cost Explorer を呼ばない

1回 0.01 USD でも、サービスごと・日ごとにループで呼ぶと回数が膨らむ。GroupBy を使って1回のリクエストでまとめて取り、結果をファイルに保存して再利用するのが基本だ。開発中に何度も試すときは、特に気を付けたい。

実践:サービス別の月額コストを出す

直近3か月分のコストを、サービス別・月別の表にする。get_cost_and_usage には Paginator がないので、PART 03 で紹介した方法で NextPageToken を受け渡す。結果は JSON に保存し、同じ日に再実行したときは API を呼ばずにファイルから読む。

cost_report.py
"""直近3か月のサービス別コストを表示する(結果は当日分をキャッシュして再利用)。"""
import json
from datetime import date
from pathlib import Path

import boto3

session = boto3.Session(profile_name="dev")
ce = session.client("ce", region_name="us-east-1")   # Cost Explorer は us-east-1


def month_start(d, back):
    """d の月から back か月前の1日を返す。"""
    y, m = d.year, d.month - back
    while m <= 0:
        y, m = y - 1, m + 12
    return date(y, m, 1)


today = date.today()
start = month_start(today, 2).isoformat()   # 2か月前の1日
end = today.isoformat()                      # End は「含まない」日付
cache = Path(f"cost_{start}_{end}.json")

if cache.exists():
    results = json.loads(cache.read_text(encoding="utf-8"))
else:
    kwargs = dict(
        TimePeriod={"Start": start, "End": end},
        Granularity="MONTHLY",
        Metrics=["UnblendedCost"],
        GroupBy=[{"Type": "DIMENSION", "Key": "SERVICE"}],
    )
    results = []
    while True:                                   # Paginator が無いので手動でページング
        resp = ce.get_cost_and_usage(**kwargs)
        results.extend(resp["ResultsByTime"])
        if not resp.get("NextPageToken"):
            break
        kwargs["NextPageToken"] = resp["NextPageToken"]
    cache.write_text(json.dumps(results, ensure_ascii=False, indent=1), encoding="utf-8")

# サービス × 月 の表にする
months = [r["TimePeriod"]["Start"][:7] for r in results]
table = {}
for r in results:
    month = r["TimePeriod"]["Start"][:7]
    for g in r["Groups"]:
        amount = float(g["Metrics"]["UnblendedCost"]["Amount"])   # 金額は文字列で返る
        table.setdefault(g["Keys"][0], {})[month] = amount

rows = sorted(table.items(), key=lambda kv: -kv[1].get(months[-1], 0))
print(f"{'Service':45}" + "".join(f"{m:>11}" for m in months))
for service, by_month in rows:
    if max(by_month.values()) < 0.01:
        continue
    print(f"{service[:45]:45}" + "".join(f"{by_month.get(m, 0):11.2f}" for m in months))
estimated = [r["TimePeriod"]["Start"][:7] for r in results if r.get("Estimated")]
print(f"\n単位: USD / 推定値を含む月: {', '.join(estimated) or 'なし'}")
出力例(金額はダミー)
Service                                          2026-08    2026-09    2026-10
Amazon Elastic Compute Cloud - Compute             84.12      86.40      58.31
Amazon Relational Database Service                 61.20      61.20      42.08
Amazon Virtual Private Cloud                       14.88      14.88      10.25
AmazonCloudWatch                                    3.41       3.95       2.67
Amazon Simple Storage Service                       1.02       1.10       0.81
Tax                                                16.46      16.75      11.41

単位: USD / 推定値を含む月: 2026-10
  • End は含まない:{"Start": "2026-09-01", "End": "2026-10-01"} で9月1か月分になる。当月分は今日の日付を End にする
  • 当月は確定していない:コストのデータは1日に1回以上更新されるが、当月分はレスポンスで Estimated: true になる。月の途中の値は、月額の見込みではなく「今日までの累計」である点に注意する
  • 金額は文字列:Amount は "84.1234567" のような文字列で返るので、float か、厳密に扱うなら decimal.Decimal に変換する
  • 税やクレジットも1行として返る:利用料だけを見たいときは、Filter={"Dimensions": {"Key": "RECORD_TYPE", "Values": ["Usage"]}} で絞る

ほかにも、GroupBy を {"Type": "TAG", "Key": "Env"} にすると環境タグ別のコストが取れる(タグをコスト配分タグとして有効にしておく必要がある)。今月の着地見込みは get_cost_forecast で取得できる。

✅ 次の記事では…

PART 06 では、ここまでのスクリプトを複数のAWSアカウントに対して実行する方法と、よく出るエラーの切り分け方を解説する。

→ PART 06 — 複数アカウントへの展開とトラブルシューティングへ