使用 ClickStack 监控 MySQL 日志 - ClickHouse Documentation

简而言之使用 OTel filelog 接收器在 ClickStack 中收集并可视化 MySQL 错误日志和慢查询日志。包含演示数据集和预构建仪表盘。

与现有 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)
保留原始日志时间戳
添加 source: mysql-error 和 source: mysql-slow 属性，便于在 HyperDX 中过滤
通过专用管道将日志发送到 ClickHouse exporter

之所以需要两个 receiver，是因为 MySQL 错误日志和慢查询日志的格式完全不同。time_parser 使用 gotime layout 来处理 MySQL 带时区偏移的 ISO8601 时间戳格式。

配置 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 并确认日志已正常流入：

进入搜索视图
将 source 设为 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 并登录账户 (你可能需要先创建账户)
进入搜索视图，将数据源设为 Logs
将时间范围设置为 2025-11-13 00:00:00 - 2025-11-16 00:00:00
你应会看到总共 40 条日志 (30 条带有 source:mysql-demo-error 的错误日志 + 10 条带有 source:mysql-demo-slow 的慢查询日志)

如果没有立即看到全部 40 条日志，请等待约一分钟，让 collector 完成处理。如果等待后日志仍未出现，请运行 docker restart clickstack-demo，再过一分钟后重新检查。这是 OpenTelemetry filelog receiver 在使用 start_at: beginning 批量加载已有文件时的已知问题。生产部署使用 start_at: end 时，会在日志写入时进行实时处理，因此不会遇到这个问题。

时区显示HyperDX 会按浏览器的本地时区显示时间戳。演示数据的时间范围为 2025-11-14 00:00:00 - 2025-11-15 00:00:00 (UTC)。较宽的时间范围可确保你无论身在何处都能看到演示日志。看到日志后，你可以将范围缩小到 24 小时，以获得更清晰的可视化效果。

仪表盘与可视化

为帮助你快速开始使用 ClickStack 监控 MySQL，我们提供了 MySQL 日志所需的关键可视化。

仪表盘配置文件

导入预构建仪表盘

打开 HyperDX 并进入“仪表盘”部分
点击右上角省略号菜单中的 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 中未显示日志

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

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 中未显示日志

慢查询日志未出现

日志解析不正确

后续步骤

投入生产环境