Monitoramento de logs do Kafka com ClickStack

Monitoramento de logs do Kafka com ClickStack

Resumo

Colete e visualize os logs do broker Kafka (formato Log4j) no ClickStack usando o receiver filelog do OTel. Inclui um conjunto de dados de demonstração e um dashboard pré-configurado.

​

Integração com Kafka existente

Esta seção aborda como configurar sua instalação existente do Kafka para enviar logs do broker ao ClickStack, alterando a configuração do OTel collector do ClickStack. Se você quiser testar a integração de logs do Kafka antes de configurar seu próprio ambiente, poderá 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 Kafka (versão 2.0 ou superior)
• Acesso aos arquivos de log do Kafka (server.log, controller.log, etc.)

1. ​

   Verifique a configuração de logging do Kafka

   O Kafka usa Log4j e grava os logs no diretório especificado pela propriedade do sistema kafka.logs.dir ou pela variável de ambiente LOG_DIR. Verifique onde seu arquivo de log está localizado:

   # Localizações padrão
   ls $KAFKA_HOME/logs/      # Apache Kafka padrão (padrão: <install-dir>/logs/)
   ls /var/log/kafka/        # Instalações via pacote RPM/DEB
   

   Principais arquivos de log do Kafka:

   • server.log: Logs gerais do broker (inicialização, conexões, replicação, erros)
   • controller.log: Eventos específicos do controlador (eleição de líder, reatribuição de partições)
   • state-change.log: Transições de estado de partições e réplicas

   O padrão do Log4j do Kafka produz linhas como:

   [2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)
   

   Para implantações do Kafka baseadas em Docker (por exemplo, confluentinc/cp-kafka), a configuração padrão do Log4j inclui apenas um appender de console — não há appender de arquivo, portanto os logs são gravados apenas no stdout. Para usar o receiver filelog, você precisará redirecionar os logs para um arquivo, seja adicionando um appender de arquivo ao log4j.properties ou encaminhando o stdout por um pipe (por exemplo, | tee /var/log/kafka/server.log).

2. ​

   Crie uma configuração personalizada do OTel collector para o Kafka

   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 kafka-logs-monitoring.yaml com a seguinte configuração:

   receivers:
     filelog/kafka:
       include:
         - /var/log/kafka/server.log
         - /var/log/kafka/controller.log  # opcional, só existe se o log4j estiver configurado com appenders de arquivo separados
         - /var/log/kafka/state-change.log  # opcional, mesmo caso acima
       start_at: beginning
       multiline:
         line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
       operators:
         - type: regex_parser
           regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
           parse_from: body
           parse_to: attributes
           timestamp:
             parse_from: attributes.timestamp
             layout: '%Y-%m-%d %H:%M:%S,%L'
           severity:
             parse_from: attributes.severity
   
         - type: move
           from: attributes.message
           to: body
   
         - type: add
           field: attributes.source
           value: "kafka"
   
         - type: add
           field: resource["service.name"]
           value: "kafka-production"
   
   service:
     pipelines:
       logs/kafka:
         receivers: [filelog/kafka]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   

   • Você só precisa definir novos receivers e pipelines na configuração personalizada. Os processors (memory_limiter, transform, batch) e exporters (clickhouse) já estão definidos na configuração base do ClickStack — basta referenciá-los pelo nome.
   • A configuração multiline garante que stack traces sejam capturados como uma única entrada de log.
   • Esta configuração usa start_at: beginning para ler todos os logs existentes quando o coletor é iniciado. Em implantações de produção, altere para start_at: end para evitar ingerir novamente os logs quando o coletor for reiniciado.
3. ​

   Configure o ClickStack para carregar uma configuração personalizada

   Para habilitar uma configuração personalizada do coletor na implantação existente do ClickStack, você deve:

   1. Montar o arquivo de configuração personalizado em /etc/otelcol-contrib/custom.config.yaml
   2. Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
   3. Montar o diretório de logs do Kafka para que o coletor possa lê-los

   Docker Compose

   Atualize a configuração da 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:
         - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
         - /var/log/kafka:/var/log/kafka:ro
         # ... outros volumes ...
   

   Docker Run (Imagem All-in-One)

   Se você estiver usando a imagem all-in-one com Docker, execute:

   docker run --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v /var/log/kafka:/var/log/kafka:ro \
     clickhouse/clickstack-all-in-one:latest
   

   Certifique-se de que o coletor do ClickStack tenha as permissões adequadas para ler os arquivos de log do Kafka. Em produção, use montagens somente leitura (:ro) e siga o princípio do menor privilégio.

4. ​

   Verifique os logs no HyperDX

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

​

Conjunto de dados de demonstração

Teste a integração de logs do Kafka com um conjunto de dados de amostra pré-gerado antes de configurar seus sistemas de produção.

1. ​

   Baixe o conjunto de dados de amostra

   Baixe o arquivo de log de amostra:

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log
   
2. ​

   Crie uma configuração de teste do collector

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

   cat > kafka-logs-demo.yaml << 'EOF'
   receivers:
     filelog/kafka:
       include:
         - /tmp/kafka-demo/server.log
       start_at: beginning
       multiline:
         line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
       operators:
         - type: regex_parser
           regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
           parse_from: body
           parse_to: attributes
           timestamp:
             parse_from: attributes.timestamp
             layout: '%Y-%m-%d %H:%M:%S,%L'
           severity:
             parse_from: attributes.severity
   
         - type: move
           from: attributes.message
           to: body
   
         - type: add
           field: attributes.source
           value: "kafka-demo"
   
         - type: add
           field: resource["service.name"]
           value: "kafka-demo"
   
   service:
     pipelines:
       logs/kafka-demo:
         receivers: [filelog/kafka]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   EOF
   
3. ​

   Execute o ClickStack com a configuração de demonstração

   Execute o ClickStack com os logs de demonstração e essa configuração:

   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)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
     clickhouse/clickstack-all-in-one:latest
   

   ​

   Verifique os logs no HyperDX

   Depois que o ClickStack estiver em execução:

   1. Abra o HyperDX e faça login na sua conta (talvez seja necessário criar uma conta primeiro)
   2. Vá para a Search view e defina a source como Logs
   3. Defina o intervalo de tempo para incluir 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

​

Dashboards e visualização

1. ​

   a configuração do dashboard

2. ​

   Importe o dashboard pré-configurado

   1. Abra o HyperDX e navegue até a seção Dashboards.
   2. Clique em “Import Dashboard” no canto superior direito, no menu de reticências.

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

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

   Para o dataset de demonstração, defina o intervalo de tempo para incluir 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC).

​

Solução de problemas

Verifique se a configuração efetiva inclui o receiver filelog:

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

Verifique se há erros no collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log

Verifique se o formato de logs do Kafka corresponde ao padrão esperado:

tail -1 /var/log/kafka/server.log

Se a sua instalação do Kafka usar um padrão personalizado do Log4j, ajuste a regex do regex_parser conforme necessário.

​

Próximos passos

• Configure alertas para eventos críticos (falhas de broker, erros de replicação e problemas de consumer group)
• Use junto com Kafka Metrics para um monitoramento completo do Kafka
• Crie dashboards adicionais para casos de uso específicos (eventos do controller, reatribuição de partições)

​

Colocando em 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.