Struct Metrics 

pub struct Metrics { /* private fields */ }

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.

Translation notes

The subset of Java’s Metrics the clients use: JMX, the sensor-expiry task and the quota machinery are omitted.

Implementations

impl Metrics

pub fn new() -> Self

Create a metrics repository with a default config, no reporters, and the system clock.

pub fn with_default_config(default_config: Arc<MetricConfig>) -> Self

Create a metrics repository with the supplied default config.

Arguments

• default_config - The default config to use for all metrics that don’t override their config

pub fn metric_name_with_description_tags( &self, name: impl Into<String>, group: impl Into<String>, description: impl Into<String>, tags: BTreeMap<String, String>, ) -> MetricName

Returns a MetricName with the given name, group, description and tags, plus default tags specified in the metric configuration. Tags in tags take precedence over default tags with the same key.

Arguments

• 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

pub fn metric_name_with_description( &self, name: impl Into<String>, group: impl Into<String>, description: impl Into<String>, ) -> MetricName

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

Arguments

• 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

pub fn metric_name_with_tags( &self, name: impl Into<String>, group: impl Into<String>, tags: BTreeMap<String, String>, ) -> MetricName

Returns a MetricName with the given name, group and tags, plus the default tags specified in the metric configuration. Tags in tags take precedence over default tags with the same key.

Arguments

• name - The name of the metric
• group - logical group name of the metrics to which this metric belongs
• tags - additional key/value attributes of the metric

pub fn metric_name( &self, name: impl Into<String>, group: impl Into<String>, ) -> MetricName

Returns a MetricName with name and group (empty description, default tags).

Arguments

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

pub fn metric_name_with_description_key_value( &self, name: impl Into<String>, group: impl Into<String>, description: impl Into<String>, key_value: &[&str], ) -> Result<MetricName, Error>

Returns a MetricName from key, value tag pairs, plus default tags.

Arguments

• 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
• key_value - additional key/value attributes of the metric (must come in pairs)

Errors

• Error::is_local_illegal_argument_error if key_value has an odd length

pub fn config(&self) -> &Arc<MetricConfig>

Returns the default config of this registry.

pub fn get_sensor(&self, name: &str) -> Option<Arc<Sensor>>

Get the sensor with the given name if it exists.

Arguments

• name - The name of the sensor

Returns

Return the sensor or None if no such sensor exists

pub fn sensor(&self, name: &str) -> Result<Arc<Sensor>, Error>

Get or create a sensor with the given unique name and no parents at INFO recording level.

Arguments

• name - The sensor name

Returns

