ClickStackでMySQLログを監視 - ClickHouse Documentation

要点OTel filelog receiver を使用して、MySQL のエラーログとスロークエリログを ClickStack で収集・可視化します。デモデータセットとあらかじめ用意されたダッシュボードが含まれています。

既存の MySQL とのインテグレーション

このセクションでは、ClickStack OTel collector の設定を変更して、既存の MySQL 環境から ClickStack にログを送信するよう構成する方法を説明します。既存環境の設定を行う前に MySQL ログのインテグレーションを試したい場合は、“デモデータセット” セクションにある事前構成済みの環境とサンプルデータを使ってテストできます。

前提条件

稼働中の ClickStack インスタンス
既存の MySQL インストール環境 (バージョン 5.7 以降)
MySQL の設定ファイルを変更するためのアクセス権限
ログファイルを保存するための十分なディスク容量

MySQL のログを設定する

MySQL は複数のログタイプをサポートしています。OpenTelemetry を使用して包括的に監視するには、エラーログとスロークエリログを有効にすることを推奨します。my.cnf または my.ini の設定ファイルは、通常、次の場所にあります。

Linux (apt/yum): /etc/mysql/my.cnf または /etc/my.cnf
macOS (Homebrew): /usr/local/etc/my.cnf または /opt/homebrew/etc/my.cnf
Docker: 通常は、環境変数またはマウントされた設定ファイルで構成します

[mysqld] セクションに次の設定を追加または変更します。

[mysqld]
# エラーログの設定
log_error = /var/log/mysql/error.log

# スロークエリログの設定
slow_query_log = ON
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 1
log_queries_not_using_indexes = ON

# オプション: 一般クエリログ（詳細出力。本番環境では注意して使用すること）
# general_log = ON
# general_log_file = /var/log/mysql/mysql-general.log

スロークエリログには、long_query_time 秒を超えたクエリが記録されます。この閾値は、アプリケーションのパフォーマンス要件に応じて調整してください。低く設定しすぎると、ログが大量に生成されます。

これらの変更を行ったら、MySQL を再起動します。

# systemdの場合
sudo systemctl restart mysql

# Dockerの場合
docker restart <mysql-container>

ログが出力されていることを確認します。

# エラーログを確認する
tail -f /var/log/mysql/error.log

# スロークエリログを確認する
tail -f /var/log/mysql/mysql-slow.log

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

ClickStack では、カスタム設定ファイルをマウントして環境変数を設定することで、ベースの OpenTelemetry Collector 設定を拡張できます。このカスタム設定は、HyperDX が OpAMP 経由で管理するベース設定にマージされます。以下の設定で、mysql-logs-monitoring.yaml という名前のファイルを作成します。

receivers:
  filelog/mysql_error:
    include:
      - /var/log/mysql/error.log
    start_at: end
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}[+-]\d{2}:\d{2})\s+(?P<thread_id>\d+)\s+\[(?P<level>[^\]]+)\]\s+(\[(?P<error_code>[^\]]+)\]\s+)?(?P<message>.*)$'
        
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
        parse_to: body
      
      - type: add
        field: attributes.source
        value: "mysql-error"
      
      - type: add
        field: resource["service.name"]
        value: "mysql-production"

  filelog/mysql_slow:
    include:
      - /var/log/mysql/mysql-slow.log
    start_at: end
    multiline:
      line_start_pattern: '^# Time:'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^# Time: (?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\n# User@Host: (?P<user>[^\[]+)\[(?P<user_host>[^\]]*)\]\s+@\s+(?P<host>[^\[]*)\[(?P<ip>[^\]]*)\].*\n# Query_time: (?P<query_time>[\d.]+)\s+Lock_time: (?P<lock_time>[\d.]+)\s+Rows_sent: (?P<rows_sent>\d+)\s+Rows_examined: (?P<rows_examined>\d+)'
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999Z'
        parse_to: body
      
      - type: add
        field: attributes.source
        value: "mysql-slow"
      
      - type: add
        field: resource["service.name"]
        value: "mysql-production"

