EC2のメトリクスを例に、CloudWatchのOpenTelemetryを分かりやすく記載

はじめに

CloudWatch の OpenTelemetry（以下 OTel）で CPU 使用率、メモリ使用率、ディスク使用率を取得し、監視からアラーム通知までを、図を取り入れながら仕組みと設定方法を見ていきます。下記のようにプライベートサブネットに配置した EC2 から VPC エンドポイント経由で CloudWatch エンドポイントに OTel メトリクスを送信します。取得した OTel のデータから CloudWatch アラームを作成して SNS 経由でメール通知を行います。

環境

役割	値
EC2	Amazon Linux 2023
VPC エンドポイント	com.amazonaws.ap-northeast-1.monitoring（必須）、com.amazonaws.ap-northeast-1.ec2（任意）
IAM	CloudWatchAgentServerPolicy
取得するメトリクス	system.cpu.utilization / system.memory.utilization / system.filesystem.utilization

com.amazonaws.ap-northeast-1.ec2 は EC2 のタグデータを取得して送付する際に必要です。

データ取得から送信

データの取得

CloudWatch Agent は OTel Collector です。OTel の設定ファイルを作成して「どこからデータを受け取り、どう加工して、どこへ送るか」を設定する形になります。

設定ファイルは 5 つのブロックでできています。それぞれの役割を見ていきます。

• receivers でメトリクスの種類や取得間隔を指定します。今回は hostmetrics を使い、60 秒ごとに OS から CPU・メモリ・ディスクを読みます。
• processors では、取得したデータに情報を足したり、まとめたりする設定をしています。具体的には resourcedetection で IMDS からインスタンス ID・AZ・インスタンスタイプを属性として付与し、resource で service.name のような自分で決めた属性を付与し、batch で 1 リクエストにまとめてから送ります。
• exporters でデータの送信先を指定します。otlphttp で CloudWatch の OTLP エンドポイントへ POST します。
• extensions は、パイプラインには乗らない補助機能の設定です。今回は sigv4auth で、送信の直前にリクエストへ SigV4 署名を付けます。認証情報を設定ファイルに書く箇所が無いのは、これが IAM ロールの一時クレデンシャルを使って署名してくれるためです。
• 最後に service で、上で定義した部品を 1 本の pipeline として繋ぐ宣言を行います。ここに書いたものだけが動きます。

コンポーネント名の末尾に付けている /cwagent は名前の衝突を避けるための接尾辞です。

データの送信

送信先と認証を見ていきます。

宛先は先ほどの https://monitoring.ap-northeast-1.amazonaws.com/v1/metrics です。認証は通常の AWS API と同じ SigV4 署名です。IMDSv2（169.254.169.254）からインスタンスプロファイルの一時クレデンシャルを取得し、POST ごとに署名を付与して CloudWatch エンドポイントに送信します。必要な IAM 権限は、OTLP 専用のものではなく従来と同じ CloudWatchAgentServerPolicy を付与しておきます。

設定の流れ

ここまでを設定手順の流れとして並べると次のようになります。水色が EC2 上で実施する設定、緑が CloudWatch 側（マネージド）で、作り込む必要のない部分です。

設定

① CloudWatch Agent を入れる

OTLP への対応は 1.300070.0 以降のバージョンをインストールします。

curl -sSLO "https://amazoncloudwatch-agent-ap-northeast-1.s3.ap-northeast-1.amazonaws.com/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm" && sudo rpm -Uvh amazon-cloudwatch-agent.rpm

バージョンが 1.300070.0 以上であることを確認します。

cat /opt/aws/amazon-cloudwatch-agent/bin/CWAGENT_VERSION
1.300073.1b1859

② OTLP の受け口を有効にする

CloudWatch Agent は「エージェント独自の JSON」と「追記する OTel Collector の YAML」の 2 段構成です。まずベースの JSON を作ります。

