org.apache.kafka.common.metrics

Class Metrics

java.lang.Object

org.apache.kafka.common.metrics.Metrics

All Implemented Interfaces:

Closeable, AutoCloseable

public class Metrics
extends Object
implements Closeable

A registry of sensors and metrics.

A metric is a named, numerical measurement. A sensor is a handle to record numerical measurements as they occur. Each Sensor has zero or more associated metrics. For example a Sensor might represent message sizes and we might associate with this sensor a metric for the average, maximum, or other statistics computed off the sequence of message sizes that are recorded by the sensor.

Usage looks something like this:

 // set up metrics:
 Metrics metrics = new Metrics(); // this is the global repository of metrics and sensors
 Sensor sensor = metrics.sensor("message-sizes");
 MetricName metricName = new MetricName("message-size-avg", "producer-metrics");
 sensor.add(metricName, new Avg());
 metricName = new MetricName("message-size-max", "producer-metrics");
 sensor.add(metricName, new Max());
 
 // as messages are sent we record the sizes
 sensor.record(messageSize);
 

Constructor Summary

Constructors

Constructor and Description
Metrics() Create a metrics repository with no metric reporters and default configuration.
Metrics(MetricConfig defaultConfig) Create a metrics repository with no reporters and the given default config.
Metrics(MetricConfig defaultConfig, List<MetricsReporter> reporters, org.apache.kafka.common.utils.Time time) Create a metrics repository with a default config and the given metric reporters.
Metrics(MetricConfig defaultConfig, List<MetricsReporter> reporters, org.apache.kafka.common.utils.Time time, boolean enableExpiration) Create a metrics repository with a default config, given metric reporters and the ability to expire eligible sensors
Metrics(MetricConfig defaultConfig, List<MetricsReporter> reporters, org.apache.kafka.common.utils.Time time, boolean enableExpiration, MetricsContext metricsContext) Create a metrics repository with a default config, given metric reporters, the ability to expire eligible sensors and MetricContext
Metrics(MetricConfig defaultConfig, List<MetricsReporter> reporters, org.apache.kafka.common.utils.Time time, MetricsContext metricsContext) Create a metrics repository with a default config, metric reporters and metric context Expiration of Sensors is disabled.
Metrics(MetricConfig defaultConfig, org.apache.kafka.common.utils.Time time) Create a metrics repository with no metric reporters and the given default configuration.
Metrics(org.apache.kafka.common.utils.Time time) Create a metrics repository with no metric reporters and default configuration.

Method Summary

Modifier and Type	Method and Description
void	addMetric(MetricName metricName, Measurable measurable) Add a metric to monitor an object that implements measurable.
void	addMetric(MetricName metricName, MetricConfig config, Measurable measurable) Add a metric to monitor an object that implements Measurable.
void	addMetric(MetricName metricName, MetricConfig config, MetricValueProvider<?> metricValueProvider) Add a metric to monitor an object that implements MetricValueProvider.
void	addMetric(MetricName metricName, MetricValueProvider<?> metricValueProvider) Add a metric to monitor an object that implements MetricValueProvider.
KafkaMetric	addMetricIfAbsent(MetricName metricName, MetricConfig config, MetricValueProvider<?> metricValueProvider) Create or get an existing metric to monitor an object that implements MetricValueProvider.
void	addReporter(MetricsReporter reporter) Add a MetricReporter
void	close() Close this metrics repository.
MetricConfig	config()
Sensor	getSensor(String name) Get the sensor with the given name if it exists
KafkaMetric	metric(MetricName metricName)
MetricName	metricInstance(MetricNameTemplate template, Map<String,String> tags)
MetricName	metricInstance(MetricNameTemplate template, String... keyValue)
MetricName	metricName(String name, String group) Create a MetricName with the given name, group and default tags specified in the metric configuration.
MetricName	metricName(String name, String group, Map<String,String> tags) Create a MetricName with the given name, group and tags, plus default tags specified in the metric configuration.
MetricName	metricName(String name, String group, String description) Create a MetricName with the given name, group, description, and default tags specified in the metric configuration.
MetricName	metricName(String name, String group, String description, Map<String,String> tags) Create a MetricName with the given name, group, description and tags, plus default tags specified in the metric configuration.
MetricName	metricName(String name, String group, String description, String... keyValue) Create a MetricName with the given name, group, description, and keyValue as tags, plus default tags specified in the metric configuration.
Map<MetricName,KafkaMetric>	metrics() Get all the metrics currently maintained indexed by metricName
KafkaMetric	removeMetric(MetricName metricName) Remove a metric if it exists and return it.
void	removeReporter(MetricsReporter reporter) Remove a MetricReporter
void	removeSensor(String name) Remove a sensor (if it exists), associated metrics and its children.
List<MetricsReporter>	reporters()
Sensor	sensor(String name) Get or create a sensor with the given unique name and no parent sensors.
Sensor	sensor(String name, MetricConfig config, long inactiveSensorExpirationTimeSeconds, Sensor... parents) Get or create a sensor with the given unique name and zero or more parent sensors.
Sensor	sensor(String name, MetricConfig config, long inactiveSensorExpirationTimeSeconds, Sensor.RecordingLevel recordingLevel, Sensor... parents) Get or create a sensor with the given unique name and zero or more parent sensors.
Sensor	sensor(String name, MetricConfig config, Sensor... parents) Get or create a sensor with the given unique name and zero or more parent sensors.
Sensor	sensor(String name, MetricConfig config, Sensor.RecordingLevel recordingLevel, Sensor... parents) Get or create a sensor with the given unique name and zero or more parent sensors.
Sensor	sensor(String name, Sensor... parents) Get or create a sensor with the given unique name and zero or more parent sensors.
Sensor	sensor(String name, Sensor.RecordingLevel recordingLevel) Get or create a sensor with the given unique name and no parent sensors and with a given recording level.
Sensor	sensor(String name, Sensor.RecordingLevel recordingLevel, Sensor... parents) Get or create a sensor with the given unique name and zero or more parent sensors.
static String	toHtmlTable(String domain, Iterable<MetricNameTemplate> allMetrics) Use the specified domain and metric name templates to generate an HTML table documenting the metrics.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Metrics