service:
  pipelines:
    logs/mysql:
      receivers: [filelog/mysql_error, filelog/mysql_slow]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

この構成では、次のことを行います。

標準的な場所から MySQL のエラーログとスロークエリログを読み取ります
複数行にまたがるログエントリを処理します (スロークエリは複数行にまたがります)
両方のログフォーマットを解析し、構造化されたフィールド (level、error_code、query_time、rows_examined) を抽出します
元のログのタイムスタンプを保持します
HyperDX でフィルタリングできるように source: mysql-error と source: mysql-slow の attribute を追加します
専用のパイプラインを介してログを ClickHouse エクスポーターにルーティングします

MySQL のエラーログとスロークエリログはフォーマットがまったく異なるため、2 つの receiver が必要です。time_parser は、タイムゾーンオフセットを含む MySQL の ISO8601 タイムスタンプフォーマットを処理するために gotime layout を使用します。

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

既存の ClickStack デプロイメントでカスタム collector 構成を有効にするには、カスタム構成ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントし、環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定します。ClickStack のデプロイメント構成を更新します:

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

ClickStack collector に、MySQL のログファイルを読み取るための適切な権限が付与されていることを確認してください。読み取り専用マウント (:ro) を使用し、最小権限の原則に従ってください。

HyperDX でログを確認する

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

Search view に移動します
ログソースを Logs に設定します
source:mysql-error または source:mysql-slow で絞り込むと、MySQL 固有のログを確認できます
level、error_code、message (エラーログ) 、および query_time、rows_examined、query (スロークエリログ) などのフィールドを含む構造化されたログエントリが表示されます

デモデータセット

本番システムを構成する前に MySQL ログインテグレーションを試したいユーザー向けに、実際の傾向に近いパターンを持つ、事前生成済みの MySQL ログのサンプルデータセットを提供しています。

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

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

# エラーログをダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/error.log

# スロークエリログをダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/mysql-slow.log

データセットには以下が含まれます。

エラーログのエントリ (起動メッセージ、警告、接続エラー、InnoDB メッセージ)
現実的なパフォーマンス特性を反映した低速クエリ
接続のライフサイクルイベント
データベースサーバーの起動および停止のシーケンス

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

以下の設定内容で、mysql-logs-demo.yaml という名前のファイルを作成します。

cat > mysql-logs-demo.yaml << 'EOF'
receivers:
  filelog/mysql_error:
    include:
      - /tmp/mysql-demo/error.log
    start_at: beginning  # デモデータの先頭から読み込む
    multiline:
      line_start_pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^(?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}[+-]\d{2}:\d{2})\s+(?P<thread_id>\d+)\s+\[(?P<level>[^\]]+)\]\s+(\[(?P<error_code>[^\]]+)\]\s+)?(?P<message>.*)$'
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
        parse_to: body
      - type: add
        field: attributes.source
        value: "mysql-demo-error"
      - type: add
        field: resource["service.name"]
        value: "mysql-demo"

  filelog/mysql_slow:
    include:
      - /tmp/mysql-demo/mysql-slow.log
    start_at: beginning  # デモデータの先頭から読み込む
    multiline:
      line_start_pattern: '^# Time:'
    operators:
      - type: regex_parser
        parse_from: body
        parse_to: attributes
        regex: '^# Time: (?P<timestamp>\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)\n# User@Host: (?P<user>[^\[]+)\[(?P<user_host>[^\]]*)\]\s+@\s+(?P<host>[^\[]*)\[(?P<ip>[^\]]*)\].*\n# Query_time: (?P<query_time>[\d.]+)\s+Lock_time: (?P<lock_time>[\d.]+)\s+Rows_sent: (?P<rows_sent>\d+)\s+Rows_examined: (?P<rows_examined>\d+)'
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999Z'
        parse_to: body
      - type: add
        field: attributes.source
        value: "mysql-demo-slow"
      - type: add
        field: resource["service.name"]
        value: "mysql-demo"

