Amazon CloudWatch と OpenTelemetry による Claude Code 利用状況の分析

エンジニアリング組織で Claude Code のような AI コーディングエージェントを利用している場合、その利用は追跡できる速度を上回って増加している可能性が高いでしょう。トークン消費量、チームごとのコスト、開発者の生産性といった疑問に既存のダッシュボードが答えられないのは、テレメトリがそもそもオブザーバビリティバックエンドに届いていないためです。

Amazon CloudWatch の OpenTelemetry Protocol（OTLP）が一般提供となったことで、ベアラートークン認証によるメトリクスの取り込みが可能になりました。これにより、OTLP を出力するツールは通常、認可ヘッダー 1 つだけでメトリクスを直接 CloudWatch に送信できます。コレクターもサイドカーも、開発者マシン上での IAM 認証情報の配線も不要です。数分でシグナルを接続し、開発者ごとのコスト按分、チーム単位の利用分析、運用アラートを実現でき、すべて Prometheus Query Language（PromQL）でクエリできます。

本記事では、Claude Code 向けのエンドツーエンドのセットアップを解説します。ここでは Claude Code に焦点を当てますが、OpenAI Codex と GitHub Copilot に関する包括的なガイダンスは AWS Observability ベストプラクティスで提供しています。本記事では、開発者マシン上でのシンプルさを重視してベアラートークン認証に焦点を当てます。開発者認証に SSO（シングルサインオン）や OIDC（OpenID Connect）を必要とする組織は、フェデレーテッドアイデンティティのパターンやトークン更新ヘルパーについてガイダンスリポジトリを参照してください。

ベアラートークン認証

ベアラートークン（CloudWatch メトリクス API キー）を使用すると、AWS の外部で動作するツール（開発者のノート PC 上の Claude Code など）が、AWS SDK や IAM 認証情報チェーンを必要とせずに CloudWatch へメトリクスを送信できます。各トークンは、CloudWatchAPIKeyAccess 管理ポリシーのみにスコープされた AWS IAM ユーザーに紐づけられます。

重要： ベアラートークンは長期的な認証情報です。本記事では、AI コーディングエージェントが AWS 外部の開発者ノート PC 上で動作するため、ベアラートークンを使用します。SigV4 認証では、中央集約型のコレクターを用意するか、すべての開発者マシンでコレクタープロセスを実行する必要があります。いずれの方式も運用上の複雑さを増します。ベアラートークンはそのインフラ要件を完全に排除します。短期的な認証情報を用いた SigV4 が実現可能な AWS 内部で動作するワークロードでは、より強固なセキュリティ態勢のためにそちらの方式を推奨します。CloudWatch の OTLP エンドポイントは HTTPS を必須とし、平文 HTTP でのリクエストは拒否されます。詳細は CloudWatch OTLP Metrics Bearer Token Auth を参照してください。

粒度（granularity）戦略

組織は、ベアラートークンをどのようにプロビジョニングするかによって、テレメトリ属性の粒度を制御します。最も細かいレベルでは、各開発者が専用の IAM ユーザーとベアラートークンを持つため、属性はトークン自体に内在します。より粗いレベルでは、単一のトークンをチーム全体や組織全体で共有し、アイデンティティの属性は代わりにクライアント側のリソース属性で処理します。次の図は、これら 3 つのアプローチを示しています。

図1：トークン粒度戦略のオプション（開発者ごと、チームごと、組織全体＋クライアント側属性の 3 アプローチ）

図 1：トークン粒度戦略のオプション（開発者ごと、チームごと、組織全体＋クライアント側属性の 3 アプローチ）

3 つのアプローチはいずれも同一のダッシュボードと PromQL クエリを生成します。属性がトークン自体ではなくリソース属性によって駆動されるためです。まずは単一の共有トークンでパイプラインを検証し、その後セキュリティ態勢の要件に応じてチームごと、または開発者ごとのトークンに分割してください。コンプライアンス上、特定個人に紐づけ可能な認証情報が求められる場合や、クリーンなオフボーディング（単一 IAM ユーザーの失効）が必須要件である場合には、開発者ごとのトークンを推奨します。

前提条件

CloudWatch リソースを作成する権限を持つ AWS アカウント
インストール・設定済みの AWS CLI v2
最新バージョンの Claude Code
CloudWatch メトリクス API キー（以下で生成）

コンソールでベアラートークンを作成する

CloudWatch コンソールで、セットアップ(Setup) セクション配下の 設定(Settings)配下のグローバル(Global) に移動します。

API キー(API Keys) までスクロールします。
作成(Create) を選択します。
API キーの有効期限(API key expiration)を選択します。

