ClickStack を使用した EC2 ホストログの監視

TL;DR

インスタンス ID、リージョン、AZ、インスタンスタイプなどの EC2 メタデータを自動付加する OpenTelemetry コレクターを使用して、ClickStack で EC2 システムログを収集・可視化します。デモ用データセットと事前構築済みダッシュボードが含まれます。

既存の EC2 インスタンスとの統合

このセクションでは、EC2 インスタンス上に OpenTelemetry Collector をインストールしてシステムログを収集し、EC2 メタデータを自動付加しながら ClickStack へ送信する方法を説明します。この分散アーキテクチャは本番運用に対応しており、複数インスタンスへのスケールにも対応できます。

同じ EC2 インスタンスで ClickStack を実行していますか？

監視したいログを出力している EC2 インスタンス上で ClickStack が動作している場合は、Generic Host Logs guide と同様のオールインワン方式を利用できます。/var/log を ClickStack コンテナにマウントし、カスタム設定に resourcedetection プロセッサを追加することで、EC2 メタデータを自動的に取得できます。本ガイドでは、より一般的な本番環境向けの分散アーキテクチャに焦点を当てます。

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

前提条件

ClickStack インスタンスが稼働していること（オンプレミス、Cloud、ローカルのいずれでも可）
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 インスタンス上で直接実行していること

注記

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

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

コレクター設定の作成

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

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 形式を解析し、タイムスタンプ、ホスト名、ユニット/サービス、PID、メッセージといった構造化フィールドを抽出します
resourcedetection プロセッサーを使用して EC2 メタデータを自動検出して追加します
オプションで、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

コレクターの実行

OpenTelemetry Collectorを起動します:

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

本番環境での使用について

コレクターをsystemdサービスとして実行するように設定し、起動時の自動起動と障害時の自動再起動を有効にしてください。詳細については、OpenTelemetry Collectorドキュメントを参照してください。

HyperDXでログを確認する

コレクターが実行されたら、HyperDXにログインし、EC2メタデータを含むログが流入していることを確認します：

検索ビューに移動します
ソースを 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）
カーネルメッセージおよびファイアウォールのアクティビティ
通常の運用と重要なイベントの混在

テストコレクター設定を作成する

以下の設定で 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でログを確認する

コレクターが起動したら：

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) に設定してください（ローカルタイムゾーンに合わせて調整してください）。インポートしたダッシュボードには、デフォルトではタイムレンジが指定されていません。

トラブルシューティング

ログに EC2 メタデータが含まれない

EC2 メタデータサービスへアクセス可能か確認する:

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

# Test metadata endpoint
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

これが失敗する場合は、次の点を確認してください:

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

メタデータ関連のエラーがないか、コレクターのログを確認してください。

# If running as systemd service
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# If running in foreground, check stdout

HyperDX にログが表示されない

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

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

コレクターがログファイルを読み取れることを確認する:

cat /var/log/syslog | head -20

ClickStack へのネットワーク疎通を確認する:

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

# レスポンスが返されます（エラーの場合でも、エンドポイントに到達可能であることを意味します）

コレクターのログにエラーがないか確認する:

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

# 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 キーの設定が正しくない
設定ファイルの構文エラー
ログファイルを読み取る際の権限の問題

次のステップ

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

本番環境への移行

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

既存の EC2 インスタンスとの統合​

前提条件​

EC2メタデータへのアクセスを確認する​

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

OpenTelemetry Collectorのインストール​

コレクター設定の作成​

ClickStack APIキーの設定​

コレクターの実行​

HyperDXでログを確認する​

デモデータセット​

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

テストコレクター設定を作成する​

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

HyperDXでログを確認する​

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

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

事前に用意されたダッシュボードをインポートする​

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

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

ログに EC2 メタデータが含まれない​

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

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

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

次のステップ​

本番環境への移行​

既存の EC2 インスタンスとの統合

前提条件

EC2メタデータへのアクセスを確認する

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

OpenTelemetry Collectorのインストール

コレクター設定の作成

ClickStack APIキーの設定

コレクターの実行

HyperDXでログを確認する

デモデータセット

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

テストコレクター設定を作成する

デモ設定でClickStackを実行する

HyperDXでログを確認する

ダッシュボードと可視化

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

事前に用意されたダッシュボードをインポートする

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

トラブルシューティング

ログに EC2 メタデータが含まれない

HyperDX にログが表示されない

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

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

次のステップ

本番環境への移行