service:
  pipelines:
    logs/mysql-demo:
      receivers: [filelog/mysql_error, filelog/mysql_slow]
      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)/mysql-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/error.log:/tmp/mysql-demo/error.log:ro" \
  -v "$(pwd)/mysql-slow.log:/tmp/mysql-demo/mysql-slow.log:ro" \
  clickhouse/clickstack-all-in-one:latest

HyperDX でログを確認する

ClickStack の起動後:

ClickStack が完全に初期化されるまで少し待ちます (通常は 30〜60 秒)
HyperDX を開いてアカウントにログインします (必要に応じて先にアカウントを作成してください)
Search view に移動し、ログソースを Logs に設定します
時間範囲を 2025-11-13 00:00:00 - 2025-11-16 00:00:00 に設定します
合計 40 件のログが表示されるはずです (source:mysql-demo-error のエラーログ 30 件 + source:mysql-demo-slow のスロークエリ 10 件)

40 件すべてのログがすぐに表示されない場合は、collector が処理を完了するまで 1 分ほど待ってください。それでもログが表示されない場合は、docker restart clickstack-demo を実行し、さらに 1 分ほど待ってからもう一度確認してください。これは、既存ファイルを start_at: beginning で一括ロードする際の OpenTelemetry filelog receiver に関する既知の問題です。start_at: end を使用する本番デプロイでは、ログは書き込まれると同時にリアルタイムで処理されるため、この問題は発生しません。

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

ダッシュボードと可視化

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

ダッシュボード設定

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

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

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

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

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

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

トラブルシューティング

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

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

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

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

HyperDX にログが表示されない

実際に適用されている設定に 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 mysql

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

docker exec <container> cat /tmp/mysql-demo/error.log | wc -l
docker exec <container> cat /tmp/mysql-demo/mysql-slow.log | wc -l

スロークエリログが表示されない

MySQL でスロークエリログが有効になっていることを確認します:

SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';

MySQL がスロークエリを記録しているか確認します:

tail -f /var/log/mysql/mysql-slow.log

テスト用の低速クエリを実行します:

SELECT SLEEP(2);

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

MySQL のログフォーマットが、想定どおりのフォーマットと一致していることを確認してください。このガイドの正規表現パターンは、MySQL 5.7+ および 8.0+ のデフォルトフォーマット向けに設計されています。エラーログの数行を確認してください。

head -5 /var/log/mysql/error.log

想定されるフォーマット：

2025-11-14T10:23:45.123456+00:00 0 [System] [MY-010116] [Server] /usr/sbin/mysqld (mysqld 8.0.35) starting as process 1

フォーマットが大きく異なる場合は、設定内の正規表現パターンを調整してください。

次のステップ

重要なイベント (接続障害、しきい値を超えるスロークエリ、エラーの急増) に対するアラートを設定する
クエリパターンごとのスロークエリ分析用に、カスタムダッシュボードを作成する
観測されたクエリ性能の傾向に基づいて、long_query_timeを調整する

本番環境への移行

このガイドでは、すばやくセットアップできるよう、ClickStack に組み込まれている OpenTelemetry Collector をベースにしています。本番環境にデプロイする場合は、独自の OTel collector を実行し、データを ClickStack の OTLP エンドポイントに送信することを推奨します。本番環境向けの構成については、OpenTelemetry データの送信を参照してください。

​既存の MySQL とのインテグレーション

前提条件

​MySQL のログを設定する

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

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

​HyperDX でログを確認する

​デモデータセット

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

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

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

​HyperDX でログを確認する

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

​ ダッシュボード設定

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

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

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

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

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

​スロークエリログが表示されない

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

​次のステップ

​本番環境への移行

既存の MySQL とのインテグレーション

MySQL のログを設定する

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

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

HyperDX でログを確認する

デモデータセット

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

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

デモ設定でClickStackを実行する

HyperDX でログを確認する

ダッシュボードと可視化

ダッシュボード設定

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

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

トラブルシューティング

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

HyperDX にログが表示されない

スロークエリログが表示されない

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

次のステップ

本番環境への移行