CloudWatch が、CloudWatchAPIKeyAccess ポリシーをアタッチした関連 IAM ユーザーを代わりに作成します。

図2：CloudWatch コンソールの Settings ページでベアラートークンを作成する

図 2：CloudWatch コンソールの Settings ページでベアラートークンを作成する

CLI でベアラートークンを作成する

あるいは、以下のコマンドで CLI を使ってトークンを作成します。

# CloudWatch メトリクス取り込み用の IAM ユーザーを作成
aws iam create-user --user-name cloudwatch-metrics-api-key-user

# CloudWatchAPIKeyAccess 管理ポリシーをアタッチ
aws iam attach-user-policy \
    --user-name cloudwatch-metrics-api-key-user \
    --policy-arn arn:aws:iam::aws:policy/CloudWatchAPIKeyAccess

# CloudWatch メトリクス取り込み用のサービス固有認証情報を作成
aws iam create-service-specific-credential \
    --user-name cloudwatch-metrics-api-key-user \
    --service-name cloudwatch.amazonaws.com

レスポンスには ServiceCredentialSecret フィールドが含まれ、これがベアラートークンの値です。AWS Secrets Manager または組織の Vault ソリューションに安全に保管してください。トークンは決してバージョン管理にコミットしないように注意してください。鍵の自動ローテーションには、Lambda 関数を用いた AWS Secrets Manager のローテーションを利用してください。

クライアント側の設定

ベアラートークンを設定したら、メトリクスをエクスポートするように Claude Code を構成できます。このアプローチでは、各開発者が設定する（またはプロファイル管理で配布する）クライアント側のリソース属性を使用します。

# Secrets Manager からトークンを取得
BEARER_TOKEN=$(aws secretsmanager get-secret-value \
 --secret-id cloudwatch-otlp-bearer-token \
 --query SecretString \
 --output text)

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT="https://monitoring.<AWS_REGION>.amazonaws.com"
export OTEL_RESOURCE_ATTRIBUTES="user.id=$(whoami),user.email=${USER_EMAIL},team.id=${TEAM:-engineering},cost_center=${COST_CENTER:-default},department=${DEPARTMENT:-engineering},environment=${ENV:-dev}"

# セキュリティ上の注意：環境変数はプロセス一覧やシェル履歴から露出する可能性があります。
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${BEARER_TOKEN}"

# エクスポート頻度の制御（テスト用に 2 秒）
export OTEL_METRIC_EXPORT_INTERVAL=2000

<AWS_REGION> はお使いのリージョン（例：us-east-1、eu-west-1）に置き換えてください。

OTEL_RESOURCE_ATTRIBUTES の行は、すべてのメトリクスにアイデンティティのディメンションを付与します。開発者がこれらの属性を直接設定します。これらはダッシュボードやアラートでフィルタリング・グループ化するための PromQL ラベルになります。組織が必要とする任意の属性を使用してください。重要な要件は、集計が機能するようにフリート全体で一貫性を保つことです。

属性	目的	例
`user.id`	開発者ごとの属性	`jdoe`
`user.email`	開発者ごとの属性（メール）	`jdoe@acme.com`
`team.id`	チーム単位の集計	`platform-eng`
`cost_center`	財務／チャージバックのグループ	`CC-4200`
`department`	組織単位のロールアップ	`engineering`
`environment`	dev／staging／prod の利用区別	`production`

利用可能な標準属性とメトリクスの完全な一覧は、Claude Code のドキュメントで確認できます。

テレメトリ設定とプライバシー制御をフリート全体に強制するために、Claude Code は組織のプロファイル管理ソリューションを通じてデプロイ可能な管理者管理の設定をサポートしています。

メトリクスが流れていることを確認する

環境変数を設定したら、短い Claude Code セッションを実行します。

# 短いセッションを開始
claude -p "Let's conquer the world" --max-turns 1

メトリクスが流れていることを確認するには、CloudWatch Query Studio を開いて claude_ と入力します。使用されたトークン数を追跡する claude_code.token.usage など、いくつかのメトリクスが表示されます。

図3：CloudWatch Query Studio でメトリクスの取り込みを確認する

図 3：CloudWatch Query Studio でメトリクスの取り込みを確認する

サンプル利用状況ダッシュボード

前述の粒度戦略に関わらず、PromQL を使って Claude Code のテレメトリデータをクエリする CloudWatch ダッシュボードが用意されています。リソース属性がクライアント側設定セクションで説明したセマンティック規約に従っている限り、すべての値が自動的にダッシュボードに表示されます。

構築済みダッシュボードをデプロイします。

