使用 ClickStack 监控 MySQL 日志

使用 ClickStack 监控 MySQL 日志

简而言之

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

​

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

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

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. 进入搜索视图
   2. 将 source 设为 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. 进入搜索视图，将数据源设为 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 的慢查询日志)

   如果没有立即看到全部 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 日志所需的关键可视化。

1. ​

   仪表盘配置文件

2. ​

   导入预构建仪表盘

   1. 打开 HyperDX 并进入“仪表盘”部分
   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 中未显示日志

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

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 数据。