メインコンテンツへスキップ
要点OpenTelemetry Collector の CloudWatch receiver を使用して、AWS CloudWatch Logs を ClickStack に転送します。指定したロググループ名と自動検出に対応しています。デモデータセットとあらかじめ用意されたダッシュボードが含まれています。

​
概要

AWS CloudWatch は、AWS のリソースやアプリケーションを監視するためのサービスです。CloudWatch にはログ集約機能もありますが、ログを ClickStack に転送することで、次のことが可能になります。
  • ログをメトリクスやトレースとあわせて単一のプラットフォームで分析する
  • ClickHouse の SQL インターフェイスを使用してログをクエリする
  • CloudWatch の保持期間を短縮したりアーカイブしたりすることで、コストを削減する
このガイドでは、OpenTelemetry Collector を使用して CloudWatch Logs を ClickStack に転送する方法を説明します。

​
既存のCloudWatchロググループとのインテグレーション

このセクションでは、既存のCloudWatchロググループからログを取得してClickStackに転送するよう、OpenTelemetry Collectorを設定する方法について説明します。 本番環境向けの構成を設定する前にインテグレーションを試したい場合は、デモデータセットのセクションにあるデモデータセットでテストできます。

​
前提条件

  • 稼働中の ClickStack インスタンス
  • CloudWatchロググループ を使用する AWS アカウント
  • 適切な IAM 権限を持つ AWS 認証情報
ファイルベースのログインテグレーション (nginx、Redis) とは異なり、CloudWatch では CloudWatch API をポーリングするために、別途 OpenTelemetry Collector を実行する必要があります。この collector は AWS 認証情報と API へのアクセスを必要とするため、ClickStack のオールインワンイメージ内では実行できません。
1

​
ClickStack API keyを取得する

OpenTelemetry Collector はデータを ClickStack の OTLP endpoint に送信しますが、これには認証が必要です。
  1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
  2. 必要に応じてアカウントを作成するか、ログインします
  3. Team Settings → API Keys に移動します
  4. インジェスト API key をコピーします
これを環境変数として保存します。
export CLICKSTACK_API_KEY="your-api-key-here"
2

​
AWS 認証情報を設定する

AWS の認証情報を環境変数としてエクスポートします。設定方法は、認証の種類によって異なります。AWS SSO ユーザー向け (ほとんどの組織に推奨) :
# SSOにログイン
aws sso login --profile YOUR_PROFILE_NAME

# 認証情報を環境変数にエクスポート
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# 認証情報が正しく機能するか確認
aws sts get-caller-identity
YOUR_PROFILE_NAME を AWS SSO のプロファイル名 (例: AccountAdministrators-123456789) に置き換えてください。長期利用の認証情報を使用する IAM ユーザーの場合:
export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="us-east-1"

# 認証情報が正しく機能するか確認する
aws sts get-caller-identity
必要な IAM 権限:これらの認証情報に関連付けられた AWS アカウントには、CloudWatch Logs を読み取るために、次の IAM ポリシーが必要です。
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchLogsRead",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:FilterLogEvents"
      ],
      "Resource": "arn:aws:logs:*:YOUR_ACCOUNT_ID:log-group:*"
    }
  ]
}
YOUR_ACCOUNT_ID は、ご使用の AWS アカウント ID に置き換えてください。
3

​
CloudWatch receiver を設定する

CloudWatch receiver の設定を含む otel-collector-config.yaml ファイルを作成します。
設定を編集する前に、リージョン内にあるロググループを一覧表示し、実際の名前を選べるようにします (あわせてリージョンが正しいことも確認できます) 。
aws logs describe-log-groups --region us-east-1 \
  --query 'logGroups[].logGroupName' --output table
出力例:
-------------------------------
|      DescribeLogGroups      |
+-----------------------------+
|  /aws-glue/jobs/error       |
|  /aws-glue/jobs/logs-v2     |
|  /aws-glue/jobs/output      |
|  /aws-glue/sessions/error   |
|  /aws-glue/sessions/output  |
+-----------------------------+
以下の例 1 の groups.named ブロックでは、この一覧の名前をそのまま使用します。上記のアカウントの場合、named-groups セクションは次のようになります:
groups:
  named:
    /aws-glue/jobs/error:
    /aws-glue/jobs/logs-v2:
    /aws-glue/jobs/output:
    /aws-glue/sessions/error:
    /aws-glue/sessions/output:
また、対象のグループが共通のプレフィックス (ここでは /aws-glue/) を持つ場合は、個別に列挙する代わりに prefix: /aws-glue/ を指定した例 2 を使用できます。
例 1: 名前付きロググループ (推奨) この設定では、特定の名前付きロググループからログを収集します:
receivers:
  awscloudwatch:
    region: us-east-1
    logs:
      poll_interval: 1m
      max_events_per_request: 100
      groups:
        named:
          /aws/lambda/my-function:
          /aws/ecs/my-service:
          /aws/eks/my-cluster/cluster:

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: http://localhost:4318
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [awscloudwatch]
      processors: [batch]
      exporters: [otlphttp]