# ダッシュボード定義をダウンロード
curl -o claude-code-dashboard.json \
 https://raw.githubusercontent.com/aws-observability/aws-observability-accelerator/main/artifacts/cloudwatch-dashboards/claude-code/claude-code.json

aws cloudwatch put-dashboard \
  --dashboard-name claude-code-usage \
  --dashboard-body file://claude-code-dashboard.json \
  --output off \
  --region <AWS_REGION>

ダッシュボードが作成されたことを確認します。

aws cloudwatch list-dashboards --dashboard-name-prefix claude-code --region <AWS_REGION>

ダッシュボードは 5 つのセクションで構成されています。まずステークホルダーが全体の健全性を一目で評価できるよう高レベルのサマリーから始まり、その後トークンの経済性、開発者の活動、組織のコスト配分、インフラの健全性へと段階的に掘り下げていきます。

概要

最上段には、消費トークン総数、アクティブユーザー数、総セッション数、キャッシュヒット率を含むサマリーが表示されます。OTel メトリクスを Amazon CloudWatch に送信するように構成したリージョンを選択してください。

図4：総トークン数、アクティブユーザー数、セッション数、キャッシュヒット率を示す概要サマリーカード

図 4：総トークン数、アクティブユーザー数、セッション数、キャッシュヒット率を示す概要サマリーカード

トークン使用量

このセクションは、エンジニアリングリーダーが最初に問う質問に答えます。「どれだけ消費していて、その内訳はどこにあるのか？」。トークン消費を時系列、種類別（入力、出力、キャッシュ読み取り、キャッシュ作成）、モデル別、ユーザー別、推定コスト別に分解します。これらのパネルを使って、どのモデルが支出を牽引しているか、どのユーザーが最も多く消費しているかを特定できます。

図5：時系列の消費量、種類別の内訳、モデル別の使用量、上位ユーザー、ユーザーごとの推定コスト、アクティブユーザーの推移を示すトークン使用量セクション

図 5：時系列の消費量、種類別の内訳、モデル別の使用量、上位ユーザー、ユーザーごとの推定コスト、アクティブユーザーの推移を示すトークン使用量セクション

開発者の生産性

コストにとどまらず、このセクションでは開発者がツールで実際に生み出しているものを追跡します。追加・削除されたコード行数、コミット数、アクティブなコーディング時間、作成されたプルリクエスト、コード編集パターンなどです。言語別の内訳円グラフは、コードベースのどの部分が AI 支援から最も恩恵を受けているかを明らかにします。コード編集の判断パネル（承認 vs 却下）は、エージェントの提案が開発者の意図とどれだけ合致しているかのシグナルになります。

図6：コード行数、コミット数、アクティブ時間、プルリクエスト、言語分布、コード編集の承認／却下率を示す開発者生産性メトリクス

図 6：コード行数、コミット数、アクティブ時間、プルリクエスト、言語分布、コード編集の承認／却下率を示す開発者生産性メトリクス

組織別の内訳

複数のチームや部門を持つ組織向けに、このセクションはコスト配分のビューを提供します。これらのパネルは、クライアント側設定セクションで構成した department および team.id リソース属性に直接対応します。チャージバック、予算計画、組織内のどこがツールを最も効果的に活用しているかの特定に活用してください。

図7：部門別およびチーム別のトークン使用量を示す組織別内訳

図 7：部門別およびチーム別のトークン使用量を示す組織別内訳

Amazon Bedrock API の健全性

Claude Code のバックエンドとして Amazon Bedrock を使用している場合、ダッシュボードにはインフラの健全性パネルも含まれます。これらはモデル別に分類されたスロットリングイベント、クライアントエラー、サーバーエラーを表示します。開発者から報告された問題（応答の遅延、リクエストの失敗）を上流の API の挙動と関連付けるのに活用してください。

アラート

ダッシュボードのすべてのパネルは PromQL クエリに支えられています。任意のパネルからアラームを作成するには、次の手順を実行します。

関心のあるパネル（例：ユーザー別トークン使用量）を開きます。
View in Query Studioを選択して、基になるクエリを開きます。
Query Studio から直接 Create alarm を選択します。
必要に応じてクエリやしきい値を調整します。

ダッシュボードが示す範囲を超えるシナリオに対して、カスタムの PromQL アラームクエリを記述することもできます。いくつか例を挙げます。

個人の支出スパイク

ある人物が 1 時間で前日 1 日分の支出の 2 倍以上を費やした場合、それは異常を示します。これは暴走ループ、スタックしたエージェント、または侵害されたトークンを検知します。

sum by("user.email") (increase({"claude_code.cost.usage"}[1h]))
> 2 * sum by("user.email") (increase({"claude_code.cost.usage"}[24h]))

