Monitor Kafka with OpenTelemetry

Osuite monitors Apache Kafka through the OpenTelemetry Collector’s kafka_metrics receiver, which queries broker, topic, and consumer-group metadata and exports it over OTLP. Consumer-group lag arrives with the same resource attributes as your services, so a backed-up consumer in APM lines up with the partitions it is falling behind on.

Note

The receiver’s type id is kafka_metrics. It ships in the Collector contrib distribution — use otelcol-contrib (or any build that includes it), not the core otelcol binary.

Setup

Prerequisites

• Reachable Kafka brokers (the receiver connects as a client; no broker-side agent is required).
• If the cluster enforces SASL or TLS, credentials the receiver can use to connect and to describe consumer groups.

Export any credentials to the Collector’s environment if authentication is enabled:

export KAFKA_PASSWORD='a-strong-password'

Configure the Collector

1. Add the kafka_metrics receiver, the otlp/osuite exporter, and a metrics pipeline. Pick the tab that matches where your Collector runs — only the brokers list changes.

   Bare host

   receivers:
     kafka_metrics:  # receiver type is kafka_metrics, not kafkametrics
       brokers:
         - localhost:9092
       protocol_version: 3.0.0
       scrapers:
         - brokers
         - topics
         - consumers
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [kafka_metrics]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Docker

   receivers:
     kafka_metrics:  # receiver type is kafka_metrics, not kafkametrics
       brokers:
         - kafka:9092
       protocol_version: 3.0.0
       scrapers:
         - brokers
         - topics
         - consumers
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [kafka_metrics]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Kubernetes

   receivers:
     kafka_metrics:  # receiver type is kafka_metrics, not kafkametrics
       brokers:
         - kafka.default.svc.cluster.local:9092
       protocol_version: 3.0.0
       scrapers:
         - brokers
         - topics
         - consumers
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [kafka_metrics]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

2. Start the Collector. On Docker and Kubernetes, the Collector and the brokers must share a network so the broker addresses resolve.

Tip

For a SASL or TLS cluster, add an auth block to the receiver (auth.sasl with username, password, mechanism, or auth.tls). Set protocol_version to match your broker version.

Validate

What you should see

Metrics named kafka.* appear in Dashboards → Explore metrics within a minute, including kafka.consumer_group.lag per consumer group.

Data collected

Metric	Description	Unit
kafka.brokers	Brokers in the cluster	{brokers}
kafka.topic.partitions	Partitions in a topic	{partitions}
kafka.partition.current_offset	Current offset of a partition	1
kafka.partition.oldest_offset	Oldest offset of a partition	1
kafka.partition.replicas	Replicas for a partition	{replicas}
kafka.partition.replicas_in_sync	In-sync replicas of a partition	{replicas}
kafka.consumer_group.members	Members in a consumer group	{members}
kafka.consumer_group.offset	Group offset at a partition	1
kafka.consumer_group.lag	Approximate lag at a partition	1
kafka.consumer_group.lag_sum	Approximate lag summed across partitions	1

The brokers, topics, and consumers scrapers each control a subset of these metrics — enable only the ones you need.

Dashboards and alerts

Once metrics arrive, build a Kafka dashboard in the dashboard builder from the series above. Alerts in Osuite are PromQL-based — see Alerts. Useful starting conditions: rising kafka.consumer_group.lag_sum, under-replicated partitions (kafka.partition.replicas_in_sync below kafka.partition.replicas), and broker-count changes.

Troubleshooting

• No consumer-group metrics — confirm the consumers scraper is listed and that the receiver’s client is allowed to describe consumer groups if ACLs are enabled.
• Connection or version errors — set protocol_version to match your broker, and confirm SASL/TLS auth settings when the cluster requires them.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.