Monitoramento de métricas do Kafka com ClickStack

Integração com uma implantação existente do Kafka

Monitore sua implantação atual do Kafka executando o contêiner OpenTelemetry JMX Metric Gatherer para coletar métricas e enviá-las ao ClickStack via OTLP.

Se quiser testar essa integração primeiro sem modificar sua configuração atual, vá para a seção do dataset de demonstração.

Pré-requisitos

Instância do ClickStack em execução
Instalação existente do Kafka (versão 2.0 ou superior) com JMX habilitado
Acesso à rede entre o ClickStack e o Kafka (porta JMX 9999, porta Kafka 9092)
JAR do OpenTelemetry JMX Metric Gatherer (instruções de download abaixo)

Obtenha a API key do ClickStack

O JMX Metric Gatherer envia dados para o endpoint OTLP do ClickStack, que exige autenticação.

Abra o HyperDX na URL do seu ClickStack (por exemplo, http://localhost:8080)
Crie uma conta ou faça login, se necessário
Acesse Team Settings → API Keys
Copie sua API key de ingestão

Defina-a como uma variável de ambiente:

export CLICKSTACK_API_KEY=your-api-key-here

Faça download do JMX Metric Gatherer do OpenTelemetry

Baixe o arquivo JAR do JMX Metric Gatherer:

curl -L -o opentelemetry-jmx-metrics.jar \
  https://github.com/open-telemetry/opentelemetry-java-contrib/releases/download/v1.32.0/opentelemetry-jmx-metrics.jar

Verifique se o JMX do Kafka está habilitado

Certifique-se de que o JMX esteja habilitado nos brokers do Kafka. Para implantações com Docker:

services:
  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      # ... other Kafka configuration
    ports:
      - "9092:9092"
      - "9999:9999"

Para implantações que não usam Docker, defina o seguinte na inicialização do Kafka:

export JMX_PORT=9999

Verifique se o JMX está acessível:

netstat -an | grep 9999

Implante o JMX Metric Gatherer com Docker Compose

Este exemplo mostra uma configuração completa com Kafka, o JMX Metric Gatherer e ClickStack. Ajuste os nomes dos serviços e os endpoints para corresponder à sua implantação existente:

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring

  kafka:
    image: confluentinc/cp-kafka:latest
    hostname: kafka
    container_name: kafka
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:9092'
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://kafka:9092,CONTROLLER://kafka:29093'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      KAFKA_JMX_OPTS: '-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=kafka -Dcom.sun.management.jmxremote.rmi.port=9999'
    ports:
      - "9092:9092"
      - "9999:9999"
    networks:
      - monitoring

  kafka-jmx-exporter:
    image: eclipse-temurin:11-jre
    depends_on:
      - kafka
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./opentelemetry-jmx-metrics.jar:/app/opentelemetry-jmx-metrics.jar
    command: >
      sh -c "java
      -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi
      -Dotel.jmx.target.system=kafka
      -Dotel.metrics.exporter=otlp
      -Dotel.exporter.otlp.protocol=http/protobuf
      -Dotel.exporter.otlp.endpoint=http://clickstack:4318
      -Dotel.exporter.otlp.headers=authorization=\${CLICKSTACK_API_KEY}
      -Dotel.resource.attributes=service.name=kafka,kafka.broker.id=broker-0
      -Dotel.jmx.interval.milliseconds=10000
      -jar /app/opentelemetry-jmx-metrics.jar"
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Principais parâmetros de configuração:

service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi - URL de conexão JMX (use o hostname do seu Kafka)
otel.jmx.target.system=kafka - Habilita métricas específicas do Kafka
http://clickstack:4318 - endpoint HTTP OTLP (use o hostname do seu ClickStack)
authorization=\${CLICKSTACK_API_KEY} - API key para autenticação (obrigatória)
service.name=kafka,kafka.broker.id=broker-0 - Atributos de resource para filtragem
10000 - Intervalo de coleta em milissegundos (10 segundos)

Verifique as métricas no HyperDX

Faça login no HyperDX e confirme que as métricas estão sendo coletadas:

Acesse o Chart Explorer
Pesquise por kafka.message.count ou kafka.partition.count
As métricas devem aparecer em intervalos de 10 segundos

Principais métricas para verificar:

kafka.message.count - Total de mensagens processadas
kafka.partition.count - Total de partições
kafka.partition.under_replicated - Deve ser 0 em um cluster saudável
kafka.network.io - Throughput de rede
kafka.request.time.* - Percentis de latência das requisições

Para gerar atividade e preencher mais métricas:

# Create a test topic
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Send test messages
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

Dataset de demonstração

Para usuários que querem testar a integração Kafka Metrics antes de configurar seus sistemas de produção, fornecemos um dataset pré-gerado com padrões realistas de métricas do Kafka.

Baixe o dataset de exemplo de métricas

Baixe os arquivos de métricas pré-gerados (29 horas de métricas do Kafka com padrões realistas):

# Baixe métricas gauge (contagem de partições, tamanhos de filas, latências, consumer lag)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-gauge.csv

# Baixe métricas sum (taxas de mensagens, taxas de bytes, contagem de requisições)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-sum.csv

O dataset inclui padrões realistas para um cluster Kafka de e-commerce com um único broker:

06:00-08:00: Pico da manhã - Aumento acentuado do tráfego em relação ao nível da madrugada
10:00-10:15: Promoção relâmpago - Pico dramático para 3,5x o tráfego normal
11:30: Evento de Implantação - Pico de 12x no consumer lag com partições sub-replicadas
14:00-15:30: Pico de compras - Tráfego intensamente elevado e sustentado em 2,8x o nível de base
17:00-17:30: Pico após o expediente - Pico secundário de tráfego
18:45: Rebalanceamento do consumer - Pico de 6x no lag durante o rebalanceamento
20:00-22:00: Queda no período da noite - Queda acentuada até os níveis da madrugada

Inicie o ClickStack

Inicie uma instância do ClickStack:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

Carregue as métricas no ClickStack

Carregue as métricas diretamente no ClickHouse:

# Carregue métricas gauge (contagem de partições, tamanhos de filas, latências, consumer lag)
cat kafka-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# Carregue métricas sum (taxas de mensagens, taxas de bytes, contagem de requisições)
cat kafka-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"

Verifique as métricas no HyperDX

Depois de carregar os dados, a forma mais rápida de ver suas métricas é pelo dashboard pré-configurado.

Vá para a seção Dashboards e visualizações para importar o dashboard e visualizar todas as métricas do Kafka de uma só vez.

Dashboards e visualizações

Para ajudar você a começar a monitorar o Kafka com o ClickStack, fornecemos visualizações essenciais para as métricas do Kafka.

Baixe a configuração do dashboard

Baixe o arquivo de configuração do dashboard.

Importe o dashboard pré-configurado

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

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

Visualize o dashboard

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

Solução de problemas

Nenhuma métrica aparece no HyperDX

Verifique se a chave de API está configurada e sendo passada para o container:

# Verificar variável de ambiente
echo $CLICKSTACK_API_KEY

# Verificar se está no container
docker exec <jmx-exporter-container> env | grep CLICKSTACK_API_KEY

Se não estiver definido, defina-o e reinicie:

export CLICKSTACK_API_KEY=your-api-key-here
docker compose up -d kafka-jmx-exporter

Verifique se as métricas estão chegando ao ClickHouse:

docker exec <clickstack-container> clickhouse-client --query "
SELECT DISTINCT MetricName 
FROM otel_metrics_sum 
WHERE ServiceName = 'kafka' 
LIMIT 10
"

Se você não vir nenhum resultado, verifique os logs do exporter JMX:

docker compose logs kafka-jmx-exporter | grep -i "error\|connection" | tail -10

Gere atividade no Kafka para popular as métricas:

# Criar um tópico de teste
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Enviar mensagens de teste
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

Erros de autenticação

Se você vir Authorization failed ou 401 Unauthorized:

Verifique a API key na UI do HyperDX (Settings → API Keys → Ingestion API Key)
Exporte novamente e reinicie:

export CLICKSTACK_API_KEY=your-correct-api-key
docker compose down
docker compose up -d

Conflitos de porta com comandos do cliente Kafka

Ao executar comandos do cliente Kafka de dentro do contêiner do Kafka, você poderá ver:

Error: Port already in use: 9999

Adicione o prefixo unset JMX_PORT && aos comandos:

docker exec kafka bash -c "unset JMX_PORT && kafka-topics --list --bootstrap-server kafka:9092"

Problemas de conectividade de rede

Se os logs do exporter JMX mostrarem Connection refused:

Verifique se todos os contêineres estão na mesma rede do Docker:

docker compose ps
docker network inspect <network-name>

Teste a conectividade:

# Do exportador JMX para o ClickStack
docker exec <jmx-exporter-container> sh -c "timeout 2 bash -c 'cat < /dev/null > /dev/tcp/clickstack/4318' && echo 'Connected' || echo 'Failed'"

Próximas etapas

Configure alertas para métricas críticas (partições sub-replicadas, aumento do consumer lag, picos de latência das solicitações)
Crie dashboards adicionais para casos de uso específicos (throughput por tópico, monitoramento de grupos de consumidores)
Monitore vários brokers do Kafka adicionando instâncias adicionais do JMX Metric Gatherer com atributos de recurso kafka.broker.id exclusivos

Em produção

Este guia envia métricas diretamente do JMX Metric Gatherer para o endpoint OTLP do ClickStack, o que funciona bem para testes e implantações pequenas.

Para ambientes de produção, implante seu próprio OpenTelemetry Collector como agente para receber métricas do JMX Exporter e encaminhá-las ao ClickStack. Isso oferece processamento em lote, resiliência e gerenciamento centralizado da configuração.

Consulte Ingestão com OpenTelemetry para ver padrões de implantação em produção e exemplos de configuração do coletor.