図8：ユーザーの 1 時間あたりの支出が 1 日分の支出を上回ったときにトリガーする PromQL アラーム

図 8：ユーザーの 1 時間あたりの支出が 1 日分の支出を上回ったときにトリガーする PromQL アラーム

チーム予算のしきい値

チームの 1 日の支出が定義した予算を超えたときにアラートを出します。

sum by ("team.id") (increase({"claude_code.cost.usage"}[24h])) > 500

利用の減少

チームの 1 日のセッション数が 7 日間平均の 50% を下回ったときに検知します。これはツールの問題やアクセスの問題の可能性を示すシグナルです。

sum by ("team.id") (increase({"claude_code.session.count"}[1d]))
< 0.5 * avg_over_time(sum by ("team.id") (increase({"claude_code.session.count"}[1d]))[7d:1d])

Amazon Managed Grafana でダッシュボードを使用する

Amazon Managed Grafana またはセルフマネージドの Grafana を使用している場合は、Grafana からのクエリに関するドキュメントに従って CloudWatch を PromQL データソースとして追加し、Grafana ダッシュボード JSON をインポートしてください。

コスト見積もり

各開発者が 1 日あたり約 20 セッションを実行し、それぞれがリソース属性付きで約 7 つのメトリクスデータポイントを出力し、開発者が月あたり約 22 日アクティブな、開発者 200 名の組織の場合：

10〜15 個の属性を持つ一般的な OTLP データポイントは 300〜600 バイトです。中間値として 450 バイトを使用すると：

200 開発者 × 20 セッション/日 × 7 メトリクス × 450 バイト = 12.6 MB/日
12.6 MB/日 × 22 日 = 約 277 MB/月 ≒ 0.27 GB/月

取り込み料金 $0.50/GB では、基本ケースで月あたり約 $0.14 です。高カーディナリティのメトリクス（100 倍のボリューム）でも、取り込み総額は月あたり $14 未満にとどまります。CloudWatch コンソールでの PromQL クエリは無料です。

この例における開発者 200 名分の総コストは、月あたり $15 未満 になります。

最新情報については Amazon CloudWatch 料金ページを参照してください。

クリーンアップ

重要： CloudWatch はメトリクスを最大 15 か月間、無料で保持します。継続的なコストとセキュリティ上の露出を避けるため、アラームと IAM リソースを削除してください。

作成したすべてのリソースを削除するには、次のコマンドを実行します。

# ダッシュボードを削除
aws cloudwatch delete-dashboards --dashboard-names claude-code-usage --region <AWS_REGION>

# CloudWatch アラームを削除
aws cloudwatch delete-alarms --alarm-names <alarm-name> --region <AWS_REGION>

# サービス固有認証情報を削除
aws iam delete-service-specific-credential --user-name cloudwatch-metrics-api-key-user --service-specific-credential-id <credential-id>

# IAM ユーザーからポリシーをデタッチ
aws iam detach-user-policy --user-name cloudwatch-metrics-api-key-user --policy-arn arn:aws:iam::aws:policy/CloudWatchAPIKeyAccess

# IAM ユーザーを削除
aws iam delete-user --user-name cloudwatch-metrics-api-key-user

# Secrets Manager を使用している場合はシークレットを削除
# 警告：シークレットの削除は不可逆です。ベアラートークンは復元できません。
# 続行する前に、トークンが不要であることを確認してください。
aws secretsmanager delete-secret --secret-id <secret-name> --region <AWS_REGION>

テレメトリのエクスポートを停止するには、環境変数の設定を解除するか、シェルプロファイルから削除します。

unset CLAUDE_CODE_ENABLE_TELEMETRY OTEL_METRICS_EXPORTER OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_HEADERS OTEL_RESOURCE_ATTRIBUTES

まとめ

本記事では、ベアラートークン認証を使用して OpenTelemetry メトリクスを Amazon CloudWatch にエクスポートするように Claude Code を構成し、コストと利用状況を可視化する PromQL ベースのダッシュボードをデプロイし、支出の異常と利用の減少に対するアラートを設定しました。

同じ CloudWatch OTLP エンドポイントは、IDE エージェントだけでなく、OpenTelemetry で計装されたあらゆるワークロードからのテレメトリを受け付けます。複数のアカウントとリージョンを持つ大規模組織向けに、一般提供ではクロスアカウント・クロスリージョンのメトリクス集約も導入されました。これにより、統一された可視性を実現するために単一のオブザーバビリティアカウントへメトリクスを収集できます。

GitHub Copilot および OpenAI Codex 向けの IDE オブザーバビリティのセットアップ方法については、完全ガイドをご覧ください。

Amazon Web Services ブログ