ClickStackでMySQLログを監視

ClickStackでMySQLログを監視

要点

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

​

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

このセクションでは、ClickStack OTel collector の設定を変更して、既存の MySQL 環境から ClickStack にログを送信するよう構成する方法を説明します。

既存環境の設定を行う前に MySQL ログのインテグレーションを試したい場合は、“デモデータセット” セクションにある事前構成済みの環境とサンプルデータを使ってテストできます。

前提条件

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

1. ​

   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
   
2. ​

   カスタム 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 を使用します。

3. ​

   カスタム構成を読み込むように 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) を使用し、最小権限の原則に従ってください。

4. ​

   HyperDX でログを確認する

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

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

​

デモデータセット

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

1. ​

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

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

   # エラーログをダウンロード
   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 メッセージ)
   • 現実的なパフォーマンス特性を反映した低速クエリ
   • 接続のライフサイクルイベント
   • データベースサーバーの起動および停止のシーケンス
2. ​

   テスト用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
   
3. ​

   デモ設定で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
   
4. ​

   HyperDX でログを確認する

   ClickStack の起動後:

   1. ClickStack が完全に初期化されるまで少し待ちます (通常は 30〜60 秒)
   2. HyperDX を開いてアカウントにログインします (必要に応じて先にアカウントを作成してください)
   3. Search view に移動し、ログソースを Logs に設定します
   4. 時間範囲を 2025-11-13 00:00:00 - 2025-11-16 00:00:00 に設定します
   5. 合計 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 ログ向けの基本的な可視化を用意しています。

1. ​

   ダッシュボード設定

2. ​

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

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

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

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

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

   デモデータセットでは、時間範囲を 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 データの送信 を参照してください。