sudo tee /tmp/agent.json > /dev/null <<'EOF'
{
  "agent": {
    "metrics_collection_interval": 60
  },
  "opentelemetry": {
    "collect": {
      "otlp": {
        "http_endpoint": "0.0.0.0:4318"
      }
    }
  }
}
EOF

上記設定にて 4318 で OTLP を待ち受け、受け取ったメトリクス・ログ・トレースをCloudWatch のエンドポイントへ送信します。アプリを計装する場合はアプリ側を http://localhost:4318 に向けます。

③ 収集設定（YAML）を書く

今回はアプリを用意しないので、hostmetrics で EC2 自身の CPU・メモリ・ディスクを集めます。

sudo tee /tmp/otel.yaml > /dev/null <<'EOF'
receivers:
  hostmetrics/cwagent:
    collection_interval: 60s
    scrapers:
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      memory:
        metrics:
          system.memory.utilization:
            enabled: true
      filesystem:
        include_fs_types:
          fs_types: [xfs, ext4]
          match_type: strict
        metrics:
          system.filesystem.utilization:
            enabled: true

processors:
  resourcedetection/cwagent:
    detectors: [env, ec2]
    ec2:
      tags:
        - ^Name$
  resource/cwagent:
    attributes:
      - key: service.name
        value: otel-demo
        action: upsert
      - key: deployment.environment
        value: test
        action: upsert
  batch/cwagent:
    send_batch_size: 200
    timeout: 10s

extensions:
  sigv4auth/cwagent:
    region: ap-northeast-1
    service: monitoring

exporters:
  otlphttp/cwagent:
    metrics_endpoint: https://monitoring.ap-northeast-1.amazonaws.com/v1/metrics
    auth:
      authenticator: sigv4auth/cwagent
  debug/cwagent:
    verbosity: detailed

service:
  extensions: [sigv4auth/cwagent]
  pipelines:
    metrics/cwagent:
      receivers: [hostmetrics/cwagent]
      processors: [resourcedetection/cwagent, resource/cwagent, batch/cwagent]
      exporters: [otlphttp/cwagent, debug/cwagent]
EOF

使用率を出す 3 つのメトリクスは、いずれも既定で無効です。system.cpu.utilization、system.memory.utilization、system.filesystem.utilization を明示的に enabled: true にしています。

debug/cwagent は検証で送信内容をデバッグログに出すためのものです。確認が済んだら pipeline の exporters から外します。

④ 設定を反映して送信を開始する

JSON ファイルを指定して CloudWatch Agent を起動した後、YAML ファイルを append します。

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -c file:/tmp/agent.json -s && sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/tmp/otel.yaml -s

⑤ ログで送信を確認する

sleep 90 && sudo tail -n 80 /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log

ログ中の Starting HTTP server 0.0.0.0:4318 で OTLP の受け口が起動し、メトリクスが送信されることを確認します。

⑥ PromQL で参照する

CloudWatch → Query Studio → 入力言語で PromQL を選択し、Editor に直接書いて Run します。下記のようなクエリで今回取得した値を確認します。

目的	クエリ
CPU 使用率（アイドル以外の合計）	sum by ("@resource.host.id")({"system.cpu.utilization", state!="idle"})
メモリ使用率	{"system.memory.utilization", state="used"}
ディスク使用率	{"system.filesystem.utilization", mountpoint="/"}
届いているかの確認	{"system.cpu.utilization"}
5 分平均	avg_over_time({"system.memory.utilization", state="used"}[5m])

監視設定

仕組み

取得したメトリクスをアラームにします。CloudWatch アラームは PromQL の式そのものを条件として受け取ります。従来のように「メトリクスを選んでしきい値を別に指定する」のではなく、しきい値も式の中に書きます。

設定の流れ

SNS トピックの作成からメール受信までを並べると次のようになります。水色が CLI で実施する設定、緑が CloudWatch 側で自動的に動く部分です。