例 2: プレフィックスでロググループを自動検出この設定では、/aws/lambda というプレフィックスで始まる最大 100 個のロググループを自動検出して、ログを収集します。
receivers:
  awscloudwatch:
    region: us-east-1
    logs:
      poll_interval: 1m
      max_events_per_request: 100
      groups:
        autodiscover:
          limit: 100
          prefix: /aws/lambda

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: http://localhost:4318
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [awscloudwatch]
      processors: [batch]
      exporters: [otlphttp]
設定パラメータ:
  • region: ロググループが存在する AWS リージョン
  • poll_interval: 新しいログを確認する間隔 (例: 1m, 5m)
  • max_events_per_request: リクエストごとに取得するログイベントの最大数
  • groups.autodiscover.limit: 検出するロググループの最大数
  • groups.autodiscover.prefix: プレフィックスでロググループを絞り込む
  • groups.named: 収集するロググループ名を明示的に指定する
その他の設定オプションについては、CloudWatch receiver のドキュメントを参照してください。以下を置き換えてください:
  • ${CLICKSTACK_API_KEY} → 先ほど設定した環境変数を使用します
  • http://localhost:4318 → 使用する ClickStack endpoint (リモートで実行している場合は ClickStack ホストを使用)
  • us-east-1 → 使用する AWS リージョン
  • Log group names/prefixes → 実際の CloudWatch ロググループ名またはプレフィックス
CloudWatch receiver は、直近の時間ウィンドウ内のログのみを取得します (poll_interval に基づきます) 。初回起動時は現在時刻から収集を開始します。過去のログはデフォルトでは取得されません。
4

​
collector を起動する

docker-compose.yaml ファイルを作成します。
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-config.yaml
    environment:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_SESSION_TOKEN
      - AWS_REGION
      - CLICKSTACK_API_KEY
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
続いて、collector を起動します:
docker compose up -d
collector のログを確認します:
docker compose logs -f otel-collector
5

​
HyperDXでログを確認する

collector の実行後、次の手順を行います。
  1. http://localhost:8080 で HyperDX を開きます (または ClickStack の URL にアクセスします)
  2. Logs ビューに移動します
  3. ログが表示されるまで 1～2 分待ちます (poll interval に応じます)
  4. CloudWatch ロググループのログを検索します
ログで次の主要な属性を確認します。
  • ResourceAttributes['aws.region']: AWS リージョン (例: “us-east-1”)
  • ResourceAttributes['cloudwatch.log.group.name']: CloudWatch ロググループ名
  • ResourceAttributes['cloudwatch.log.stream']: ログストリーム名
  • Body: 実際のログメッセージの内容

​
デモデータセット

本番の AWS 環境を設定する前に CloudWatch Logs インテグレーションを試したいユーザー向けに、複数の AWS サービスにまたがる実際の運用に近いパターンを示す、事前生成済みログを含むサンプルデータセットを用意しています。
1

​
サンプルデータセットをダウンロードする

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/aws/cloudwatch/cloudwatch-logs.jsonl
このデータセットには、複数のサービスの 24 時間分の CloudWatch Logs が含まれています。
  • Lambda functions: 支払い処理、注文管理、認証
  • ECS services: レート制限とタイムアウトを伴う API ゲートウェイ
  • Background jobs: 再試行パターンを含むバッチ処理
2

​
ClickStack を起動する

まだ ClickStack を実行していない場合は、次を実行します。
docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest
ClickStack が完全に起動するまで少し待ちます。
3

​
デモデータセットをインポートする

docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_logs FORMAT JSONEachRow
" < cloudwatch-logs.jsonl
これにより、ログが ClickStack のログテーブルに直接インポートされます。
4

​
デモデータを確認する

インポートが完了したら、次の手順を実行します。
  1. http://localhost:8080 で HyperDX を開いてログインします (必要に応じてアカウントを作成してください)
  2. Logs ビューに移動します
  3. 時間範囲を 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC) に設定します
  4. cloudwatch-demo を検索するか、LogAttributes['source'] = 'cloudwatch-demo' でフィルタリングします
複数の CloudWatch Logs のロググループからのログが表示されるはずです。
タイムゾーン表示HyperDX はタイムスタンプをブラウザーのローカルタイムゾーンで表示します。デモデータの対象期間は 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC) です。場所にかかわらずデモログを確実に表示するには、時間範囲を 2025-12-06 00:00:00 - 2025-12-09 00:00:00 に設定してください。ログが表示されたら、より見やすく可視化するために範囲を 24 時間に絞り込めます。

​
ダッシュボードと可視化

