Metrics (clients 7.4.13-ce API)

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

All Methods Static Methods Instance Methods Concrete Methods
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()`
`io.confluent.telemetry.api.events.EventEmitter`	`eventEmitter()`
`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
  - eventEmitter
```
public io.confluent.telemetry.api.events.EventEmitter eventEmitter()
```

Class Metrics

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Metrics

Metrics

Metrics

Metrics

Metrics

Metrics

Metrics

Metrics

Method Detail

metricName

metricName

metricName

metricName

metricName

toHtmlTable

config

getSensor

sensor

sensor

sensor

sensor

sensor

sensor

sensor

sensor

removeSensor

addMetric

addMetric

addMetric

addMetric

addMetricIfAbsent

removeMetric

addReporter

removeReporter

metrics

reporters

metric

metricInstance

metricInstance

close

eventEmitter