設定

① SNS トピックを作る

通知先のトピックを作り、ARN を変数に入れておきます。

TOPIC_ARN=$(aws sns create-topic --name otel-alarm --region ap-northeast-1 --query TopicArn --output text) && echo "$TOPIC_ARN"

② サブスクリプションを承認する

メールアドレスをサブスクリプションとして登録します。実行するとそのアドレスに確認メールが届くので、本文のリンクを押して購読を有効にします。

aws sns subscribe --topic-arn "$TOPIC_ARN" --protocol email --notification-endpoint [e-mail] --region ap-northeast-1

③ アラームを作成する

CPU・メモリ・ディスクの 3 本を作ります。条件式は PromQL で確認したクエリに比較演算子を足したものです。

aws cloudwatch put-metric-alarm --alarm-name otel-cpu-high --region ap-northeast-1 --evaluation-interval 60 --evaluation-criteria '{"PromQLCriteria":{"Query":"sum by (\"@resource.host.id\")({\"system.cpu.utilization\", state!=\"idle\"}) > 0.7","PendingPeriod":300,"RecoveryPeriod":300}}' --alarm-actions "$TOPIC_ARN"

aws cloudwatch put-metric-alarm --alarm-name otel-memory-high --region ap-northeast-1 --evaluation-interval 60 --evaluation-criteria '{"PromQLCriteria":{"Query":"avg_over_time({\"system.memory.utilization\", state=\"used\"}[5m]) > 0.8","PendingPeriod":300,"RecoveryPeriod":300}}' --alarm-actions "$TOPIC_ARN"

aws cloudwatch put-metric-alarm --alarm-name otel-disk-high --region ap-northeast-1 --evaluation-interval 60 --evaluation-criteria '{"PromQLCriteria":{"Query":"{\"system.filesystem.utilization\", mountpoint=\"/\"} > 0.8","PendingPeriod":300,"RecoveryPeriod":300}}' --alarm-actions "$TOPIC_ARN"

④ 状態を確認する

aws cloudwatch describe-alarms --alarm-name-prefix otel- --region ap-northeast-1 --output table

下記のように、CloudWatch コンソールからもアラームが作成されていることを確認できます。

※otel-cpu-high2 は動作確認用に CPU 使用率 < 0.7 で設定したテストアラームです。

⑤ アラームを発生させる

otel-cpu-high2 でアラームが発生したことを確認します。

⑥ メールを受信する

下記のとおり、アラームメールが送信されます。

Alarm Details:
- Name:                       otel-cpu-high2
- Description:                
- AWS Account:                xxxxxxxxxxxx
- Alarm Arn:                  arn:aws:cloudwatch:ap-northeast-1:xxxxxxxxxxxx:alarm:otel-cpu-high2

Contributor Details:
- Id:                         xxxxxxxxxxxx
- State Change:               OK -> ALARM
- Timestamp:                  Friday 25 September, 2026 xx:xx:xx UTC

Contributor Attributes:
- @resource.host.id         i-xxxxxxxxxxxx

Evaluation Criteria:
- Type:                       PromQL
- Query:                      sum by ("@resource.host.id")({"system.cpu.utilization", state!="idle"}) < 0.7
- Pending Period:             5m
- Recovery Period:            5m

State Change Actions:
- OK: 
- ALARM: [arn:aws:sns:ap-northeast-1:xxxxxxxxxxxx:otel-alarm]
- INSUFFICIENT_DATA: 

おわりに

CloudWatch Agent を OTel Collector として使うと、プライベートサブネットの EC2 からでも OTLP で CPU・メモリ・ディスク使用率を送れることが確認できました。設定ファイルの書き方は素の Collector と同一なので、そのまま OTel の学習にもなります。また、アラーム設定も比較的簡単に設定できることが確認できました。

なお、続きのログ・メトリクスの送信については下記ブログに記載しました。