Monedula
monedula-metrics-reporter docs menu

Filter metrics with an allow-list

Limit the Kafka metrics the reporter exports with allowed.metrics regex patterns in server.properties, matched against Kafka's own metric names.

How-to guides 4 of 6

3 min read

Updated 10 October 2026

Markdown

On this page

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.
  • 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:

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 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), 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:

# 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.