Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickStack で AWS CloudWatch Logs を監視する

View as MarkdownEdit this pageReport an issueSet up docs MCP

概要

AWS CloudWatch は、AWS のリソースやアプリケーションを監視するためのサービスです。CloudWatch にはログ集約機能もありますが、ログを ClickStack に転送することで、次のことが可能になります。

  • ログをメトリクスやトレースとあわせて単一のプラットフォームで分析する
  • ClickHouse の SQL インターフェイスを使用してログをクエリする
  • CloudWatch の保持期間を短縮したりアーカイブしたりすることで、コストを削減する

このガイドでは、OpenTelemetry Collector を使用して CloudWatch Logs を ClickStack に転送する方法を説明します。

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

このセクションでは、既存のCloudWatchロググループからログを取得してClickStackに転送するよう、OpenTelemetry Collectorを設定する方法について説明します。

本番環境向けの構成を設定する前にインテグレーションを試したい場合は、デモデータセットのセクションにあるデモデータセットでテストできます。

前提条件

  • 稼働中の ClickStack インスタンス
  • CloudWatchロググループ を使用する AWS アカウント
  • 適切な IAM 権限を持つ AWS 認証情報

ClickStack API keyを取得する

OpenTelemetry Collector はデータを ClickStack の OTLP endpoint に送信しますが、これには認証が必要です。

  1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
  2. 必要に応じてアカウントを作成するか、ログインします
  3. Team Settings → API Keys に移動します
  4. インジェスト API key をコピーします
ClickStack API Key

これを環境変数として保存します:

export CLICKSTACK_API_KEY="your-api-key-here"

AWS 認証情報を設定する

AWS の認証情報を環境変数としてエクスポートします。設定方法は、認証の種類によって異なります。

AWS SSO ユーザー向け (ほとんどの組織に推奨) :

# Login to SSO
aws sso login --profile YOUR_PROFILE_NAME

# Export credentials to environment variables
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Verify credentials work
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"

# Verify credentials work
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 に置き換えてください。

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 ロググループ名またはプレフィックス

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

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 サービスにまたがる実際の運用に近いパターンを示す、事前生成済みのログを含むサンプルデータセットを提供しています。

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

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: 再試行パターンを含むバッチ処理

ClickStack を起動する

まだ ClickStack を実行していない場合は、次を実行します。

docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

ClickStack が完全に起動するまで少し待ちます。

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

docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_logs FORMAT JSONEachRow
" < cloudwatch-logs.jsonl

これにより、ログが ClickStack のログテーブルに直接インポートされます。

デモデータを確認する

インポートが完了したら、次の手順を実行します。

  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ロググループ からのログが表示されるはずです。

デモ検索ビュー

ダッシュボードと可視化

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

ダッシュボード設定をダウンロードする

ダッシュボード設定ファイルをダウンロードする。

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

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

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

すべての可視化があらかじめ設定された状態でダッシュボードが作成されます。

CloudWatch Logs ダッシュボード

トラブルシューティング

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 の設定から削除する

本番環境向け

このガイドでは、テスト目的で Docker Compose を使用して OpenTelemetry Collector をローカルで実行する方法を説明します。本番環境へのデプロイでは、アクセスキーの管理を不要にするため、AWS にアクセスできるインフラストラクチャ上で collector を実行してください (IAM ロールを使用する EC2、IRSA を使用する EKS、またはタスクロールを使用する ECS) 。レイテンシーとコストを抑えるため、CloudWatchロググループ と同じ AWS リージョンに collectors をデプロイしてください。

本番環境向けのデプロイパターンと collector の設定例については、OpenTelemetry による取り込み を参照してください。

Navigation