public Metrics()

Create a metrics repository with no metric reporters and default configuration. Expiration of Sensors is disabled.

Metrics

public Metrics(org.apache.kafka.common.utils.Time time)

Create a metrics repository with no metric reporters and default configuration. Expiration of Sensors is disabled.

Metrics

public Metrics(MetricConfig defaultConfig,
               org.apache.kafka.common.utils.Time time)

Create a metrics repository with no metric reporters and the given default configuration. Expiration of Sensors is disabled.

Metrics

public Metrics(MetricConfig defaultConfig)

Create a metrics repository with no reporters and the given default config. This config will be used for any metric that doesn't override its own config. Expiration of Sensors is disabled.

Parameters:

defaultConfig - The default config to use for all metrics that don't override their config

Metrics

public Metrics(MetricConfig defaultConfig,
               List<MetricsReporter> reporters,
               org.apache.kafka.common.utils.Time time)

Create a metrics repository with a default config and the given metric reporters. Expiration of Sensors is disabled.

Parameters:

defaultConfig - The default config

reporters - The metrics reporters

time - The time instance to use with the metrics

Metrics

public Metrics(MetricConfig defaultConfig,
               List<MetricsReporter> reporters,
               org.apache.kafka.common.utils.Time time,
               MetricsContext metricsContext)

Create a metrics repository with a default config, metric reporters and metric context Expiration of Sensors is disabled.

Parameters:

defaultConfig - The default config

reporters - The metrics reporters

time - The time instance to use with the metrics

metricsContext - The metricsContext to initialize metrics reporter with

Metrics

public Metrics(MetricConfig defaultConfig,
               List<MetricsReporter> reporters,
               org.apache.kafka.common.utils.Time time,
               boolean enableExpiration)

Create a metrics repository with a default config, given metric reporters and the ability to expire eligible sensors

Parameters:

defaultConfig - The default config

reporters - The metrics reporters

time - The time instance to use with the metrics

enableExpiration - true if the metrics instance can garbage collect inactive sensors, false otherwise

Metrics

public Metrics(MetricConfig defaultConfig,
               List<MetricsReporter> reporters,
               org.apache.kafka.common.utils.Time time,
               boolean enableExpiration,
               MetricsContext metricsContext)

Create a metrics repository with a default config, given metric reporters, the ability to expire eligible sensors and MetricContext

Parameters:

defaultConfig - The default config

reporters - The metrics reporters

time - The time instance to use with the metrics

enableExpiration - true if the metrics instance can garbage collect inactive sensors, false otherwise

metricsContext - The metricsContext to initialize metrics reporter with

Method Detail

metricName

public MetricName metricName(String name,
                             String group,
                             String description,
                             Map<String,String> tags)

Create a MetricName with the given name, group, description and tags, plus default tags specified in the metric configuration. Tag in tags takes precedence if the same tag key is specified in the default metric configuration.

