ClickStackでEC2ホストログを監視する

既存のEC2インスタンスとのインテグレーション

このセクションでは、システムログを収集し、EC2メタデータを自動的に付与して ClickStack に送信するために、EC2インスタンスへ OpenTelemetry Collector をインストールする方法を説明します。この分散アーキテクチャは本番環境での利用を前提としており、複数のインスタンスへスケールできます。

本番インスタンスを構成する前に EC2 ホストログのインテグレーションを試したい場合は、"デモデータセット" セクションにある事前構成済みのセットアップとサンプルデータでテストできます。

前提条件

ClickStack インスタンスが稼働中であること (オンプレミス、クラウド、またはローカル環境のいずれでも可)
EC2 インスタンスが稼働中であること (Ubuntu、Amazon Linux、またはその他の Linux ディストリビューション)
EC2 インスタンスから ClickStack の OTLP エンドポイントにネットワーク接続できること (HTTP はポート 4318、gRPC は 4317)
EC2 インスタンスメタデータサービスにアクセスできること (デフォルトで有効)

EC2メタデータにアクセスできることを確認する

EC2インスタンス上で、メタデータサービスにアクセスできることを確認します。

# Get metadata token (IMDSv2)
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Verify instance metadata
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type

インスタンス ID、リージョン、インスタンスタイプが表示されるはずです。これらのコマンドが失敗する場合は、次の点を確認してください。

インスタンスメタデータサービスが有効になっている
IMDSv2 がセキュリティグループまたはネットワーク ACL によってブロックされていない
これらのコマンドを EC2 インスタンス自体で実行している

syslog ファイルが存在することを確認する

EC2 インスタンスに syslog ファイルが出力されていることを確認します。

# Ubuntu instances
ls -la /var/log/syslog

# Amazon Linux / RHEL instances
ls -la /var/log/messages

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages

OpenTelemetry Collector をインストールする

EC2インスタンスに OpenTelemetry Collector Contrib をインストールします。

# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version

collector configurationの作成

/etc/otelcol-contrib/config.yaml に OpenTelemetry Collector の設定ファイルを作成します：

sudo mkdir -p /etc/otelcol-contrib

お使いのLinuxディストリビューションに合わせて設定を選択してください：

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
      
      - type: add
        field: attributes.source
        value: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /var/log/messages
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

設定内の以下の項目を置き換えてください：

YOUR_CLICKSTACK_HOST: ClickStack が稼働しているホスト名または IP アドレス
ローカルでテストする場合は、SSH トンネルを使用できます (トラブルシューティングセクションを参照) 。

この設定:

標準的な場所 (Ubuntu では /var/log/syslog、Amazon Linux/RHEL では /var/log/messages) にあるシステムログファイルを読み取ります
syslog形式を解析し、構造化フィールド (タイムスタンプ、ホスト名、unit/service、PID、メッセージ) を抽出
EC2 メタデータを自動的に検出して追加するには、resourcedetection プロセッサを使用します
存在する場合は、必要に応じて EC2 タグ (Name、Environment、Team) も含まれます
OTLP HTTP 経由でログを ClickStack に送信する

ClickStack APIキーを設定する

ClickStack APIキーを環境変数としてエクスポートします：

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

再起動後も有効にするには、シェルのプロファイルに追加してください。

echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

collector を起動する

OpenTelemetry Collector を起動します。

CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml

HyperDX でログを確認する

collector が起動したら、HyperDX にログインし、EC2 メタデータ付きのログが流れていることを確認します。

Search view に移動します
ログソースを Logs に設定します
source:ec2-host-logs で絞り込みます
ログエントリをクリックして展開します
リソース属性に EC2 メタデータが表示されていることを確認します。
- cloud.provider
- cloud.region
- host.id (インスタンス ID)
- host.type (インスタンスタイプ)
- cloud.availability_zone

デモデータセット

本番環境のインスタンスを構成する前に EC2 ホストログのインテグレーションを試したい方向けに、シミュレーションされた EC2 メタデータを含むデモデータセットを用意しています。

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

サンプルのログファイルをダウンロードします：

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

このデータセットには、以下が含まれます：

システムの起動シーケンス
SSH ログインのアクティビティ (成功した試行と失敗した試行)
セキュリティインシデント (fail2ban による対応を伴うブルートフォース攻撃)
定期メンテナンス (cron ジョブ、anacron)
サービスの再起動 (rsyslog)
カーネルメッセージとファイアウォールのアクティビティ
通常の運用と特筆すべきイベントの混在

テスト用collectorの設定を作成する

以下の設定で、ec2-host-logs-demo.yaml という名前のファイルを作成します。

cat > ec2-host-logs-demo.yaml << 'EOF'
receivers:
  filelog/journal:
    include:
      - /tmp/host-demo/journal.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      
      - type: add
        field: attributes.source
        value: "ec2-demo"

