---
title: "As métricas do Kafka precisam mesmo ser tão difíceis?"
date: 2026-05-26T00:00:00.000Z
author: "grzegorz"
excerpt: "Por que as métricas do Kafka são dolorosas, por que dashboards baseados em JMX muitas vezes não mostram dados e como exportar métricas do Kafka nativamente via OTLP."
---
Hoje em dia, o [Apache Kafka](https://kafka.apache.org/) é um dos softwares mais utilizados em TI. Ele está em todo lugar, é um padrão de fato para event streaming e tem ampla adoção em grandes empresas. O projeto Apache Kafka afirma que o Kafka é usado por milhares de organizações e tem a confiança de mais de 80% das empresas da Fortune 100.

Em muitas organizações, o Kafka é a espinha dorsal de seus sistemas, e o ecossistema Kafka cresce constantemente.

Mas operar um cluster Kafka confiável pode ser desafiador: ele tem muitas configurações tanto no nível de broker quanto no de topic, é distribuído e, obviamente, queremos que ele seja altamente disponível.

O monitoramento é crucial: sem uma configuração adequada para coletar métricas, construir dashboards e, por fim, definir alertas, a equipe de operações fica cega.

Neste artigo, vou descrever os problemas conhecidos das métricas do Kafka e propor uma solução que, espero, resolva a maioria deles — ou talvez até todos.

> Você já importou um dashboard de Kafka no Grafana e ele não mostra nenhum dado? Você vai encontrar a resposta mais abaixo.

## Afinal, o que é o Kafka?

Aposto que, se você está lendo este artigo, sabe perfeitamente o que é o Kafka e qual é o seu propósito. Mas aqui vai uma recapitulação rápida:

O Apache Kafka é uma plataforma distribuída de event streaming. A forma mais simples de pensar nele: o Kafka é um log durável, do tipo append-only, que permite que muitas aplicações gravem eventos nele — os producers — e que muitas outras leiam esses eventos de volta — os consumers — em tempo real, com altíssima vazão.

Os eventos vivem em topics, que são divididos em partitions e replicados entre múltiplos brokers, os servidores que compõem um cluster Kafka. Isso lhe dá escalabilidade horizontal e tolerância a falhas: se um broker morre, outra réplica assume e os consumers continuam lendo sem perder nada.

Hoje, o Kafka está no coração de muitos sistemas de missão crítica: pipelines de pagamento, detecção de fraudes, comunicação entre microsserviços, change data capture de bancos de dados, agregação de logs, telemetria de IoT. Quando funciona bem, ninguém percebe. Quando não funciona, é um desastre.

## O sistema de métricas dentro do Kafka — a raiz do problema

Você sabia que os brokers do Kafka expõem métricas através de dois sistemas de métricas diferentes? Eu não sabia.

As métricas do Kafka são tratadas por duas bibliotecas de métricas separadas rodando na mesma JVM.

A mais antiga é o Yammer Metrics. Está no Kafka desde os primórdios, e muitas métricas fundamentais de broker — por exemplo `BytesInPerSec`, `MessagesInPerSec` e `UnderReplicatedPartitions` — ainda são tratadas por ele.

A segunda é o Kafka Metrics, `org.apache.kafka.common.metrics`, também conhecido como SPI — Service Provider Interface. Foi introduzido quando os clientes Java foram criados. Também é usado por ferramentas do ecossistema, como Kafka Streams e Kafka Connect.

Isso não é só curiosidade. A [documentação oficial de monitoramento do Apache Kafka](https://kafka.apache.org/documentation/#monitoring) diz que o Kafka usa o Yammer Metrics para métricas de servidor, enquanto os clientes Java usam o Kafka Metrics. Ambos expõem métricas via JMX e podem ser configurados com stats reporters plugáveis.

Esses dois sistemas existem por razões históricas. Em algum momento, todas as novas métricas passaram a ser criadas como métricas SPI, mas não havia um plano para migrar as métricas Yammer para o SPI.

Aqui estão as principais diferenças:

| Área | MBeans do Yammer Metrics | MBeans do Kafka Metrics |
|---|---|---|
| Uso principal no Kafka | Métricas clássicas de broker/servidor/controller | Clientes Java e módulos de broker/controller mais novos/comuns |
| Configuração do reporter | `kafka.metrics.reporters` | `metric.reporters` |
| Interface do reporter | `kafka.metrics.KafkaMetricsReporter` | `org.apache.kafka.common.metrics.MetricsReporter` |
| Exposição JMX padrão | Reporter JMX do Yammer | `org.apache.kafka.common.metrics.JmxReporter` |
| Formato do MBean | O nome da métrica costuma fazer parte do `ObjectName`, como `name=...` | O `ObjectName` geralmente é domínio + tipo + tags; os nomes das métricas costumam ser atributos |
| Atributos | Atributos genéricos do Yammer como `Value`, `Count`, `MeanRate`, `OneMinuteRate`, percentis | Nomes de métricas do Kafka como atributos, como `byte-rate`, `throttle-time`, `connection-count`, `*-rate`, `*-total` |
| Estilo de exemplo | `kafka.server:type=BrokerTopicMetrics,name=BytesInPerSec,topic=my-topic` | `kafka.server:type=Produce,user=alice,client-id=app1` com atributos como `byte-rate`, `throttle-time` |

## Configurando métricas do Kafka — do jeito antigo

A forma tradicional de monitorar o Kafka é exportar métricas do JMX com o [Prometheus JMX Exporter](https://prometheus.github.io/jmx_exporter/). É uma biblioteca que roda como um Java agent e é configurada com um arquivo de regras e um número de porta.

A porta é usada como endpoint do Prometheus, com `/metrics` acrescentado.

E o arquivo de regras? É um arquivo YAML enorme, com toneladas de expressões regulares. Normalmente, ninguém entende os detalhes por completo e simplesmente o usa, torcendo para que quem o escreveu soubesse o que estava fazendo.

Então você precisa subir o JMX Exporter para todos os brokers, possivelmente criar ou editar o arquivo de configuração com as regras — boa sorte com isso — e reiniciar os brokers. Se tudo correr bem, você pode fazer um curl no endpoint de métricas e ver as métricas. Ótimo!

Em seguida, você coleta essas métricas no [Prometheus](https://prometheus.io/), baixa alguns dashboards de Kafka no [Grafana](https://grafana.com/) e… na maioria dos casos, você vê "No Data". Por quê? Porque não existe um padrão único para as regras, então a única opção é editar o dashboard ou tentar encontrar outro.

Mas tem mais: cada um desses sistemas de métricas pode ser configurado com uma classe customizada, ou plugin. Olhe a tabela acima — sim, são duas configurações. Uma com o prefixo `kafka`, a outra sem. Uma com `metric` no singular, a outra com `metrics` no plural.

Pois é.

## Ei, estamos em 2026, o Kafka pode usar OpenTelemetry?

A resposta curta é: não diretamente. Mas há algumas formas de ensinar o protocolo [OpenTelemetry](https://opentelemetry.io/) ao Kafka.

Existem várias maneiras de fazer isso:

- JMX Exporter mais o Prometheus receiver no [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) — os mesmos problemas de mapeamento JMX descritos acima.
- [OpenTelemetry Collector JMX receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/jmxreceiver) — ainda baseado em JMX, exige expor o JMX, e o componente agora está marcado como deprecated, com a recomendação de usar um programa Java JMX Gatherer standalone no lugar.
- [OpenTelemetry Java agent](https://opentelemetry.io/docs/zero-code/java/agent/) — uma boa opção. Ele consegue coletar métricas de broker do Kafka através do módulo JMX Metric Insight, e a demo do OpenTelemetry usa essa abordagem para o Kafka. Mas se você quiser um conjunto customizado de métricas JMX, ainda acaba com mais um arquivo de mapeamento de métricas.

## A solução

E se tivéssemos algo que resolvesse todos os problemas descritos acima?

Como mencionado, as configurações `metric.reporters` e `kafka.metrics.reporters` são apenas nomes de classe. As classes precisam implementar as interfaces `org.apache.kafka.common.metrics.MetricsReporter` e `kafka.metrics.KafkaMetricsReporter`, respectivamente.

Então tivemos a ideia: uma biblioteca com as seguintes características.

### OTLP nativo, sem salto via JMX

A maioria das stacks de observabilidade do Kafka acopla o `jmx_exporter`, ou algo similar, como um agent da JVM, depois coleta MBeans por um endpoint HTTP e então envia para um collector.

Este plugin vive dentro do processo do Kafka e fala [OTLP](https://opentelemetry.io/docs/specs/otlp/) diretamente com o collector — um processo a menos, uma superfície de configuração a menos e nenhum YAML de regras JMX para manter.

### Um plugin, ambos os registros do Kafka

Os brokers do Kafka expõem métricas através de dois sistemas paralelos: o SPI do Kafka, configurado com `metric.reporters`, e o registro legado do Yammer/Coda Hale.

Vários sinais internos do broker — `UnderReplicatedPartitions`, `OfflinePartitionsCount`, `ActiveControllerCount` e o `BrokerTopicMetrics` por topic — só se registram no Yammer.

O `OtlpMetricReporter` conecta-se a ambos com uma única configuração. O mesmo JAR roda sem alterações nos clientes, onde o lado Yammer se desativa automaticamente.

### À prova de falhas por design — o Kafka nunca é bloqueado

Callbacks de métricas como `metricChange` e `metricRemoval` só tocam um `ConcurrentHashMap` em memória. Todo o I/O acontece em uma thread daemon de agendamento.

Se o collector estiver inacessível, a chamada de exportação dá timeout, o lote é descartado e o próximo tick começa do zero. Sem fila de retentativas, sem memória ilimitada, sem impacto na latência de produce/fetch do Kafka.

### O contexto do broker vira labels de primeira classe no Prometheus

O Kafka invoca `MetricsReporter.contextChange(MetricsContext)` com o cluster id, o node/broker id e a versão do Kafka.

O plugin captura esses valores e os anexa como resource attributes do OTLP. Eles aparecem como labels — `kafka_cluster_id`, `kafka_node_id` ou `kafka_broker_id` — em cada série, de modo que `by(kafka_cluster_id, kafka_node_id)` funciona no PromQL sem nenhuma configuração extra.

## Senhoras e senhores, conheçam o `monedula-metrics-reporter`

O [`monedula-metrics-reporter`](https://github.com/monedula-dev/monedula-metrics-reporter) é uma biblioteca open source que atende a esses requisitos — e mais.

Ele exporta métricas do Kafka diretamente via OTLP usando gRPC ou HTTP, suporta Kafka 3.x e 4.x no Java 17+ e também pode emitir métricas de runtime da JVM no mesmo pipeline.

Ele também inclui recursos práticos de produção, como:

- allow-listing de métricas,
- resource attributes customizados,
- configuração de TLS e mTLS,
- compressão,
- métricas de automonitoramento do reporter,
- e suporte tanto a brokers quanto a clientes.

O reporter emite suas próprias métricas de saúde também, por exemplo:

- `monedula_reporter_export_success_total`,
- `monedula_reporter_export_failure_total`,
- `monedula_reporter_export_duration_ms`.

Assim, se o pipeline do collector quebrar, você não recebe apenas silêncio. Você recebe sinais de que o próprio reporter está falhando ao exportar.

O projeto também vem com um quickstart fácil de usar que demonstra o fluxo completo com Kafka, o OpenTelemetry Collector, Prometheus e Grafana. E porque os dashboards fazem parte do problema, ele inclui um conjunto curado de dashboards do Grafana prontos para uso que correspondem às métricas produzidas pelo plugin.

Você pode encontrá-lo no GitHub, compilá-lo localmente e testá-lo com o quickstart. Artefatos pré-compilados chegarão em breve.

Se encontrar um bug ou tiver uma sugestão de melhoria, fique à vontade para criar uma issue no GitHub.

## Resumo

O monitoramento do Kafka é mais difícil do que deveria porque o Kafka expõe métricas através de dois sistemas de métricas diferentes, a maioria das configurações de produção ainda depende de JMX, e cada mapeamento de JMX para Prometheus cria mais uma camada de compatibilidade entre o broker, o Prometheus e os dashboards do Grafana.

O `monedula-metrics-reporter` adota uma abordagem diferente: ele roda como um metrics reporter do Kafka, exporta métricas nativamente via OTLP, lida com ambos os registros de métricas do Kafka e vem com dashboards que correspondem às métricas emitidas.

Então, as métricas do Kafka precisam mesmo ser tão difíceis?

Espero que não mais.