Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

使用 ClickStack 监控 MySQL 日志

View as MarkdownEdit this pageReport an issueSet up docs MCP

与现有 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]
# Error log configuration
log_error = /var/log/mysql/error.log

# Slow query log configuration
slow_query_log = ON
slow_query_log_file = /var/log/mysql/mysql-slow.log
long_query_time = 1
log_queries_not_using_indexes = ON

# Optional: General query log (verbose, use with caution in production)
# general_log = ON
# general_log_file = /var/log/mysql/mysql-general.log

完成这些更改后，重启 MySQL：

# For systemd
sudo systemctl restart mysql

# For Docker
docker restart <mysql-container>

确认日志是否正在写入：

# Check error log
tail -f /var/log/mysql/error.log

# Check slow query 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

配置 ClickStack 以加载自定义配置

要在现有的 ClickStack 部署中启用自定义 collector 配置，请将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml，并将环境变量 CUSTOM_OTELCOL_CONFIG_FILE 设置为 /etc/otelcol-contrib/custom.config.yaml。

更新 ClickStack 的部署配置：

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./mysql-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mysql:/var/log/mysql:ro
      # ... other volumes ...

在 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 日志演示数据集，其中包含逼真的日志模式。

下载示例数据集

下载示例日志文件：

# Download error log
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/error.log

# Download slow query 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  # Read from beginning for demo data
    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  # Read from beginning for demo data
    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 运行后：

  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 的慢查询日志)
搜索视图
日志视图

仪表盘与可视化

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

下载仪表盘配置

下载仪表盘配置文件。

导入预构建仪表盘

  1. 打开 HyperDX 并进入“仪表盘”部分
  2. 点击右上角省略号菜单中的 Import Dashboard
导入仪表盘按钮
  1. 上传 mysql-logs-dashboard.json 文件，然后点击 Finish Import
完成导入

查看仪表盘

仪表盘创建后，所有可视化都将预先配置完成。

示例仪表盘

故障排查

自定义配置未加载

确认已设置环境变量：

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

Navigation