Monitoramento dos logs do MySQL com ClickStack

Integração com um MySQL existente

Esta seção explica como configurar sua instalação existente do MySQL para enviar logs ao ClickStack, modificando a configuração do ClickStack OTel collector.

Se quiser testar a integração de logs do MySQL antes de configurar seu próprio ambiente, você pode usar nossa configuração pré-configurada e os dados de exemplo na seção "Conjunto de dados de demonstração".

Pré-requisitos

Instância do ClickStack em execução
Instalação existente do MySQL (versão 5.7 ou superior)
Acesso para modificar os arquivos de configuração do MySQL
Espaço em disco suficiente para os arquivos de log

Configure os logs do MySQL

O MySQL oferece suporte a vários tipos de log. Para um monitoramento abrangente com OpenTelemetry, recomendamos habilitar o log de erros e o log de consultas lentas.

O arquivo de configuração my.cnf ou my.ini normalmente fica em:

Linux (apt/yum): /etc/mysql/my.cnf ou /etc/my.cnf
macOS (Homebrew): /usr/local/etc/my.cnf ou /opt/homebrew/etc/my.cnf
Docker: a configuração geralmente é definida por meio de variáveis de ambiente ou de um arquivo de configuração montado

Adicione ou modifique estas configurações na seção [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

Depois de fazer essas alterações, reinicie o MySQL:

# For systemd
sudo systemctl restart mysql

# For Docker
docker restart <mysql-container>

Verifique se os logs estão sendo registrados:

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

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

Criar configuração personalizada do OTel collector

O ClickStack permite estender a configuração básica do OpenTelemetry Collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente. A configuração personalizada é mesclada à configuração básica gerenciada pelo HyperDX via OpAMP.

Crie um arquivo chamado mysql-logs-monitoring.yaml com a seguinte configuração:

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 configuração:

Lê os logs de erro do MySQL e os logs de consultas lentas de seus locais padrão
Processa entradas de log com várias linhas (consultas lentas ocupam várias linhas)
Analisa os dois formatos de log para extrair campos estruturados (level, error_code, query_time, rows_examined)
Preserva os timestamps originais dos logs
Adiciona os atributos source: mysql-error e source: mysql-slow para filtragem no HyperDX
Encaminha os logs para o ClickHouse exporter por meio de um pipeline dedicado

Configure o ClickStack para carregar uma configuração personalizada

Para habilitar uma configuração personalizada do collector na implantação existente do ClickStack, monte o arquivo de configuração personalizado em /etc/otelcol-contrib/custom.config.yaml e defina a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml.

Atualize a configuração de implantação do 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 ...

Verificando logs no HyperDX

Depois de configurar, faça login no HyperDX e verifique se os logs estão fluindo:

Vá para a visualização Busca
Defina a source como Logs
Filtre por source:mysql-error ou source:mysql-slow para ver logs específicos do MySQL
Você deverá ver entradas de log estruturadas com campos como level, error_code, message (para logs de erro) e query_time, rows_examined, query (para logs de consultas lentas)

Conjunto de dados de demonstração

Para usuários que desejam testar a integração de logs do MySQL antes de configurar seus sistemas em produção, fornecemos um conjunto de dados de exemplo com logs do MySQL pré-gerados e padrões realistas.

Baixe o conjunto de dados de amostra

Baixe os arquivos de log de amostra:

# 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

O conjunto de dados inclui:

Registros de erro no log (mensagens de inicialização, avisos, erros de conexão, mensagens do InnoDB)
Consultas lentas com características de desempenho realistas
Eventos do ciclo de vida da conexão
Sequências de inicialização e desligamento do servidor de banco de dados

Criar a configuração do coletor de teste

Crie um arquivo chamado mysql-logs-demo.yaml com a seguinte configuração:

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

Execute o ClickStack com a configuração de demo

Execute o ClickStack com os logs e a configuração de demo:

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

Verifique os logs no HyperDX

Quando o ClickStack estiver em execução:

Aguarde alguns instantes para que o ClickStack seja inicializado por completo (normalmente, de 30 a 60 segundos)
Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
Navegue até a visualização Busca e defina a source como Logs
Defina o intervalo de tempo como 2025-11-13 00:00:00 - 2025-11-16 00:00:00
Você deverá ver 40 logs no total (30 logs de erro com source:mysql-demo-error + 10 consultas lentas com source:mysql-demo-slow)

Painéis e visualização

Para ajudar você a começar a monitorar o MySQL com o ClickStack, fornecemos visualizações essenciais para os logs do MySQL.

Baixar a configuração do painel

Baixar o arquivo de configuração do painel.

Importe o painel pré-configurado

Abra o HyperDX e vá para a seção Painéis
Clique em Importar painel no canto superior direito, no menu de reticências

Faça upload do arquivo mysql-logs-dashboard.json e clique em Finish Import

Visualize o painel

O painel será criado com todas as visualizações pré-configuradas.

Solução de problemas

Config personalizada não carrega

Verifique se a variável de ambiente está definida:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Verifique se o arquivo de configuração personalizado está montado e legível:

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

Logs não aparecem no HyperDX

Verifique se a config efetiva inclui o receiver filelog:

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

Verifique se há erros nos logs do collector:

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

Se estiver usando o conjunto de dados de demonstração, verifique se os arquivos de log estão acessíveis:

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

Logs de consultas lentas não aparecem

Verifique se o log de consultas lentas está habilitado no MySQL:

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

Verifique se o MySQL está gravando consultas lentas:

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

Gere uma consulta lenta para teste:

SELECT SLEEP(2);

Logs não estão sendo interpretados corretamente

Verifique se o formato de log do MySQL corresponde ao formato esperado. Os padrões regex neste guia foram projetados para os formatos padrão do MySQL 5.7+ e 8.0+.

Verifique algumas linhas do seu log de erros:

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

Se o seu formato for significativamente diferente, ajuste os padrões de regex na configuração.

Próximos passos

Configure alertas para eventos críticos (falhas de conexão, consultas lentas que ultrapassam os limites, picos de erros)
Crie painéis personalizados para analisar consultas lentas por padrão de consulta
Ajuste long_query_time com base nos padrões observados de desempenho das consultas

Preparando para produção

Este guia se baseia no OpenTelemetry Collector integrado do ClickStack para uma configuração rápida. Para implantações em produção, recomendamos executar seu próprio OTel Collector e enviar os dados para o endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para a configuração de produção.