---
title: "Filter metrics with an allow-list"
description: "Limit the Kafka metrics the reporter exports with allowed.metrics regex patterns in server.properties, matched against Kafka's own metric names."
url: https://monedula.dev/flock/docs/metrics-reporter/how-to/filter-metrics/
---

`otlp.metric.reporter.allowed.metrics` limits the Kafka metrics the reporter exports, by default all of them, to those whose names match at least one of a list of regular expressions. The reporter reads the allow-list when the broker starts and applies it as Kafka registers each metric.

## Before you start

- The reporter installed on your brokers. See [Install the reporter on brokers](/flock/docs/metrics-reporter/how-to/install-on-brokers/).
- A window to restart the brokers: in 0.10.0, a new allow-list takes effect only after a restart.

## Steps

### 1. Find the names to match

The patterns match Kafka's own metric names, not the Prometheus names:

- **Kafka SPI metrics** match as `{group}.{name}`. The broker metric that Prometheus shows as `kafka_server_socket_server_metrics_connection_count` matches as `socket-server-metrics.connection-count`.
- **Yammer metrics** match as `{group}.{type}.{name}`. The broker metric `kafka_server_replicamanager_underreplicatedpartitions` matches as `kafka.server.ReplicaManager.UnderReplicatedPartitions`.

Each pattern is a Java regular expression that must match the whole name, and matching is case-sensitive. `socket-server-metrics\..*` admits every metric of the `socket-server-metrics` group; `kafka\.server\..*` admits every Yammer metric of the `kafka.server` group.

The allow-list covers Kafka SPI and Yammer metrics only. JVM metrics have their own switch, `otlp.metric.reporter.jvm.metrics.enabled`, the reporter's self-monitoring metrics are always exported, and KIP-714 client metrics follow the client-metrics subscription.

### 2. Set the allow-list in server.properties

Separate patterns with commas:

```properties
otlp.metric.reporter.allowed.metrics=socket-server-metrics\\..*,kafka\\.server\\..*
```

In a `.properties` file, a backslash starts an escape sequence, so write each backslash of a regular expression twice: Java's [Properties](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Properties.html#load(java.io.Reader)) loader drops a single backslash in front of an ordinary character.

### 3. Restart the broker

Restart each broker to apply the allow-list; metrics that do not match are never exported.

If a pattern is not a valid regular expression, the broker still starts, but the reporter logs `OtlpMetricReporter failed to initialize, running as no-op` and exports nothing until you fix the pattern and restart.

## Check it worked

One export interval after the restart, only the Kafka metrics that match the allow-list reach the collector. The reporter's self-monitoring and JVM metrics keep arriving.

## In builds from main: change the allow-list at runtime

Builds from the main branch, not yet released, change this behavior: the reporter keeps every metric Kafka announces and applies the allow-list when it exports, off Kafka's callback path, and the allow-list can change on running brokers through Kafka's dynamic broker configuration ([KIP-226](https://cwiki.apache.org/confluence/display/KAFKA/KIP-226+-+Dynamic+Broker+Configuration)), with `kafka-configs.sh` or the Admin client's `incrementalAlterConfigs`. This does not work with 0.10.0. On the command line, single quotes keep the backslashes as they are, and square brackets keep the comma-separated patterns in one value:

```bash
# Widen the allow-list on every broker, no restart (the brackets group the patterns):
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default \
  --alter --add-config 'otlp.metric.reporter.allowed.metrics=[socket-server-metrics\..*,kafka\.network\..*]'

# Inspect the current dynamic config:
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --describe

# Revert to the value in server.properties (or the default):
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default \
  --alter --delete-config otlp.metric.reporter.allowed.metrics
```

- `kafka-configs.sh` splits `--add-config` at every comma outside square brackets, so without the brackets it reads the second pattern as a separate, malformed setting and rejects the command. It also removes every square bracket inside a value, so a pattern that contains brackets, such as the character class `[0-9]`, has to go in a properties file passed with `--add-config-file` instead. In that file, write each backslash twice, as in `server.properties`.
- `--entity-default` changes every broker; `--entity-name <broker-id>` changes one broker.
- The broker validates the new value before applying it. An invalid pattern fails the `--alter` command and never reaches the running reporter, which keeps the previous allow-list.
- A new allow-list applies from the next export, and because filtering happens at export time, widening it brings back metrics that Kafka registers only once, at startup.
- The value persists in cluster metadata across restarts and takes precedence over `server.properties` until you remove it with `--delete-config`.
- `--describe` does not show the value. The broker does not know these keys, so it treats them as sensitive and redacts them: you can see that the key is overridden, with the source `DYNAMIC_BROKER_CONFIG`, but not what it is set to.
- After a change, the broker log has a line that starts with `OtlpMetricReporter reconfigured`. A reporter in no-op mode logs `dynamic reconfiguration ignored; restart required` instead.

## Related

- [Configuration keys](/flock/docs/metrics-reporter/reference/configuration/#otlp-metric-reporter-allowed-metrics) describes `allowed.metrics`.
- [Metric names and labels](/flock/docs/metrics-reporter/concepts/metric-names-and-labels/) explains how Kafka names become Prometheus names.
- [How it works](/flock/docs/metrics-reporter/concepts/how-it-works/) shows where the allow-list sits between Kafka and the collector.