> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickStackでMySQLログを監視

> ClickStackでMySQLログを監視

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **要点**

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

<div id="existing-mysql">
  ## 既存の MySQL とのインテグレーション
</div>

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

既存環境の設定を行う前に MySQL ログのインテグレーションを試したい場合は、["デモデータセット"](/ja/clickstack/integration-examples/mysql#demo-dataset) セクションにある事前構成済みの環境とサンプルデータを使ってテストできます。

<div id="prerequisites">
  ##### 前提条件
</div>

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

<Steps>
  <Step>
    #### 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]` セクションに次の設定を追加または変更します。

    ```ini theme={null}
    [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
    ```

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

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

    ```bash theme={null}
    # systemdの場合
    sudo systemctl restart mysql

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

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

    ```bash theme={null}
    # エラーログを確認する
    tail -f /var/log/mysql/error.log

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

  <Step>
    #### カスタム OTel collector の設定を作成する

    ClickStack では、カスタム設定ファイルをマウントして環境変数を設定することで、ベースの OpenTelemetry Collector 設定を拡張できます。このカスタム設定は、HyperDX が OpAMP 経由で管理するベース設定にマージされます。

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

    ```yaml theme={null}
    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 エクスポーターにルーティングします

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

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

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

    ClickStack のデプロイメント構成を更新します:

    ```yaml theme={null}
    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
          # ... その他のボリューム ...
    ```

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

  <Step>
    #### 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` (スロークエリログ) などのフィールドを含む構造化されたログエントリが表示されます

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/mysql/search-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=8e2326a651e60df710f04c8391a04768" alt="Search view" width="3838" height="1934" data-path="images/clickstack/mysql/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/mysql/log-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=10dad89317d5f4dbaef846388d9432da" alt="Log view" width="3838" height="1934" data-path="images/clickstack/mysql/log-view.png" />
  </Step>
</Steps>

<div id="demo-dataset">
  ## デモデータセット
</div>

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

<Steps>
  <Step>
    #### サンプルデータセットをダウンロードする

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

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

  <Step>
    #### テスト用collectorの設定を作成する

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

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step>
    #### デモ設定でClickStackを実行する

    デモ用のログと設定でClickStackを実行します。

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### HyperDX でログを確認する

    ClickStack の起動後:

    1. ClickStack が完全に初期化されるまで少し待ちます (通常は 30〜60 秒)
    2. [HyperDX](http://localhost:8080/) を開いてアカウントにログインします (必要に応じて先にアカウントを作成してください)
    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 件)

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/mysql/search-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=8e2326a651e60df710f04c8391a04768" alt="Search view" width="3838" height="1934" data-path="images/clickstack/mysql/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/mysql/log-view.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=10dad89317d5f4dbaef846388d9432da" alt="Log view" width="3838" height="1934" data-path="images/clickstack/mysql/log-view.png" />

    <Info>
      **タイムゾーン表示**

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

<div id="dashboards">
  ## ダッシュボードと可視化
</div>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/ja/examples/mysql-logs-dashboard.json'} download="mysql-logs-dashboard.json" eventName="docs.mysql_logs_monitoring.dashboard_download">ダウンロード</TrackedLink> ダッシュボード設定
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/import-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=cdfe26f160c1c080b995c8451311241d" alt="ダッシュボードのインポートボタン" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/mysql/finish-import.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=adfa438e4d9c813bd1fc4da17e20f002" alt="インポート完了" width="3374" height="1934" data-path="images/clickstack/mysql/finish-import.png" />
  </Step>

  <Step>
    #### ダッシュボードを表示する

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/OwB6o9ddvLojEP8N/images/clickstack/mysql/example-dashboard.png?fit=max&auto=format&n=OwB6o9ddvLojEP8N&q=85&s=92dbfddb4fede32fd19544727c517195" alt="ダッシュボードの例" width="3812" height="1934" data-path="images/clickstack/mysql/example-dashboard.png" />

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

<div id="troubleshooting">
  ## トラブルシューティング
</div>

<div id="troubleshooting-not-loading">
  ### カスタム設定が読み込まれない
</div>

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

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

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

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10
```

<div id="no-logs">
  ### HyperDX にログが表示されない
</div>

実際に適用されている設定に filelog receiver が含まれていることを確認してください。

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
```

collector のログにエラーがないか確認してください:

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i mysql
```

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

```bash theme={null}
docker exec <container> cat /tmp/mysql-demo/error.log | wc -l
docker exec <container> cat /tmp/mysql-demo/mysql-slow.log | wc -l
```

<div id="no-slow-queries">
  ### スロークエリログが表示されない
</div>

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

```sql theme={null}
SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';
```

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

```bash theme={null}
tail -f /var/log/mysql/mysql-slow.log
```

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

```sql theme={null}
SELECT SLEEP(2);
```

<div id="logs-not-parsing">
  ### ログが正しくパースされない
</div>

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

エラーログの数行を確認してください。

```bash theme={null}
head -5 /var/log/mysql/error.log
```

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

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

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

<div id="next-steps">
  ## 次のステップ
</div>

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

<div id="going-to-production">
  ## 本番環境への移行
</div>

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