ClickStack によるホストログの監視

TL;DR

このガイドでは、OpenTelemetry collector を構成して systemd、カーネル、SSH、cron などのシステムサービスからログを収集し、ClickStack でホストのシステムログを監視する方法を説明します。次の内容を学びます。

システムログファイルを読み取るように OTel collector を構成する
カスタム構成を適用して ClickStack をデプロイする
あらかじめ用意されたダッシュボードを使って、ホストログのエラー、警告、サービスのアクティビティを可視化する

本番ホストを構成する前にインテグレーションをテストしたい場合のために、サンプルログを含むデモデータセットも用意されています。

所要時間: 5〜10 分

既存ホストとの統合

このセクションでは、ClickStack の OTel collector の設定を変更し、すべてのシステムログファイル（syslog、auth、kernel、daemon、アプリケーションログ）を読み取ることで、既存ホストから ClickStack にシステムログを送信する方法を説明します。

ご自身の既存環境を設定する前にホストログの統合を試してみたい場合は、"Demo dataset" セクションにある事前構成済みセットアップとサンプルデータを使ってテストできます。

前提条件

稼働中の ClickStack インスタンス
syslog ファイルがあるシステム
ClickStack の設定ファイルを変更するためのアクセス権限

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

まず、システムがsyslogファイルを書き込んでいることを確認します：

# syslogファイルの存在を確認（Linux）
ls -la /var/log/syslog /var/log/messages

# macOSの場合
ls -la /var/log/system.log

# 最新のエントリを表示
tail -20 /var/log/syslog

一般的なsyslogの配置場所:

Ubuntu/Debian: /var/log/syslog
RHEL/CentOS/Fedora: /var/log/messages
macOS: /var/log/system.log

カスタムOTel collector設定を作成する

ClickStackでは、カスタム設定ファイルをマウントして環境変数を設定することにより、ベースとなるOpenTelemetry Collectorの設定を拡張することができます。

システムの設定を含む host-logs-monitoring.yaml ファイルを作成します：

モダン Linux（Ubuntu 24.04 以降）
レガシー Linux（Ubuntu 20.04、RHEL、CentOS）
macOS

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: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