The sensor

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_recording_level( &self, name: &str, recording_level: RecordingLevel, ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with the given name, recording level, and no parents.

Arguments

• name - The sensor name.
• recording_level - The recording level.

Returns

The sensor

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_parents( &self, name: &str, parents: &[Arc<Sensor>], ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with parents at INFO recording level.

Arguments

• name - The name of the sensor
• parents - The parent sensors

Returns

The sensor that is created

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_recording_level_parents( &self, name: &str, recording_level: RecordingLevel, parents: &[Arc<Sensor>], ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with the given name, recording level and parents.

Arguments

• name - The name of the sensor.
• recording_level - The recording level.
• parents - The parent sensors.

Returns

The sensor that is created

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_config_parents( &self, name: &str, config: Option<Arc<MetricConfig>>, parents: &[Arc<Sensor>], ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with a config and parents, at INFO recording level.

Arguments

• 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

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_config_recording_level_parents( &self, name: &str, config: Option<Arc<MetricConfig>>, recording_level: RecordingLevel, parents: &[Arc<Sensor>], ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with a config, recording level and parents.

Arguments

• name - The name of the sensor
• config - A default configuration to use for this sensor for metrics that don’t have their own config
• recording_level - The recording level.
• parents - The parent sensors

Returns

The sensor that is created

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_config_inactive_sensor_expiration_time_seconds_parents( &self, name: &str, config: Option<Arc<MetricConfig>>, inactive_sensor_expiration_time_seconds: i64, parents: &[Arc<Sensor>], ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with a config, expiration and parents, at INFO recording level.

Arguments

• name - The name of the sensor
• config - A default configuration to use for this sensor for metrics that don’t have their own config
• inactive_sensor_expiration_time_seconds - If no value is recorded on the Sensor for this duration of time, it is eligible for removal
• parents - The parent sensors

Returns

The sensor that is created

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn sensor_with_options( &self, options: SensorOptions<'_>, ) -> Result<Arc<Sensor>, Error>

Get or create a sensor with a config, expiration, recording level and parents.

Arguments

• options - every parameter, name included

Returns

The sensor

Errors

• Error::is_local_illegal_argument_error if the sensor would be its own ancestor

pub fn remove_sensor(&self, name: &str)

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

Arguments

• name - The name of the sensor to be removed

pub fn add_metric_with_measurable( &self, metric_name: MetricName, measurable: Box<dyn Measurable>, ) -> Result<(), Error>

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 Self::add_metric_with_metric_value_provider.

Arguments

• metric_name - The name of the metric
• measurable - The measurable that will be measured by this metric

Errors

• Error::is_local_illegal_argument_error if a metric with same name already exists.

pub fn add_metric_with_metric_value_provider( &self, metric_name: MetricName, metric_value_provider: Box<dyn MetricValueProvider>, ) -> Result<(), Error>

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.

Arguments

• metric_name - The name of the metric
• metric_value_provider - The metric value provider associated with this metric

Errors

• Error::is_local_illegal_argument_error if a metric with same name already exists.

pub fn add_metric_with_config_metric_value_provider( &self, metric_name: MetricName, config: Option<Arc<MetricConfig>>, provider: Box<dyn MetricValueProvider>, ) -> Result<(), Error>

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.

Arguments

• metric_name - The name of the metric
• config - The configuration to use when measuring this measurable, None for the registry’s default config
• provider - The metric value provider associated with this metric

Errors

• Error::is_local_illegal_argument_error if a metric with same name already exists.

pub fn add_metric_if_absent( &self, metric_name: MetricName, config: Option<Arc<MetricConfig>>, provider: Box<dyn MetricValueProvider>, ) -> Arc<KafkaMetric>

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.

Arguments

• metric_name - The name of the metric
• config - The configuration to use when measuring this metric, None for the registry’s default config
• provider - The metric value provider associated with this metric

Returns

Existing KafkaMetric if already registered or else a newly created one

pub fn remove_metric( &self, metric_name: &MetricName, ) -> Option<Arc<KafkaMetric>>

Remove a metric if it exists and return it. metric_removal is invoked on each reporter when a metric is removed.

Arguments

• metric_name - The name of the metric

Returns

the removed KafkaMetric or None if no such metric exists

pub fn add_reporter(&self, reporter: Arc<dyn MetricsReporter>)

Add a MetricsReporter

Arguments

• reporter - the reporter, initialized with every existing metric

pub fn metrics(&self) -> MetricsView

Get all the metrics currently maintained indexed by metricName

Returns

a live, read-only view of the metrics: it sees every metric registered or removed after the call

pub fn metric(&self, metric_name: &MetricName) -> Option<Arc<KafkaMetric>>

Returns the metric with the given name, if registered.

Arguments

• metric_name - the name of the metric

pub fn metric_instance_with_key_value( &self, template: &MetricNameTemplate, key_value: &[&str], ) -> Result<MetricName, Error>

Returns a MetricName built from a template and tag pairs.

Arguments

• template - the template of the metric name
• key_value - the tags, as key and value pairs

Errors

• Error::is_local_illegal_argument_error if key_value has an odd length, or if the tags, with the default config’s tags, are not the template’s

pub fn metric_instance_with_tags( &self, template: &MetricNameTemplate, tags: BTreeMap<String, String>, ) -> Result<MetricName, Error>

Returns a MetricName built from a template and a tags map.

Arguments

• template - the template of the metric name
• tags - the tags

Errors

• Error::is_local_illegal_argument_error if the tags, with the default config’s tags, are not the template’s

pub fn close(&self)

Close this metrics repository.

Trait Implementations

impl Debug for Metrics

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Metrics

fn default() -> Self

Returns the “default value” for a type.