---
title: "Install the reporter on brokers"
description: "Download the monedula-metrics-reporter JAR, put it on the broker classpath and point it at your OpenTelemetry Collector in server.properties."
url: https://monedula.dev/flock/docs/metrics-reporter/how-to/install-on-brokers/
---
## Before you start

- Brokers on Java 17 or newer and Apache Kafka 3.7.0 to 4.3.0; see [Compatibility](/flock/docs/metrics-reporter/concepts/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:

<Tabs group="metrics-jar-source" labels={['Maven Central', 'GitHub Release']} label="Download from">

```bash
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
```

```bash
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
```

</Tabs>

- **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](https://github.com/orgs/monedula-dev/packages?repo_name=monedula-metrics-reporter) serves the same coordinates but needs a personal access token with `read:packages`.

Replace `0.10.0` with the [latest release](https://github.com/monedula-dev/monedula-metrics-reporter/releases/latest) 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](https://github.com/sigstore/cosign):

```bash
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:

```bash
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`:

```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](/flock/docs/metrics-reporter/reference/configuration/) reference lists all 18. If the collector needs TLS or an authentication header, see [Secure the collector connection](/flock/docs/metrics-reporter/how-to/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](/flock/docs/metrics-reporter/concepts/metric-names-and-labels/#labels-on-every-series):

```yaml
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](/flock/docs/metrics-reporter/concepts/fail-safe-design/)).

One interval after startup, the first metrics reach the collector. In Prometheus, [`monedula_reporter_export_success_total`](/flock/docs/metrics-reporter/reference/self-monitoring-metrics/) grows with every export, and broker series such as `kafka_server_replicamanager_underreplicatedpartitions` carry the `kafka_cluster_id` and `kafka_node_id` labels.

## Related

- [Filter metrics with an allow-list](/flock/docs/metrics-reporter/how-to/filter-metrics/) limits what the reporter exports.
- [Collect Kafka client metrics with KIP-714](/flock/docs/metrics-reporter/how-to/collect-client-telemetry/) adds producer and consumer metrics without touching the clients.
- Runnable version: [quickstart](https://github.com/monedula-dev/monedula-metrics-reporter/tree/main/quickstart), a three-broker cluster with the reporter, a collector, Prometheus and Grafana in Docker Compose.