processors:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  resource:
    attributes:
      - key: service.name
        value: "ec2-demo"
        action: insert
      - key: cloud.provider
        value: "aws"
        action: insert
      - key: cloud.platform
        value: "aws_ec2"
        action: insert
      - key: cloud.region
        value: "us-east-1"
        action: insert
      - key: cloud.availability_zone
        value: "us-east-1a"
        action: insert
      - key: host.id
        value: "i-0abc123def456789"
        action: insert
      - key: host.type
        value: "t3.medium"
        action: insert
      - key: host.name
        value: "prod-web-01"
        action: insert

service:
  pipelines:
    logs/ec2-demo:
      receivers: [filelog/journal]
      processors:
        - resource
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

デモ設定で ClickStack を実行する

デモ用のログと設定を使用して ClickStack を実行します。

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/ec2-host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

HyperDX でログを確認する

collector が起動したら、次の手順を実行します。

HyperDX を開き、アカウントにログインします (必要に応じて先にアカウントを作成してください)
検索ビューに移動し、ログソースを Logs に設定します
時間範囲を 2025-11-10 00:00:00 - 2025-11-13 00:00:00 に設定します
source:ec2-demo で絞り込みます
ログエントリを展開し、リソース属性に含まれる EC2 メタデータを確認します

以下を含む、シミュレートされた EC2 コンテキストを持つログが表示されるはずです。

インスタンス ID: i-0abc123def456789
リージョン: us-east-1
アベイラビリティーゾーン: us-east-1a
インスタンスタイプ: t3.medium

ダッシュボードと可視化

ClickStack で EC2 ホストログの監視をすぐに始められるよう、クラウドコンテキストを含む主要な可視化を用意しています。

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

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

あらかじめ用意されたダッシュボードをインポートする

HyperDX を開き、Dashboards セクションに移動します
右上の三点メニューから Import Dashboard をクリックします

host-logs-dashboard.json ファイルをアップロードし、Finish Import をクリックします

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

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

ダッシュボードの可視化は、EC2 コンテキストで絞り込めます。

cloud.region:us-east-1 - 特定のリージョンのログを表示
host.type:t3.medium - インスタンスタイプで絞り込み
host.id:i-0abc123def456 - 特定のインスタンスのログ

トラブルシューティング

ログにEC2メタデータが表示されない

EC2メタデータサービスにアクセスできることを確認してください。

# メタデータトークンを取得する
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# メタデータエンドポイントをテストする
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

これが失敗する場合は、以下を確認してください。

インスタンスメタデータサービスが有効になっていること
IMDSv2 がセキュリティグループでブロックされていないこと
collector を EC2 インスタンス上で実行していること

メタデータ関連のエラーについて collector のログを確認してください。

# systemdサービスとして実行している場合
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# フォアグラウンドで実行している場合は、stdoutを確認する

HyperDX にログが表示されない

syslog ファイルが存在し、書き込みが行われていることを確認します。

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

collector がログファイルを読み取れるか確認してください:

cat /var/log/syslog | head -20

ClickStack へのネットワーク接続を確認する:

# OTLPエンドポイントをテスト
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# レスポンスが返ってくれば（エラーでも可）、エンドポイントに到達できている

collector のログにエラーがないか確認する:

# フォアグラウンドで実行している場合
# 標準出力のエラーメッセージを確認する

# systemd サービスとして実行している場合
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

ログが正しくパースされない

syslog のフォーマットを確認してください:

Ubuntu 24.04 以降の場合:

# ISO8601フォーマットで表示されるはずです: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Amazon Linux 2 / Ubuntu 20.04 の場合:

# 従来のフォーマットで表示されるはずです: Nov 17 14:16:16
tail -5 /var/log/messages

フォーマットが一致しない場合は、使用しているディストリビューションに応じて、collector 設定の作成セクションで該当する設定タブを使用してください。

systemd サービスとして collector が起動しない

サービスの状態を確認します。

sudo systemctl status otelcol-contrib

詳細なログを確認する:

sudo journalctl -u otelcol-contrib -n 50

よくある問題:

環境変数で API key が正しく設定されていない
設定ファイルの構文エラー
ログファイルの読み取り権限の問題

次のステップ

重要なシステムイベント (サービス障害、認証の失敗、ディスク警告) に対するアラートを設定します
EC2 メタデータ属性 (リージョン、インスタンスタイプ、インスタンス ID) で絞り込み、特定のリソースを監視します
EC2 のホストログをアプリケーションログと相関付け、総合的なトラブルシューティングを行います
セキュリティ監視 (SSH 接続の試行、sudo の使用、ファイアウォールによるブロック) 向けにカスタムダッシュボードを作成します

本番環境への移行

このガイドでは、ホストレベルの監視における本番環境の推奨構成として、OpenTelemetry Collector を EC2 インスタンスに直接インストールします。多数のインスタンスにわたって collector を管理する場合は、構成管理ツール (Ansible、Chef、Puppet) や、Kubernetes 環境では OpenTelemetry Operator の利用を検討してください。本番環境向けの設定については、OpenTelemetry データの送信を参照してください。