ClickStack で CloudWatch Logs を監視できるように、重要な可視化を含むあらかじめ用意されたダッシュボードを提供しています。
1

​
ダッシュボード設定をする

2

​
ダッシュボードをインポートする

  1. HyperDX を開き、Dashboards セクションに移動します
  2. 右上の三点メニューにある Import Dashboard をクリックします
  1. cloudwatch-logs-dashboard.json ファイルをアップロードし、Finish Import をクリックします
3

​
ダッシュボードを表示する

すべての可視化があらかじめ設定された状態でダッシュボードが作成されます。
デモデータセットでは、時間範囲を 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC) に設定してください (ローカルのタイムゾーンに応じて調整してください) 。インポートしたダッシュボードには、デフォルトでは時間範囲が指定されていません。

​
トラブルシューティング

​
HyperDX にログが表示されない

AWS 認証情報が設定されていることを確認してください。 
aws sts get-caller-identity
これが失敗する場合は、認証情報が無効であるか、有効期限が切れています。 IAM 権限を確認します: AWS の認証情報に、必要な logs:DescribeLogGroups および logs:FilterLogEvents 権限があることを確認します。 collector のログでエラーを確認します: 
# Dockerを直接使用している場合、ログはstdoutに出力されます
# Docker Composeを使用している場合:
docker compose logs otel-collector
よくあるエラー:
  • The security token included in the request is invalid: 認証情報が無効であるか、有効期限が切れています。一時的な認証情報 (SSO) の場合は、AWS_SESSION_TOKEN が設定されていることを確認してください。
  • operation error CloudWatch Logs: FilterLogEvents, AccessDeniedException: IAM 権限が不足しています
  • failed to refresh cached credentials, no EC2 IMDS role found: AWS 認証情報の環境変数が設定されていません
  • connection refused: ClickStack エンドポイントに接続できません
CloudWatchロググループ が存在し、最近のログがあることを確認してください: 
# ロググループを一覧表示する
aws logs describe-log-groups --region us-east-1

# 特定のロググループに最近のログがあるか確認する（直近1時間）
aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function \
  --region us-east-1 \
  --start-time $(date -u -v-1H +%s)000 \
  --max-items 5

​
古いログしか表示されない、または最新のログが表示されない

CloudWatch receiver はデフォルトで「現在時刻」から開始します。 collector が初回起動時に現在時刻でチェックポイントを作成するため、その時点以降のログしか取得されません。過去のログは収集されません。 直近の過去ログを収集するには: collector を停止してチェックポイントを削除し、その後再起動します: 
# collectorを停止する
docker stop <container-id>

# 新たに再起動する（チェックポイントはコンテナーに保存されているため、削除するとリセットされる）
docker run --rm ...
receiver は新しいチェックポイントを作成し、現在時刻以降のログを収集します。

​
無効なセキュリティトークン / 認証情報の期限切れ

一時的な認証情報 (AWS SSO や引き受けたロール) を使用している場合、一定時間が経過すると期限切れになります。 新しい認証情報を再度エクスポートしてください： 
# SSOユーザーの場合:
aws sso login --profile YOUR_PROFILE_NAME
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# IAMユーザーの場合:
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# collectorを再起動する
docker restart <container-id>

​
レイテンシが高い、または最新のログが表示されない

ポーリング間隔を短くする: デフォルトの poll_interval は 1 分です。ログをほぼリアルタイムで取得したい場合は、これを短くします: 
logs:
  poll_interval: 30s  # 30秒ごとにポーリング
注: ポーリング間隔を短くすると、AWS API の呼び出し回数が増え、CloudWatch API のコストが高くなる可能性があります。

​
collector のメモリ使用量が多すぎる

バッチサイズを減らすか、タイムアウト時間を長くしてください。 
processors:
  batch:
    timeout: 5s
    send_batch_size: 100
自動検出を制限する: 
groups:
  autodiscover:
    limit: 50  # 100から50に減らす

​
次のステップ

  • 重大なイベント (接続障害、エラーの急増) に対するアラートを設定する
  • ログを ClickStack に取り込めたので、保持期間を調整するか S3 にアーカイブして CloudWatch のコストを削減する
  • インジェスト量を減らすため、ノイズの多いロググループを collector の設定から削除する

​
本番環境での運用

このガイドでは、テスト目的で OpenTelemetry Collector を Docker Compose を使ってローカルで実行する方法を紹介します。本番環境にデプロイする場合は、アクセスキーの管理を不要にするため、AWS にアクセスできるインフラストラクチャ (IAMロールを使用する EC2、IRSA を使用する EKS、またはタスクロールを使用する ECS) 上で collector を実行してください。レイテンシーとコストを削減するため、collector は CloudWatch ロググループと同じ AWS リージョンにデプロイしてください。 本番環境向けのデプロイメントパターンと collector の設定例については、OpenTelemetry を使用した取り込みを参照してください。
最終更新日 2026年6月10日