Monitorización de logs de MySQL con ClickStack

Integración con MySQL existente

En esta sección se explica cómo configurar su instalación existente de MySQL para enviar logs a ClickStack modificando la configuración del OTel collector de ClickStack.

Si desea probar la integración de logs de MySQL antes de configurar su propio entorno, puede usar nuestra configuración predefinida y datos de ejemplo en la sección "conjunto de datos de demostración".

Requisitos previos

Instancia de ClickStack en ejecución
Instalación existente de MySQL (versión 5.7 o posterior)
Acceso para modificar los archivos de configuración de MySQL
Espacio suficiente en disco para los archivos de registro

Configurar el registro de MySQL

MySQL admite varios tipos de registros. Para una monitorización completa con OpenTelemetry, recomendamos habilitar el registro de errores y el registro de consultas lentas.

El archivo de configuración my.cnf o my.ini suele encontrarse en:

Linux (apt/yum): /etc/mysql/my.cnf o /etc/my.cnf
macOS (Homebrew): /usr/local/etc/my.cnf o /opt/homebrew/etc/my.cnf
Docker: La configuración suele establecerse mediante variables de entorno o un archivo de configuración montado

Añada o modifique estos parámetros en la sección [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

Después de realizar estos cambios, reinicia MySQL:

# For systemd
sudo systemctl restart mysql

# For Docker
docker restart <mysql-container>

Verifique que se estén escribiendo los logs:

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

# Check slow query log
tail -f /var/log/mysql/mysql-slow.log

Crear una configuración personalizada de OTel collector

ClickStack le permite ampliar la configuración base de OpenTelemetry Collector montando un archivo de configuración personalizado y estableciendo una variable de entorno. La configuración personalizada se fusiona con la configuración base administrada por HyperDX mediante OpAMP.

Cree un archivo llamado mysql-logs-monitoring.yaml con la siguiente configuración:

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

Esta configuración:

Lee los logs de errores de MySQL y los logs de consultas lentas desde sus ubicaciones estándar
Gestiona entradas de log de varias líneas (las consultas lentan abarcan varias líneas)
Analiza ambos formatos de log para extraer campos estructurados (level, error_code, query_time, rows_examined)
Conserva las marcas de tiempo originales de los logs
Añade los atributos source: mysql-error y source: mysql-slow para filtrar en HyperDX
Envía los logs al exportador de ClickHouse mediante un pipeline dedicado

Configura ClickStack para cargar una configuración personalizada

Para habilitar una configuración personalizada del colector en tu despliegue existente de ClickStack, monta el archivo de configuración personalizado en /etc/otelcol-contrib/custom.config.yaml y establece la variable de entorno CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml.

Actualiza la configuración de despliegue de 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 ...

Verificar logs en HyperDX

Una vez configurado, inicia sesión en HyperDX y verifica que se estén recibiendo logs:

Ve a la vista de búsqueda
Establece source en Logs
Filtra por source:mysql-error o source:mysql-slow para ver logs específicos de MySQL
Deberías ver entradas de log estructuradas con campos como level, error_code, message (para logs de error) y query_time, rows_examined, query (para logs de consultas lentas)

Conjunto de datos de demostración

Para quienes quieran probar la integración de logs de MySQL antes de configurar sus sistemas de producción, proporcionamos un conjunto de datos de ejemplo con logs de MySQL generados previamente y patrones realistas.

Descargar el conjunto de datos de ejemplo

Descargue los archivos de log de ejemplo:

# 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

El conjunto de datos incluye:

Entradas del registro de errores (mensajes de inicio, advertencias, errores de conexión, mensajes de InnoDB)
Consultas lentas con características de rendimiento realistas
Eventos del ciclo de vida de las conexiones
Secuencias de inicio y apagado del servidor de base de datos

Crear la configuración del collector de prueba

Crea un archivo llamado mysql-logs-demo.yaml con la siguiente configuración:

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

Ejecuta ClickStack con la configuración de demostración

Ejecuta ClickStack con los logs de demostración y la configuración de demostración:

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

Verifica los logs en HyperDX

Una vez que ClickStack esté en ejecución:

Espera unos instantes a que ClickStack se inicialice por completo (normalmente, entre 30 y 60 segundos)
Abre HyperDX e inicia sesión en tu cuenta (puede que primero tengas que crear una cuenta)
Ve a Search view y establece la source en Logs
Establece el intervalo de tiempo en 2025-11-13 00:00:00 - 2025-11-16 00:00:00
Deberías ver 40 logs en total (30 logs de error con source:mysql-demo-error + 10 consultas lentas con source:mysql-demo-slow)

Dashboards y visualización

Para ayudarte a empezar a supervisar MySQL con ClickStack, proporcionamos visualizaciones esenciales para los logs de MySQL.

Descargar la configuración del dashboard

Descargar el archivo de configuración del dashboard.

Importa el dashboard preconfigurado

Abre HyperDX y ve a la sección Dashboards
Haz clic en Import Dashboard en la esquina superior derecha, dentro del menú de puntos suspensivos

Sube el archivo mysql-logs-dashboard.json y haz clic en Finish Import

Ver el dashboard

El dashboard se creará con todas las visualizaciones ya configuradas.

Solución de problemas

La configuración personalizada no se carga

Verifique que la variable de entorno esté configurada:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Comprueba que el archivo de configuración personalizado esté montado y se pueda leer:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml | head -10

No aparecen logs en HyperDX

Comprueba que la configuración efectiva incluya tu receiver filelog:

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

Compruebe si hay errores en los logs del collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i mysql

Si utiliza el conjunto de datos de demostración, verifique que se pueda acceder a los archivos de registro:

docker exec <container> cat /tmp/mysql-demo/error.log | wc -l
docker exec <container> cat /tmp/mysql-demo/mysql-slow.log | wc -l

El registro de consultas lentas no aparece

Verifique que el registro de consultas lentas esté habilitado en MySQL:

SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';

Compruebe si MySQL está registrando consultas lentas:

tail -f /var/log/mysql/mysql-slow.log

Genere una consulta lenta de prueba:

SELECT SLEEP(2);

Los logs no se procesan correctamente

Verifique que el formato de logs de MySQL coincida con el formato esperado. Los patrones de expresiones regulares de esta guía están diseñados para los formatos predeterminados de MySQL 5.7+ y 8.0+.

Revise algunas líneas del registro de errores:

head -5 /var/log/mysql/error.log

Formato esperado:

2025-11-14T10:23:45.123456+00:00 0 [System] [MY-010116] [Server] /usr/sbin/mysqld (mysqld 8.0.35) starting as process 1

Si el formato difiere significativamente, ajusta los patrones regex en la configuración.

Próximos pasos

Configura alertas para eventos críticos (fallos de conexión, consultas lentas que superan los umbrales y picos de errores)
Crea dashboards personalizados para analizar consultas lentas por patrón de consulta
Ajusta long_query_time en función de los patrones de rendimiento observados en las consultas

Paso a producción

Esta guía amplía el OpenTelemetry Collector integrado de ClickStack para facilitar una configuración rápida. Para implementaciones de producción, recomendamos ejecutar su propio OTel Collector y enviar los datos al endpoint OTLP de ClickStack. Consulte Envío de datos de OpenTelemetry para ver una configuración de producción.