Package 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 Details

    • 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 Details

    • 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 AutoCloseable
      Specified by:
      close in interface Closeable