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 Summary
Constructors Constructor 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 sensorsMetrics(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 MetricContextMetrics(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 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.void
addReporter(MetricsReporter reporter)
Add a MetricReportervoid
close()
Close this metrics repository.MetricConfig
config()
Sensor
getSensor(String name)
Get the sensor with the given name if it existsKafkaMetric
metric(MetricName metricName)
MetricName
metricInstance(MetricNameTemplate template, String... keyValue)
MetricName
metricInstance(MetricNameTemplate template, Map<String,String> tags)
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, 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, String... keyValue)
Create a MetricName with the given name, group, description, and keyValue as tags, plus 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, Map<String,String> tags)
Create a MetricName with the given name, group and tags, plus default tags specified in the metric configuration.Map<MetricName,KafkaMetric>
metrics()
Get all the metrics currently maintained indexed by metricNameKafkaMetric
removeMetric(MetricName metricName)
Remove a metric if it exists and return it.void
removeReporter(MetricsReporter reporter)
Remove a MetricReportervoid
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.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, 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, 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, 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.Sensor
sensor(String name, 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.
-
-
-
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 configreporters
- The metrics reporterstime
- 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 configreporters
- The metrics reporterstime
- The time instance to use with the metricsmetricsContext
- 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 configreporters
- The metrics reporterstime
- The time instance to use with the metricsenableExpiration
- 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 configreporters
- The metrics reporterstime
- The time instance to use with the metricsenableExpiration
- true if the metrics instance can garbage collect inactive sensors, false otherwisemetricsContext
- 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 metricgroup
- logical group name of the metrics to which this metric belongsdescription
- A human-readable description to include in the metrictags
- 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 metricgroup
- logical group name of the metrics to which this metric belongsdescription
- 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 metricgroup
- 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 metricgroup
- logical group name of the metrics to which this metric belongsdescription
- A human-readable description to include in the metrickeyValue
- 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 metricgroup
- logical group name of the metrics to which this metric belongstags
- 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 eachMetricNameTemplate
.- Parameters:
domain
- the domain or prefix for the JMX MBean names; may not be nullallMetrics
- the collection of allMetricNameTemplate
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 sensorparents
- 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 sensorconfig
- A default configuration to use for this sensor for metrics that don't have their own configparents
- 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 sensorconfig
- A default configuration to use for this sensor for metrics that don't have their own configrecordingLevel
- 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 sensorconfig
- A default configuration to use for this sensor for metrics that don't have their own configinactiveSensorExpirationTimeSeconds
- If no value if recorded on the Sensor for this duration of time, it is eligible for removalparents
- The parent sensorsrecordingLevel
- 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 sensorconfig
- A default configuration to use for this sensor for metrics that don't have their own configinactiveSensorExpirationTimeSeconds
- If no value if recorded on the Sensor for this duration of time, it is eligible for removalparents
- 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 asaddMetric(MetricName, MetricValueProvider)
.- Parameters:
metricName
- The name of the metricmeasurable
- 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 asaddMetric(MetricName, MetricConfig, MetricValueProvider)
.- Parameters:
metricName
- The name of the metricconfig
- The configuration to use when measuring this measurablemeasurable
- 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 metricmetricValueProvider
- The metric value provider associated with this metric
-
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 metricmetricValueProvider
- The metric value provider associated with this metric
-
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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
-