Мониторинг журналов MySQL с помощью ClickStack

Интеграция с существующим MySQL

В этом разделе описано, как настроить существующий экземпляр MySQL на отправку журналов в ClickStack, изменив конфигурацию OTel collector в 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 через отдельный конвейер

Настройте ClickStack для загрузки пользовательской конфигурации

Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, смонтируйте файл пользовательской конфигурации по пути /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 и убедитесь, что журналы поступают:

Перейдите в Search view
Установите для source значение Logs
Отфильтруйте по source:mysql-error или source:mysql-slow, чтобы увидеть журналы MySQL
Вы должны увидеть структурированные записи журнала с такими полями, как 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)
Медленные запросы с реалистичными характеристиками производительности
События жизненного цикла подключения
Последовательности запуска и остановки сервера базы данных

Создайте конфигурацию тестового коллектора

Создайте файл с именем 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:

Подождите немного, пока 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)

Панели мониторинга и визуализация

Чтобы помочь вам начать мониторинг MySQL в ClickStack, мы предоставляем основные визуализации для журналов MySQL.

Скачать конфигурацию панели мониторинга

Скачать файл конфигурации панели мониторинга.

Импортируйте преднастроенный дашборд

Откройте HyperDX и перейдите в раздел Dashboards
Нажмите Import Dashboard в правом верхнем углу в меню с многоточием

Загрузите файл 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

Проверьте, что в итоговой конфигурации присутствует ваш ресивер filelog:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

Проверьте журналы коллектора на наличие ошибок:

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 и отправлять данные в конечную точку OTLP ClickStack. См. раздел Отправка данных OpenTelemetry с рекомендациями по конфигурации для продакшн.