confluent_kafka/common/metrics/gauge.rs
1// Copyright 2025 Confluent Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! A gauge metric is an instantaneous reading of a particular value
16//! (`org.apache.kafka.common.metrics.Gauge`).
17
18use crate::common::MetricValue;
19use crate::common::metrics::{MetricConfig, MetricValueProvider};
20
21/// A gauge metric is an instantaneous reading of a particular value.
22///
23/// # Translation notes
24///
25/// It yields a [`MetricValue`].
26// Java's `Gauge<T> extends MetricValueProvider<T>` declares nothing of its own:
27// its single method is `MetricValueProvider::value`. The public metric value is
28// type-erased, so the Rust gauge produces a `MetricValue`.
29#[doc(alias = "org.apache.kafka.common.metrics.Gauge")]
30pub trait Gauge: MetricValueProvider {}
31
32/// A [`Gauge`] that calls `function`, standing in for a Java lambda
33/// implementing `Gauge` (e.g. `(config, now) -> metrics.size()`): `function`
34/// is [`MetricValueProvider::value`]. A method Java adds later as an overload
35/// of `value` gets its own factory, `with_<parameter>`.
36///
37/// # Arguments
38///
39/// - `function` - computes the value from the config and the time in milliseconds
40///
41/// # Returns
42///
43/// The gauge calling `function`.
44///
45/// ```
46/// use confluent_kafka::common::MetricValue;
47/// use confluent_kafka::common::metrics::{gauge, Metrics};
48///
49/// let metrics = Metrics::new();
50/// let name = metrics.metric_name("answer", "example");
51/// metrics
52/// .add_metric_with_metric_value_provider(name, Box::new(gauge::new(|_config, _now| MetricValue::Int(42))))
53/// .unwrap();
54/// ```
55// stands in for a Java lambda implementing `Gauge`
56#[doc(alias = "rust-only")]
57pub fn new<F>(function: F) -> impl Gauge
58where
59 F: Fn(&MetricConfig, i64) -> MetricValue + Send + Sync,
60{
61 struct FunctionGauge<F>(F);
62
63 impl<F> MetricValueProvider for FunctionGauge<F>
64 where
65 F: Fn(&MetricConfig, i64) -> MetricValue + Send + Sync,
66 {
67 fn value(&self, config: &MetricConfig, now: i64) -> MetricValue {
68 (self.0)(config, now)
69 }
70
71 // A function is Rust's lambda, which Java's `KafkaMetric.toString` omits.
72 fn type_name(&self) -> Option<&'static str> {
73 None
74 }
75 }
76
77 impl<F> Gauge for FunctionGauge<F> where F: Fn(&MetricConfig, i64) -> MetricValue + Send + Sync {}
78
79 FunctionGauge(function)
80}
81
82#[cfg(test)]
83mod tests {
84 use super::*;
85
86 #[test]
87 fn new_calls_the_function_and_reports_no_type_name() {
88 let gauge = new(|config, now| MetricValue::Long(now + i64::from(config.samples())));
89 let config = MetricConfig::default();
90 assert_eq!(gauge.value(&config, 40), MetricValue::Long(40 + i64::from(config.samples())));
91 assert_eq!(gauge.type_name(), None);
92 }
93}