Monedula
monedula-metrics-reporter docs menu

Install the reporter on brokers

Download the monedula-metrics-reporter JAR, put it on the broker classpath and point it at your OpenTelemetry Collector in server.properties.

How-to guides 1 of 6

3 min read

Updated 10 October 2026

Markdown

On this page

Before you start

  • Brokers on Java 17 or newer and Apache Kafka 3.7.0 to 4.3.0; see Compatibility.
  • An OpenTelemetry Collector with an OTLP receiver that the brokers can reach: port 4317 for gRPC or 4318 for HTTP by default.
  • Access to each broker’s host and Kafka installation, and a window to restart the brokers.

Steps

1. Download the JAR

Released versions are on Maven Central, on each GitHub Release and on GitHub Packages. Download the JAR into the current directory from either of the first two:

VERSION=0.10.0
curl -L -o monedula-metrics-reporter-${VERSION}.jar \
  https://repo1.maven.org/maven2/dev/monedula/monedula-metrics-reporter/${VERSION}/monedula-metrics-reporter-${VERSION}.jar
VERSION=0.10.0
curl -L -o monedula-metrics-reporter-${VERSION}.jar \
  https://github.com/monedula-dev/monedula-metrics-reporter/releases/download/v${VERSION}/monedula-metrics-reporter-${VERSION}.jar
  • Maven Central needs no authentication.
  • GitHub Release serves the same JAR, together with a CycloneDX SBOM, bom.json, and a Sigstore signature (.sig) and certificate (.pem) for each file.
  • Tools that resolve JARs for you, such as Coursier or mvn dependency:get, use the coordinates dev.monedula:monedula-metrics-reporter, whose main artifact is the relocated (shadow) JAR. They store it in their own cache, so copy it from there in step 2. GitHub Packages serves the same coordinates but needs a personal access token with read:packages.

Replace 0.10.0 with the latest release if a newer one exists.

To check that the JAR was built by our release workflow and not changed since, fetch its signature and certificate from the release and verify them with cosign:

VERSION=0.10.0
BASE=https://github.com/monedula-dev/monedula-metrics-reporter/releases/download/v${VERSION}
curl -LO ${BASE}/monedula-metrics-reporter-${VERSION}.jar.sig
curl -LO ${BASE}/monedula-metrics-reporter-${VERSION}.jar.pem

cosign verify-blob \
  --signature monedula-metrics-reporter-${VERSION}.jar.sig \
  --certificate monedula-metrics-reporter-${VERSION}.jar.pem \
  --certificate-identity-regexp 'https://github.com/monedula-dev/monedula-metrics-reporter/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  monedula-metrics-reporter-${VERSION}.jar

A successful verification prints Verified OK. The same command, with the file names changed, verifies the sources and javadoc JARs and bom.json.

2. Put the JAR on the classpath

On every broker, copy the JAR into Kafka’s libs/ directory, or anywhere else on Kafka’s classpath:

cp monedula-metrics-reporter-0.10.0.jar $KAFKA_HOME/libs/

3. Enable the reporter in server.properties

Add the reporter and your collector’s endpoint to each broker’s server.properties:

# One reporter, both metric streams. On brokers it covers Kafka SPI *and* Yammer
# registries; on clients only the SPI registry is present and the Yammer side
# auto-disables.
metric.reporters=dev.monedula.metricsreporter.OtlpMetricReporter

otlp.metric.reporter.endpoint=http://otel-collector:4317
otlp.metric.reporter.transport=grpc

Replace otel-collector with your collector’s host. To send over HTTP instead, set otlp.metric.reporter.transport=http and point the endpoint at the collector’s HTTP port, such as http://collector:4318. A bare collector root like that becomes http://collector:4318/v1/metrics; an endpoint with its own path is used as given.

Other keys you may want now:

  • otlp.metric.reporter.interval.ms: how often the reporter exports, 30000 milliseconds by default.
  • otlp.metric.reporter.timeout.ms: how long one export may take, 5000 milliseconds by default. It must be less than the interval.
  • otlp.metric.reporter.resource.attributes: extra labels for every series, as key=value,key=value.

The configuration keys reference lists all 18. If the collector needs TLS or an authentication header, see Secure the collector connection.

4. Restart the broker

The reporter reads its settings when the broker starts, so restart each broker to load the JAR and the new settings.

5. Turn resource attributes into Prometheus labels

If the collector exports to Prometheus with its prometheus exporter, enable resource_to_telemetry_conversion, as the quickstart’s otel-collector-config.yaml does, so that the broker’s identity reaches Prometheus as labels on every series:

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    resource_to_telemetry_conversion:
      enabled: true

Check it worked

The broker log shows the reporter starting:

  • A line that starts with OtlpMetricReporter started and names the endpoint, the transport, the interval and yammer=true.
  • OtlpMetricReporter attached to Kafka Yammer registry, for the broker-internal metrics.
  • OtlpMetricReporter JVM runtime metrics enabled and OtlpMetricReporter client telemetry (KIP-714) receiver enabled, unless you turned those off.

If the log shows OtlpMetricReporter failed to initialize, running as no-op instead, a setting is invalid: fix it and restart. The broker keeps serving traffic meanwhile (Fail-safe by design).

One interval after startup, the first metrics reach the collector. In Prometheus, monedula_reporter_export_success_total grows with every export, and broker series such as kafka_server_replicamanager_underreplicatedpartitions carry the kafka_cluster_id and kafka_node_id labels.