Parameters:

name - The name of the metric

group - logical group name of the metrics to which this metric belongs

description - A human-readable description to include in the metric

tags - additional key/value attributes of the metric

metricName

public MetricName metricName(String name,
                             String group,
                             String description)

Create a MetricName with the given name, group, description, and default tags specified in the metric configuration.

Parameters:

name - The name of the metric

group - logical group name of the metrics to which this metric belongs

description - A human-readable description to include in the metric

metricName

public MetricName metricName(String name,
                             String group)

Create a MetricName with the given name, group and default tags specified in the metric configuration.

Parameters:

name - The name of the metric

group - logical group name of the metrics to which this metric belongs

metricName

public MetricName metricName(String name,
                             String group,
                             String description,
                             String... keyValue)

Create a MetricName with the given name, group, description, and keyValue as tags, plus default tags specified in the metric configuration. Tag in keyValue takes precedence if the same tag key is specified in the default metric configuration.

Parameters:

name - The name of the metric

group - logical group name of the metrics to which this metric belongs

description - A human-readable description to include in the metric

keyValue - additional key/value attributes of the metric (must come in pairs)

metricName

public MetricName metricName(String name,
                             String group,
                             Map<String,String> tags)

Create a MetricName with the given name, group and tags, plus default tags specified in the metric configuration. Tag in tags takes precedence if the same tag key is specified in the default metric configuration.

Parameters:

name - The name of the metric

group - logical group name of the metrics to which this metric belongs

tags - key/value attributes of the metric

toHtmlTable

public static String toHtmlTable(String domain,
                                 Iterable<MetricNameTemplate> allMetrics)

Use the specified domain and metric name templates to generate an HTML table documenting the metrics. A separate table section will be generated for each of the MBeans and the associated attributes. The MBean names are lexicographically sorted to determine the order of these sections. This order is therefore dependent upon the order of the tags in each MetricNameTemplate.

Parameters:

domain - the domain or prefix for the JMX MBean names; may not be null

allMetrics - the collection of all MetricNameTemplate instances each describing one metric; may not be null

Returns:

the string containing the HTML table; never null

config

public MetricConfig config()

getSensor

public Sensor getSensor(String name)

Get the sensor with the given name if it exists

Parameters:

name - The name of the sensor

Returns:

Return the sensor or null if no such sensor exists

sensor

public Sensor sensor(String name)

Get or create a sensor with the given unique name and no parent sensors. This uses a default recording level of INFO.

Parameters:

name - The sensor name

Returns:

The sensor

sensor

public Sensor sensor(String name,
                     Sensor.RecordingLevel recordingLevel)

Get or create a sensor with the given unique name and no parent sensors and with a given recording level.

Parameters:

name - The sensor name.

recordingLevel - The recording level.

Returns:

The sensor

sensor

public Sensor sensor(String name,
                     Sensor... parents)

Get or create a sensor with the given unique name and zero or more parent sensors. All parent sensors will receive every value recorded with this sensor. This uses a default recording level of INFO.

Parameters:

name - The name of the sensor

parents - The parent sensors

Returns:

The sensor that is created

sensor

public Sensor sensor(String name,
                     Sensor.RecordingLevel recordingLevel,
                     Sensor... parents)

Get or create a sensor with the given unique name and zero or more parent sensors. All parent sensors will receive every value recorded with this sensor.

Parameters:

name - The name of the sensor.

parents - The parent sensors.

recordingLevel - The recording level.

Returns:

The sensor that is created

sensor

public Sensor sensor(String name,
                     MetricConfig config,
                     Sensor... parents)

Get or create a sensor with the given unique name and zero or more parent sensors. All parent sensors will receive every value recorded with this sensor. This uses a default recording level of INFO.

Parameters:

name - The name of the sensor

config - A default configuration to use for this sensor for metrics that don't have their own config

parents - The parent sensors

Returns:

The sensor that is created

sensor

public Sensor sensor(String name,
                     MetricConfig config,
                     Sensor.RecordingLevel recordingLevel,
                     Sensor... parents)

Get or create a sensor with the given unique name and zero or more parent sensors. All parent sensors will receive every value recorded with this sensor.

Parameters:

name - The name of the sensor

config - A default configuration to use for this sensor for metrics that don't have their own config

recordingLevel - The recording level.

parents - The parent sensors

Returns:

The sensor that is created

sensor

public Sensor sensor(String name,
                     MetricConfig config,
                     long inactiveSensorExpirationTimeSeconds,
                     Sensor.RecordingLevel recordingLevel,
                     Sensor... parents)

