Pular para o conteúdo principal
ResumoColete 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árioO 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
  1. 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.
Última modificação em 10 de junho de 2026