ClickStackでホストログを監視

既存ホストとのインテグレーション

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

独自の既存環境を構成する前にホストログのインテグレーションを試したい場合は、"デモデータセット" セクションにある、あらかじめ構成されたセットアップとサンプルデータを使ってテストできます。

前提条件

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

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

まず、システムがsyslogファイルを出力していることを確認します。

# Check if syslog files exist (Linux)
ls -la /var/log/syslog /var/log/messages

# Or on macOS
ls -la /var/log/system.log

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

一般的な syslog の保存場所:

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

カスタムOTel collector configurationの作成

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

システムの設定を記述した host-logs-monitoring.yaml というファイルを作成します：

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エクスポーターにルーティングする

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

既存の ClickStack デプロイメントでカスタム collector 設定を有効にするには、次の対応が必要です。

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

オプション 1: Docker Compose

ClickStack のデプロイメント設定を更新します。

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./host-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log:/var/log:ro
      # ... other volumes ...

オプション 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 \
  clickhouse/clickstack-all-in-one:latest

HyperDX でログを確認する

設定が完了したら、HyperDX にログインし、ログが取り込まれていることを確認します。

Search view に移動します
ログソースを 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" \
  clickhouse/clickstack-all-in-one:latest

HyperDX でログを確認する

ClickStack が起動したら、以下を実行します。

HyperDX を開いてアカウントにログインします (先にアカウント作成が必要な場合があります)
Search view に移動し、ソースを Logs に設定します
時間範囲を 2025-11-10 00:00:00 - 2025-11-13 00:00:00 に設定します

ダッシュボードと可視化

ClickStack でホストログの監視を始めるのに役立つよう、システムログ向けの基本的な可視化を用意しています。

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

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

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

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

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

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

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

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

重要度別のログ量の推移
ログを生成している上位の systemd ユニット
SSH ログインアクティビティ (成功/失敗)
ファイアウォールのアクティビティ (ブロック/許可)
セキュリティイベント (ログイン失敗、BAN、ブロック)
サービス再起動のアクティビティ

トラブルシューティング

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

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

docker exec <container-name> 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

collector がログを読み取れているか確認します:

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

現在有効な設定に filelog receiver が含まれていることを確認してください。

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フォーマットが、選択した設定と一致していることを確認してください。

Modern Linux (Ubuntu 24.04以降) の場合：

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

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