Package org.apache.kafka.common.metrics

Class 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 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

      • 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