service:
  pipelines:
    logs/host:
      receivers: [filelog/syslog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /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: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

service:
  pipelines:
    logs/host:
      receivers: [filelog/syslog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

receivers:
  filelog/syslog:
    include:
      - /var/log/system.log
      - /host/private/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: "host-logs"
      
      - type: add
        field: resource["service.name"]
        value: "host-production"

service:
  pipelines:
    logs/host:
      receivers: [filelog/syslog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

全設定項目:

標準的な場所から syslog ファイルを読み込む
syslog 形式を解析して、タイムスタンプ、ホスト名、ユニット/サービス、PID、メッセージといった構造化フィールドを抽出する
元のログタイムスタンプを保持する
HyperDX でのフィルタリング用に source: host-logs 属性を追加する
専用パイプラインを使用してログを ClickHouse exporter に転送する

注記

カスタム設定では、新しいレシーバーとパイプラインだけを定義します
プロセッサー（memory_limiter、transform、batch）とエクスポーター（clickhouse）は、ベースの ClickStack 設定ですでに定義されているため、あとは名前で参照するだけです。
正規表現パーサーは、syslog フォーマットから systemd ユニット名、PID、その他のメタデータを抽出します
この設定では、コレクターの再起動時にログを再取り込みしてしまうのを防ぐために start_at: end を使用します。テスト用途では、すぐに過去のログを確認できるように start_at: beginning に変更してください。

ClickStackにカスタム設定を読み込むよう構成する

既存のClickStackデプロイメントでカスタムコレクター設定を有効にするには、次の手順を実行してください:

カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントします
環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定します。
コレクターがログを読み取れるように、syslog ディレクトリをマウントします

オプション1: Docker Compose

ClickStackのデプロイメント構成を更新してください:

services:
  clickstack:
    # ... 既存の設定 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... その他の環境変数 ...
    volumes:
      - ./host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log:/var/log:ro
      # ... その他のボリューム ...

オプション2：Docker Run（オールインワンイメージ）

docker runでオールインワンイメージを使用している場合:

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

注記

ClickStackコレクターがsyslogファイルを読み取るための適切な権限を持っていることを確認してください。本番環境では、読み取り専用マウント(:ro)を使用し、最小権限の原則に従ってください。

HyperDXでのログの確認

設定完了後、HyperDXにログインし、ログが正常に送信されていることを確認してください：

検索ビューに移動します
ソースを「Logs」に設定します
source:host-logs でフィルタしてホスト固有のログを表示します
unit、hostname、pid、message などのフィールドを含む構造化されたログエントリが表示されているはずです。

デモ用データセット

本番環境を構成する前にホストログ連携をテストしたいユーザー向けに、現実的なパターンを含む事前生成済みのシステムログからなるサンプルデータセットを提供します。

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

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

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

このデータセットには次の内容が含まれます:

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

テスト用 Collector 設定を作成する

次の設定内容で host-logs-demo.yaml という名前のファイルを作成します:

cat > 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: "host-demo"
      
      - type: add
        field: resource["service.name"]
        value: "host-demo"

service:
  pipelines:
    logs/host-demo:
      receivers: [filelog/journal]
      processors:
        - 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)/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 でログを確認する

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

HyperDX を開き、自分のアカウントにログインします (アカウントをまだ持っていない場合は先に作成する必要があります)
Search ビューに移動し、source を Logs に設定します
時間範囲を 2025-11-10 00:00:00 - 2025-11-13 00:00:00 に設定します

タイムゾーン表示

HyperDX はタイムスタンプをブラウザのローカルタイムゾーンで表示します。デモデータは 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) の期間をカバーしています。広めの時間範囲を指定しておくことで、どのロケーションからでもデモログが表示されるようにしています。ログが表示されたら、可視化を見やすくするために時間範囲を 24 時間に絞り込むことを推奨します。

ダッシュボードと可視化

ClickStack を使ってホストログのモニタリングを始められるように、システムログ向けの基本的な可視化を提供しています。

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

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

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

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

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

ダッシュボードは、すべての可視化が事前に設定された状態で作成されます。

主な可視化は次のとおりです:

重大度別の時間経過に伴うログボリューム
ログを生成している上位の systemd ユニット
SSH ログインアクティビティ（成功 vs 失敗）
ファイアウォールアクティビティ（ブロック vs 許可）
セキュリティイベント（ログイン失敗、アクセス禁止、ブロック）
サービスの再起動アクティビティ

注記

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

トラブルシューティング

カスタム設定が読み込まれない

環境変数が設定されていることを確認してください：

docker exec <コンテナ名> printenv CUSTOM_OTELCOL_CONFIG_FILE

カスタム設定ファイルがマウントされており、読み取り可能であることを確認します：

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10

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

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

# syslogの存在を確認
ls -la /var/log/syslog /var/log/messages

# ログが書き込まれているか確認
tail -f /var/log/syslog

コレクターがログを読み取れていることを確認する：

docker exec <container> cat /var/log/syslog | head -20

有効な設定に filelog レシーバーが含まれていることを確認してください。

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

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

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i "filelog\|syslog"

デモデータセットを使用している場合は、ログファイルにアクセスできることを確認してください。

docker exec <container> cat /tmp/host-demo/journal.log | wc -l

ログが正しく解析されない

選択した設定と syslog フォーマットが一致していることを確認してください。

モダンな Linux（Ubuntu 24.04 以降）の場合:

# ISO8601形式で表示されます: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

レガシーLinux または macOS の場合:

# 従来の形式で表示されます: Nov 17 14:16:16
tail -5 /var/log/syslog
# または
tail -5 /var/log/system.log

形式が一致しない場合は、カスタム OTel collector 設定の作成セクションで適切な設定タブを選択してください。

次のステップ

ホストログの監視を設定したら、次の作業を行ってください:

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

本番環境への移行

このガイドでは、迅速なセットアップのために、ClickStack に組み込まれている OpenTelemetry Collector を拡張して利用します。本番環境での運用では、独自の OTel collector を実行し、ClickStack の OTLP エンドポイントにデータを送信することを推奨します。本番向けの設定については、OpenTelemetry データの送信を参照してください。

既存ホストとの統合​

前提条件​

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

カスタムOTel collector設定を作成する​

ClickStackにカスタム設定を読み込むよう構成する​

オプション1: Docker Compose​

オプション2：Docker Run（オールインワンイメージ）​

HyperDXでのログの確認​

デモ用データセット​

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

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

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

HyperDX でログを確認する​

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

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

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

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

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

カスタム設定が読み込まれない​

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

ログが正しく解析されない​

次のステップ​

本番環境への移行​