Monitoramento de logs do Kafka com ClickStack

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.)

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:

# Default locations
ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
ls /var/log/kafka/        # RPM/DEB package installations

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)

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  # optional, only exists if log4j is configured with separate file appenders
      - /var/log/kafka/state-change.log  # optional, same as above
    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

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:

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

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

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

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.

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

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

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:

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

Dashboards e visualização

Baixar a configuração do dashboard

Baixar o arquivo de configuração do dashboard.

Importe o dashboard pré-configurado

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

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

Concluir a importação do dashboard de logs do Kafka

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

Para o conjunto de dados 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 dados para o endpoint OTLP do ClickStack. Consulte Enviando dados do OpenTelemetry para a configuração de produção.