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

要点OpenTelemetry Collector を使用して、EC2 のシステムログを自動的に EC2 メタデータ (インスタンス ID、リージョン、AZ、インスタンスタイプ) でエンリッチし、ClickStack に収集・可視化します。デモデータセットとあらかじめ用意されたダッシュボードも含まれています。

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

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

ClickStack を同じEC2インスタンスで実行していますか？監視対象のログがあるEC2インスタンス上で ClickStack も実行している場合は、Generic Host Logs ガイドと同様のオールインワン構成を使用できます。/var/log を ClickStack コンテナーにマウントし、カスタム設定に resourcedetection processor を追加すると、EC2メタデータを自動的に取得できます。このガイドでは、本番環境へのデプロイでより一般的な分散アーキテクチャに焦点を当てます。

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

前提条件

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

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

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

# メタデータトークンを取得する (IMDSv2)
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
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 インスタンス自体で実行している

EC2 メタデータは、インスタンス内から http://169.254.169.254 で利用できます。OpenTelemetry の resourcedetection プロセッサは、このエンドポイントを使用してログにクラウドのコンテキスト情報を自動的に付加します。

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

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

# Ubuntuインスタンス
ls -la /var/log/syslog

# Amazon Linux / RHELインスタンス
ls -la /var/log/messages

# 最近のエントリを表示
tail -20 /var/log/syslog
# または
tail -20 /var/log/messages

OpenTelemetry Collector をインストールする

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

# 最新リリースをダウンロード
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# 展開してインストール
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# インストールを確認
otelcol-contrib --version

collector configurationの作成

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

sudo mkdir -p /etc/otelcol-contrib

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

モダンな Linux（Ubuntu 24.04+）
レガシー Linux（Amazon Linux 2、RHEL、古い Ubuntu）

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 に送信する

EC2メタデータの付加resourcedetection プロセッサは、すべてのログに次の属性を自動的に追加します。

cloud.provider: “aws”
cloud.platform: “aws_ec2”
cloud.region: AWSリージョン (例: “us-east-1”)
cloud.availability_zone: AZ (例: “us-east-1a”)
cloud.account.id: AWSアカウント ID
host.id: EC2 インスタンス ID (例: “i-1234567890abcdef0”)
host.type: インスタンスタイプ (例: “t3.medium”)
host.name: インスタンスのホスト名

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

本番環境で使用する場合collector が systemd サービスとして実行されるように設定し、起動時に自動的に開始され、障害発生時に再起動されるようにします。詳細は、OpenTelemetry Collector documentationを参照してください。

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:
  # デモ用にEC2メタデータをシミュレート（実際のEC2インスタンス不要）
  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

デモ目的のため、ここでは resource プロセッサを使用して EC2 メタデータを手動で追加しています。本番環境で実際の EC2 インスタンスを使用する場合は、EC2 メタデータ API を自動的に問い合わせる resourcedetection プロセッサを使用してください。

デモ設定で 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 メタデータを確認します

タイムゾーン表示HyperDX はタイムスタンプをブラウザーのローカルタイムゾーンで表示します。デモデータの期間は 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) です。時間範囲を広めに設定しているため、どの地域からでもデモログを確認できます。ログが表示されたら、可視化を見やすくするために期間を 24 時間まで絞り込めます。

以下を含む、シミュレートされた 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 - 特定のインスタンスのログ

デモデータセットでは、時間範囲を 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) に設定してください (ローカルの timezone に応じて調整してください) 。インポートしたダッシュボードには、デフォルトでは時間範囲が指定されていません。

トラブルシューティング

ログに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 データの送信を参照してください。

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

前提条件

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

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

​OpenTelemetry Collector をインストールする

​collector configurationの作成

​ClickStack APIキーを設定する

​collector を起動する

​HyperDX でログを確認する

​デモデータセット

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

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

​デモ設定で ClickStack を実行する

​HyperDX でログを確認する

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

​ ダッシュボード設定

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

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

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

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

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

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

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

​次のステップ

​本番環境での運用

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

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

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

OpenTelemetry Collector をインストールする

collector configurationの作成

ClickStack APIキーを設定する

collector を起動する

HyperDX でログを確認する

デモデータセット

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

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

デモ設定で ClickStack を実行する

HyperDX でログを確認する

ダッシュボードと可視化

ダッシュボード設定

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

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

トラブルシューティング

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

HyperDX にログが表示されない

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

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

次のステップ

本番環境での運用