> ## 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` 接收器在 ClickStack 中收集并可视化 MySQL 错误日志和慢查询日志。包含演示数据集和预构建仪表盘。
</Info>

<div id="existing-mysql">
  ## 与现有 MySQL 集成
</div>

本节介绍如何通过修改 ClickStack OTel collector 配置，将现有的 MySQL 实例配置为把日志发送到 ClickStack。

如果您想先测试 MySQL 日志集成，再配置自己现有的环境，可以在["演示数据集"](/zh/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)
    * 保留原始日志时间戳
    * 添加 `source: mysql-error` 和 `source: mysql-slow` 属性，便于在 HyperDX 中过滤
    * 通过专用管道将日志发送到 ClickHouse exporter

    <Note>
      之所以需要两个 receiver，是因为 MySQL 错误日志和慢查询日志的格式完全不同。`time_parser` 使用 `gotime` layout 来处理 MySQL 带时区偏移的 ISO8601 时间戳格式。
    </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. 进入搜索视图
    2. 将 source 设为 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="搜索视图" 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="日志视图" 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. 进入搜索视图，将数据源设为 `Logs`
    4. 将时间范围设置为 **2025-11-13 00:00:00 - 2025-11-16 00:00:00**
    5. 你应会看到总共 40 条日志 (30 条带有 `source:mysql-demo-error` 的错误日志 + 10 条带有 `source:mysql-demo-slow` 的慢查询日志)

    <Note>
      如果没有立即看到全部 40 条日志，请等待约一分钟，让 collector 完成处理。如果等待后日志仍未出现，请运行 `docker restart clickstack-demo`，再过一分钟后重新检查。这是 OpenTelemetry filelog receiver 在使用 `start_at: beginning` 批量加载已有文件时的已知问题。生产部署使用 `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="搜索视图" 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="日志视图" 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={'/zh/examples/mysql-logs-dashboard.json'} download="mysql-logs-dashboard.json" eventName="docs.mysql_logs_monitoring.dashboard_download">下载</TrackedLink>仪表盘配置文件
  </Step>

  <Step>
    #### 导入预构建仪表盘

    1. 打开 HyperDX 并进入“仪表盘”部分
    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>

检查当前生效的配置中是否包含 接收器：

```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>

* 为关键事件设置[告警](/zh/clickstack/features/alerts) (如连接失败、超过阈值的慢查询、错误激增)
* 按查询模式创建用于分析慢查询的自定义仪表盘
* 根据观察到的查询性能表现调优 `long_query_time`

<div id="going-to-production">
  ## 投入生产环境
</div>

本指南基于 ClickStack 内置的 OpenTelemetry Collector，便于快速完成设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅 [发送 OpenTelemetry 数据](/zh/clickstack/ingesting-data/opentelemetry)。