...
Code Block | ||||
---|---|---|---|---|
| ||||
package org.apache.kafka.common.metrics; public interface Monitorable { /** * Set the PluginMetrics instance from the clientcomponent that instantiates the plugin. */ Plugins can register voidand withPluginMetrics(PluginMetricsunregister metrics); } |
The PluginMetrics interface has methods to add and remove metrics and sensors. Plugins will only be able to remove metrics and sensors they created. Metrics created via this class will have their group set to "plugins" and include tags that uniquely identify the plugin.
Code Block | ||
---|---|---|
| ||
public interface PluginMetrics extends Closeable { /** * Create a {@link MetricName} with the given name, description and tags. The group will be set to "plugins" using the given PluginMetrics * at any point in their lifecycle prior to their close method being called. * * Plugin must call the close() method on this PluginMetrics instance in their close() * Tagsmethod to uniquelyclear identifyall themetrics plugins are automatically added to the provided tagsthey registered. */ void withPluginMetrics(PluginMetrics metrics); } |
The PluginMetrics interface has methods to add and remove metrics and sensors. Plugins will only be able to remove metrics and sensors they created. Metrics created via this class will have their group set to "plugins" and include tags that uniquely identify the plugin.
Code Block | ||
---|---|---|
| ||
/** * Implementations are thread safe so plugins may use the PluginMetrics instance from multiple threads */ public interface PluginMetrics extends Closeable {* @param name The name of the metric * @param description A human-readable description to include in the metric * @param tags additional key/value attributes of the metric */ MetricName metricName(String name, String description, Map<String, String> tags); /** * AddCreate a metric{@link toMetricName} monitorwith anthe objectgiven thatname, implementsdescription {@linkand MetricValueProvider}tags. ThisThe metricgroup won'twill be associatedset withto any"plugins" * sensor. This is a way to expose existing values as metrics. Tags to uniquely identify the plugins are automatically added to the provided tags * * @param metricNamename The name of the metric * @param metricValueProviderdescription TheA metrichuman-readable valuedescription providerto associatedinclude within thisthe metric * @throws@param IllegalArgumentExceptiontags if a metric with same name already exists. additional key/value attributes of the metric */ voidMetricName addMetric(MetricName metricName, MetricValueProvider<?> metricValueProvidermetricName(String name, String description, Map<String, String> tags); /** * RemoveAdd a metric ifto itmonitor exists. an object that implements * * @param metricName The name of the metric{@link MetricValueProvider}. This metric won't be associated with any * @throwssensor. IllegalArgumentExceptionThis ifis thea pluginway hasto notexpose alreadyexisting createdvalues a metric with this nameas metrics. */ void* removeMetric(MetricName@param metricName); /** The name of the metric * Create@param ametricValueProvider sensorThe withmetric thevalue givenprovider uniqueassociated name.with Thethis namemetric must only be unique for* the@throws plugin,IllegalArgumentException soif differenta pluginsmetric canwith usesame thename samealready namesexists. */ void * @param name The sensor nameaddMetric(MetricName metricName, MetricValueProvider<?> metricValueProvider); * @return The sensor/** * Remove a metric if it exists. * * @param metricName The name of the metric * @throws IllegalArgumentException if the plugin has not already created a sensormetric with samethis name already exists for this plugin */ Sensor sensor(String name); /** * Remove a sensor (if it exists) and its associated metrics. * * @param name The name of the sensor to be removed * @throws IllegalArgumentException if the plugin has not already created a sensor with this name */ void removeSensor(String name); } |
The PluginMetrics interface implements Closeable. Calling the close() method removed all metrics and sensors created by this plugin. It will be the responsibility of the plugin that create metrics to call close() of their PluginMetrics instance to remove their metrics.
New methods will be added to AbstractConfig so new plugin instances implementing Monitorable can get a PluginMetrics instance.
*/
void removeMetric(MetricName metricName);
/**
* Create a sensor with the given unique name. The name must only be unique for the plugin, so different plugins can use the same names.
*
* @param name The sensor name
* @return The sensor
* @throws IllegalArgumentException if a sensor with same name already exists for this plugin
*/
Sensor sensor(String name);
/**
* Remove a sensor (if it exists) and its associated metrics.
*
* @param name The name of the sensor to be removed
* @throws IllegalArgumentException if the plugin has not already created a sensor with this name
*/
void removeSensor(String name);
} |
The PluginMetrics interface implements Closeable. Calling the close() method removed all metrics and sensors created by this plugin. It will be the responsibility of the plugin that creates metrics to call close() of the PluginMetrics instance they were given to remove their metrics.
New methods will be added to AbstractConfig so new plugin instances implementing Monitorable can get a PluginMetrics instance.
Code Block | ||||
---|---|---|---|---|
| ||||
/**
* Get a configured instance of the give class specified by the given configuration key. If the object implements
* Configurable configure it using the configuration. If the object implements Monitorable, set the appropriate PluginMetrics for that instance.
*
* @param key The configuration key for the class.
* @param t The interface the class should implement.
* @param metrics The metrics registry to use to build the PluginMetrics instance if the class implements Monitorable.
* @return A configured instance of the class.
*/
public <T> T getConfiguredInstance(String key, Class<T> t, Metrics metrics);
| ||||
Code Block | ||||
| ||||
/** * Get a configured instance of the give class specified by the given configuration key. If the object implements * Configurable configure it using the configuration. If the object implements Monitorable, set the appropriate PluginMetrics for that instance. * * @param key The configuration key for the class. * @param t The interface the class should implement. * @param configOverrides override origin configs. * @param metrics The metrics registry to use to build the PluginMetrics instance if the class implements Monitorable. * @return A configured instance of the class. */ public <T> T getConfiguredInstance(String key, Class<T> t, Map<String, Object> configOverrides, Metrics metrics); /** * Get a configured instance of the give class specified by the given configuration key. If the object implements * Configurable configure it using the configuration. If the object implements Monitorable, set the appropriate PluginMetrics for that instance. * list of configured instances of the given class specified by the given configuration key. The configuration * may specify either null or an empty string to indicate no configured instances. If an instance implements Monitorable, * set the appropriate PluginMetrics for that instance. In both cases, this method returns an empty list to indicate no configured instances. * @param key The configuration key for the class. * @param t The interface the class should implement. * @param configOverrides overrideConfiguration overrides originto configsuse. * @param metrics The metrics registry to use to build the PluginMetrics instanceinstances iffor theeach class that implements Monitorable. * @return AThe configured instancelist of theconfigured classinstances. */ public <T> TList<T> getConfiguredInstancegetConfiguredInstances(String key, Class<T> t, Map<String, Object> configOverrides, Metrics metrics); /** * Get a list of configured instances of the given class specified by the given configuration key. The configuration * may specify either null or an empty string to indicate no configured instances. If an instance implements Monitorable, * set the appropriate PluginMetrics for that instance. In both cases, this method returns an empty list to indicate no configured instances. * @param key The configuration key for the class. * @param t The interface the class should implement. * @param configOverrides Configuration overrides to use. classes. * @param metricsclassNames The metrics registry to uselist of class names of the instances to build the PluginMetrics instances for eachcreate. * @param t The interface the class thatshould implements Monitorableimplement. * @return@param TheconfigOverrides listConfiguration ofoverrides configuredto instancesuse. */ public <T> List<T> getConfiguredInstances(String key, Class<T> t, Map<String, Object> configOverrides, Metrics metrics); /** * Get a list of configured instances of the given class specified by the given configuration key. The configuration * may specify either null or an empty string to indicate no configured instances. If an instance implements Monitorable, * set the appropriate PluginMetrics for that instance. In both cases, this method returns an empty list to indicate no configured instances. * @param key The configuration key for the classes. * @param classNames The list of class names of the instances to create. * @param t The interface the class should implement. * @param configOverrides Configuration overrides to use. * @param metrics The metrics registry to use to build the PluginMetrics instances for each class that implements Monitorable. * @return The list of configured instances. */ public <T> List<T> getConfiguredInstances(String key, List<String> classNames, Class<T> t, Map<String, Object> configOverrides, Metrics metrics) |
The Converter interface will extend Closeable (like HeaderConverter already does), the logic of the Converter class stays untouched. The Connect runtime will be updated to call close() when the converter instances can be released.
Code Block | ||||
---|---|---|---|---|
| ||||
public interface Converter extends Closeable {
@Override
default void close() throws IOException {
// no-op
}
} |
Proposed Changes
When instantiating a class, if it implements Monitorable
, the withPluginMetrics()
method will be called. If the class is also Configurable
, withPluginMetrics()
will be always called after configure()
. Metrics registered by plugins will inherit the prefix/namespace from the current Metrics
instance, these are: kafka.producer, kafka.consumer, kafka.connect, kafka.streams and kafka.server. Tags will be added to metrics and sensors tags created via the PluginMetrics interface to unique identify each instance.
For all plugins apart from Connectors, Tasks, Converters, Transformations and Predicates, a tag containing the configuration name (config) will be added. For example, metrics registered by a custom Serializer named MySerializer configured via key.serializer will have the following name: kafka.producer:type=plugins,client-id=producer-1,config=key.serializer,class=MySerializer,
For Connectors and Converters, the name of the connector (connector) will be added as a tag. Tasks will add the connector name and the task id (task) added as tags. Transformations and Predicates will have the connector name, the task id and their alias (alias) added as tags. For example for a task: kafka.connect:type=plugins,class=MyTask,connector=my-sink,task=0
...
@param metrics The metrics registry to use to build the PluginMetrics instances for each class that implements Monitorable.
* @return The list of configured instances.
*/
public <T> List<T> getConfiguredInstances(String key, List<String> classNames, Class<T> t, Map<String, Object> configOverrides, Metrics metrics) |
The Converter interface will extend Closeable (like HeaderConverter already does), the logic of the Converter class stays untouched. The Connect runtime will be updated to call close() when the converter instances can be released.
Code Block | ||||
---|---|---|---|---|
| ||||
public interface Converter extends Closeable {
@Override
default void close() throws IOException {
// no-op
}
} |
Proposed Changes
When instantiating a class, if it implements Monitorable
, the withPluginMetrics()
method will be called. If the class is also Configurable
, withPluginMetrics()
will be always called after configure()
. Metrics registered by plugins will inherit the prefix/namespace from the current Metrics
instance, these are: kafka.producer, kafka.consumer, kafka.connect, kafka.streams and kafka.server. Tags will be added to metrics and sensors tags created via the PluginMetrics interface to unique identify each instance.
For all plugins apart from Connectors, Tasks, Converters, Transformations and Predicates, a tag containing the configuration name (config) will be added. For example, metrics registered by a custom Serializer named MySerializer configured via key.serializer will have the following name: kafka.producer:type=plugins,client-id=producer-1,config=key.serializer,class=MySerializer,
For Connectors and Converters, the name of the connector will be added as a tag (connector). Tasks will add the name of the connector (connector) and the task id (task) as tags. Transformations and Predicates will have the connector name, the task id and their alias (transformation/predicate) added as tags. For example:
- for a task: kafka.connect:type=plugins,connector=my-sink,task=0
- for a predicate: kafka.connect:type=plugins,connector=my-sink,task=0,predicate=my-predicate
For configurations that accept a list of classes, for example interceptor.classes, if the same class is provided multiple times, their metrics may collide. This is deemed highly unlikely to occur as there are no use cases where providing multiple times the same class is useful.
This proposal supersedes KIP-608 which only aimed at providing this functionality to Authorizer plugins. KIP-608 was adopted in 2020 but never implemented. This KIP proposes to alter the names of the metrics from KIP-608 to the following so all plugins use the same naming format:
Full Name | Type | Description |
---|---|---|
kafka.server:type=plugins,config=authorizer.class.name,class=MyAuthorizer,name=acls-total-count | Gauge | Total ACLs created in the broker |
kafka.server:type=plugins,config=authorizer.class.name,class=MyAuthorizer,name=authorization-request-rate-per-minute | Rate | Total number of authorization requests per minute |
kafka.server:type=plugins,config=authorizer.class.name,class=MyAuthorizer,name=authorization-allowed-rate-per-minute | Rate | Total number of authorization allowed per minute |
kafka.server:type=plugins,config=authorizer.class.name,class=MyAuthorizer,name=authorization-denied-rate-per-minute | Rate | Total number of authorization denied per minute |
Supported plugins
The goal is allow this feature to be used by all plugins that are Closeable, AutoCloseable or have a close() methods apart from MetricsReporter since instances are created before the Metrics instance. Also all Connect connector plugins will be supported. The javadoc of all supported plugins will be updated to mention they are able to implement the Monitorable interface to define their own metrics.
...
Class | Config | Reason |
---|---|---|
KafkaMetricsReporter | kafka.metrics.reporters | This interface is technically not part of the public API. Since MetricsReporter will not support it, it makes sense to not add it to this one either. |
ConsumerPartitionAssignor | partition.assignment.strategy | This interface does not have a close() method. This interface is being deprecated by KIP-848, hence I don't propose updating it. |
DeserializationExceptionHandler | default.deserialization.exception.handler | This interface does not have a close() method. |
ProductionExceptionHandler | default.production.exception.handler | This interface does not have a close() method. |
TimestampExtractor | default.timestamp.extractor | This interface does not have a close() method. |
RocksDBConfigSetter | rocksdb.config.setter | This interface does not have a close() method. |
SecurityProviderCreator | security.providers | This interface does not have a close() method. The instance is passed to java.security.Security and we don't control its lifecycle. |
ReplicationPolicy | replication.policy.class | MirrorMaker currently uses its own mechanism to emit metrics. This interface does not have a close() method. |
ConfigPropertyFilter | config.property.filter.class | MirrorMaker currently uses its own mechanism to emit metrics. |
GroupFilter | group.filter.class | MirrorMaker currently uses its own mechanism to emit metrics. |
TopicFilter | topic.filter.class | MirrorMaker currently uses its own mechanism to emit metrics. |
ForwardingAdmin | forwarding.admin.class | MirrorMaker currently uses its own mechanism to emit metrics. |
...
Code Block | ||
---|---|---|
| ||
public class MyInterceptor<K, V> implements ProducerInterceptor<K, V>, Monitorable { private Sensor sensor; private PluginMetrics metrics; public void withPluginMetrics(PluginMetrics metrics) { this.metrics = metrics; sensor = metrics.sensor("onSend"); MetricName rate = metrics.metricName("rate", "Average number of calls per second.", Collections.emptyMap()); MetricName total = metrics.metricName("total", "Total number of calls.", Collections.emptyMap()); sensor.add(rate, new Rate()); sensor.add(total, new CumulativeCount()); } @Override public ProducerRecord<K, V> onSend(ProducerRecord<K, V> record) { sensor.record(); return record; } @Override public void close() { try { if (metrics != null) metrics.close(); } catch (IOException e) { // Even though ProducerInterceptor extends AutoCloseable which has "void close() throws Exception;", ProducerInterceptor has its own close() method without "throws"! throw new RuntimeException(e); } } } |
...