Get or create a sensor with the given unique name and zero or more parent sensors. All parent sensors will receive every value recorded with this sensor.

Parameters:

name - The name of the sensor

config - A default configuration to use for this sensor for metrics that don't have their own config

inactiveSensorExpirationTimeSeconds - If no value if recorded on the Sensor for this duration of time, it is eligible for removal

parents - The parent sensors

recordingLevel - The recording level.

Returns:

The sensor that is created

sensor

public Sensor sensor(String name,
                     MetricConfig config,
                     long inactiveSensorExpirationTimeSeconds,
                     Sensor... parents)

Get or create a sensor with the given unique name and zero or more parent sensors. All parent sensors will receive every value recorded with this sensor. This uses a default recording level of INFO.

Parameters:

name - The name of the sensor

config - A default configuration to use for this sensor for metrics that don't have their own config

inactiveSensorExpirationTimeSeconds - If no value if recorded on the Sensor for this duration of time, it is eligible for removal

parents - The parent sensors

Returns:

The sensor that is created

removeSensor

public void removeSensor(String name)

Remove a sensor (if it exists), associated metrics and its children.

Parameters:

name - The name of the sensor to be removed

addMetric

public void addMetric(MetricName metricName,
                      Measurable measurable)

Add a metric to monitor an object that implements measurable. This metric won't be associated with any sensor. This is a way to expose existing values as metrics. This method is kept for binary compatibility purposes, it has the same behaviour as addMetric(MetricName, MetricValueProvider).

Parameters:

metricName - The name of the metric

measurable - The measurable that will be measured by this metric

addMetric

public void addMetric(MetricName metricName,
                      MetricConfig config,
                      Measurable measurable)

Add a metric to monitor an object that implements Measurable. This metric won't be associated with any sensor. This is a way to expose existing values as metrics. This method is kept for binary compatibility purposes, it has the same behaviour as addMetric(MetricName, MetricConfig, MetricValueProvider).

Parameters:

metricName - The name of the metric

config - The configuration to use when measuring this measurable

measurable - The measurable that will be measured by this metric

addMetric

public void addMetric(MetricName metricName,
                      MetricConfig config,
                      MetricValueProvider<?> metricValueProvider)

Add a metric to monitor an object that implements MetricValueProvider. This metric won't be associated with any sensor. This is a way to expose existing values as metrics. User is expected to add any additional synchronization to update and access metric values, if required.

Parameters:

metricName - The name of the metric

metricValueProvider - The metric value provider associated with this metric

Throws:

IllegalArgumentException - if a metric with same name already exists.

addMetric

public void addMetric(MetricName metricName,
                      MetricValueProvider<?> metricValueProvider)

Add a metric to monitor an object that implements MetricValueProvider. This metric won't be associated with any sensor. This is a way to expose existing values as metrics. User is expected to add any additional synchronization to update and access metric values, if required.

Parameters:

metricName - The name of the metric

metricValueProvider - The metric value provider associated with this metric

addMetricIfAbsent

public KafkaMetric addMetricIfAbsent(MetricName metricName,
                                     MetricConfig config,
                                     MetricValueProvider<?> metricValueProvider)

Create or get an existing metric to monitor an object that implements MetricValueProvider. This metric won't be associated with any sensor. This is a way to expose existing values as metrics. This method takes care of synchronisation while updating/accessing metrics by concurrent threads.

Parameters:

metricName - The name of the metric

metricValueProvider - The metric value provider associated with this metric

Returns:

Existing KafkaMetric if already registered or else a newly created one

removeMetric

public KafkaMetric removeMetric(MetricName metricName)

Remove a metric if it exists and return it. Return null otherwise. If a metric is removed, `metricRemoval` will be invoked for each reporter.

Parameters:

metricName - The name of the metric

Returns:

the removed `KafkaMetric` or null if no such metric exists

addReporter

public void addReporter(MetricsReporter reporter)

Add a MetricReporter

removeReporter

public void removeReporter(MetricsReporter reporter)

Remove a MetricReporter

metrics

public Map<MetricName,KafkaMetric> metrics()

Get all the metrics currently maintained indexed by metricName

reporters

public List<MetricsReporter> reporters()

metric

public KafkaMetric metric(MetricName metricName)

metricInstance

public MetricName metricInstance(MetricNameTemplate template,
                                 String... keyValue)

metricInstance

public MetricName metricInstance(MetricNameTemplate template,
                                 Map<String,String> tags)

close

public void close()

Close this metrics repository.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable