Monitoramento dos logs do MySQL com ClickStack

Monitoramento dos logs do MySQL com ClickStack

Resumo

Colete e visualize logs de erro e de consultas lentas do MySQL no ClickStack usando o receiver filelog do OTel. Inclui um conjunto de dados de demonstração e um painel pré-configurado.

​

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

1. ​

   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]
   # Configuração do log de erros
   log_error = /var/log/mysql/error.log
   
   # Configuração do log de consultas lentas
   slow_query_log = ON
   slow_query_log_file = /var/log/mysql/mysql-slow.log
   long_query_time = 1
   log_queries_not_using_indexes = ON
   
   # Opcional: Log geral de consultas (verboso, use com cautela em produção)
   # general_log = ON
   # general_log_file = /var/log/mysql/mysql-general.log
   

   O log de consultas lentas registra consultas que levam mais de long_query_time segundos. Ajuste esse limite de acordo com os requisitos de desempenho da sua aplicação. Defini-lo baixo demais gerará logs em excesso.

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

   # Para systemd
   sudo systemctl restart mysql
   
   # Para Docker
   docker restart <mysql-container>
   

   Verifique se os logs estão sendo registrados:

   # Verificar log de erros
   tail -f /var/log/mysql/error.log
   
   # Verificar log de consultas lentas
   tail -f /var/log/mysql/mysql-slow.log
   
2. ​

   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

   Dois receivers são necessários porque os logs de erro do MySQL e os logs de consultas lentas têm formatos completamente diferentes. O time_parser usa o layout gotime para lidar com o formato de timestamp ISO8601 do MySQL com deslocamentos de fuso horário.

3. ​

   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:
       # ... configuração existente ...
       environment:
         - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
         # ... outras variáveis de ambiente ...
       volumes:
         - ./mysql-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
         - /var/log/mysql:/var/log/mysql:ro
         # ... outros volumes ...
   

   Certifique-se de que o coletor do ClickStack tenha as permissões adequadas para ler os arquivos de log do MySQL. Use montagens somente leitura (:ro) e siga o princípio do privilégio mínimo.

4. ​

   Verificando logs no HyperDX

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

   1. Vá para a visualização Busca
   2. Defina a source como Logs
   3. Filtre por source:mysql-error ou source:mysql-slow para ver logs específicos do MySQL
   4. 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.

1. ​

   Baixe o conjunto de dados de amostra

   Baixe os arquivos de log de amostra:

   # Baixar log de erros
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mysql/error.log
   
   # Baixar log de consultas lentas
   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
2. ​

   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  # Lê desde o início para dados de demonstração
       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  # Lê desde o início para dados de demonstração
       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. ​

   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
   
4. ​

   Verifique os logs no HyperDX

   Quando o ClickStack estiver em execução:

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

   Se você não vir todos os 40 logs imediatamente, aguarde cerca de um minuto para o collector concluir o processamento. Se os logs ainda não aparecerem depois disso, execute docker restart clickstack-demo e verifique novamente após mais um minuto. Este é um problema conhecido do receiver filelog do OpenTelemetry ao carregar em massa arquivos preexistentes com start_at: beginning. Implantações em produção que usam start_at: end processam os logs à medida que são gravados em tempo real e não apresentam esse problema.

   Exibição de fuso horário

   O HyperDX exibe os timestamps no fuso horário local do seu navegador. Os dados de demonstração abrangem 2025-11-14 00:00:00 - 2025-11-15 00:00:00 (UTC). O intervalo de tempo mais amplo garante que você verá os logs de demonstração independentemente da sua localização. Assim que os logs aparecerem, você poderá restringir o intervalo para um período de 24 horas e obter visualizações mais claras.

​

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.

1. ​

   a configuração do painel

2. ​

   Importe o painel pré-configurado

   1. Abra o HyperDX e vá para a seção Dashboards
   2. Clique em Import Dashboard no canto superior direito, no menu de reticências

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

   Visualize o painel

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

   Para o conjunto de dados de demonstração, defina o intervalo de tempo como 2025-11-14 00:00:00 - 2025-11-15 00:00:00 (UTC) (ajuste conforme o seu fuso horário local). Por padrão, o painel importado não terá um intervalo de tempo definido.

​

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

​

Indo para produção

Este guia aproveita o 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.