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

TL;DR

OTel filelog receiver を使用して、ホストのシステムログ (syslog、auth、kernel) を ClickStack で収集・可視化します。デモ用データセットとあらかじめ用意されたダッシュボードが含まれます。

既存ホストとの統合

このセクションでは、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 エクスポーターに送信する

注記

カスタム設定では、新しい receivers と pipelines だけを定義します
プロセッサー（memory_limiter、transform、batch）とエクスポーター（clickhouse）は、ベースの ClickStack 構成ですでに定義されているため、名前を指定するだけで利用できます
regex パーサーは 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 \
  clickhouse/clickstack-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" \
  clickhouse/clickstack-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 にログが表示されていない​

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

次のステップ​

本番環境への移行​