Status

Current state: Under DiscusssionAdopted

Discussion thread: here

JIRA:

...

public interface MetricsReporter extends Reconfigurable, AutoCloseable {
    [...]
    
    /**
     * CallbackProvides method providing context metadata for the
     * service or library exposing metrics
     *
     * @param metricsContext the metric context
     */
    @InterfaceStability.Evolving
    default void contextChange(MetricsContext metricsContext) {}
}

...

/**
 * MetricsContext encapsulates additional metadata about metrics exposed via a
 * {@link org.apache.kafka.common.metrics.MetricsReporter}
 * 
 * The metadata map provides following information:
 * - a <code>_namespace</node> field indicating the component exposing metrics
 *   e.g. kafka.server, kafka.consumer
 *   {@link JmxReporter} uses this as prefix for mbean names
 *
 * - for clients and streams libraries: any freeform fields passed in via
 *   client properties in the form of `metrics.context.<key>=<value>
 *
 * - for kafka brokers: kafka.broker.id, kafka.cluster.id
 * - for connect workers: connect.kafka.cluster.id, connect.group.id
 */
@InterfaceStability.Evolving
public interface MetricsContext {

    /* predefined fields */
    String NAMESPACE = "_namespace"; // metrics namespace, formerly jmx prefix
    
    /**
     * Returns metadata fields
     */
    public Map<String, String> metadatacontextLabels();
}

Connect, Streams and Client configuration changes

...

Kafka brokers will pass in fully resolved fields kafka.broker.id and kafka.cluster.id to the metric context.

In addition, similar to client, any metrics.context.<field>=<value> entries passed in via broker configuration will also be added to the metrics context.

Connect Workers

Connect workers will pass in the following fields to the metric context:

• connect.kafka.cluster.id to indicate the backing Kafka cluster

...

• connect.group.id to indicate the group id used for worker coordination (only in distributed mode)

Connect will , and also propagate this information to the its clientsthese fields to embedded clients via the metrics.context. client properties.

Compatibility, Deprecation, and Migration Plan

contextChange(MetricsContext metricsContext) will be added as a default method to MetricsReporter to support backward compatibility with existing implementations. No changes are required for existing metric reporters since we are not changing any other behavior.

metrics.context. configuration properties are optional, and as such would not impact any upgrades.

Since the properties are namespaced, they are unlikely to conflict with configs from other extensions / plugins. 

Rejected Alternatives

• Add additional metadata to the tags defined in MetricsConfig
MetricsConfig tags are tightly coupled to MetricNameTemplate objects, and require metric names to provide placeholders for all the tags, which make it difficult to add new tags without changing the metric names.

• Add additional metadata to the ClusterResource class
  Metrics reporters could already get some Kafka cluster metadata information (e.g, Kafka cluster id) by implementing the ClusterResourceListener interface introduced in KIP-78. We considered adding additional context metadata to this class, but ultimately rejected that idea. ClusterResource is tightly coupled to a Kafka cluster. Adding metadata of other components to ClusterResource would be ill-suited and cause for confusion. The ClusterResourceListener.onUpdate(ClusterResource) method also has well-defined semantics for broker and client metadata updates, which would make implementing MetricsReporters more difficult.

• Pass in additional context via the Configurable/Reconfigurable interface
  As noted, some context metadata such as broker.id is currently available via configuration, but relies on workarounds to manipulate the config passed to metrics reporters when they are defined dynamically. While it might be possible to use reconfigure(...) instead to pass context values when they are known, this would require metric reporters to know all possible context keys in advance to return in reconfigurableConfigs. As a result, one would have to make code changes to reporter plugins with every release just to support new fields added to the context. That would be akin to asking metrics reporter to know what metric tags are exposed in advance, which seemed convoluted.