Skip to main content

confluent_kafka/common/metrics/stats/
rate.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//! The rate of a quantity over the sample windows
16//! (`org.apache.kafka.common.metrics.stats.Rate`).
17
18use std::sync::Arc;
19
20use crate::common::metrics::TimeUnit;
21use crate::common::metrics::internals::MetricsUtils;
22use crate::common::metrics::stats::SampledStat;
23use crate::common::metrics::stats::WindowedSum;
24use crate::common::metrics::{Measurable, MetricConfig, Stat};
25
26/// The rate of the given quantity. By default this is the total observed over a
27/// set of samples from a sampled statistic divided by the elapsed time over the
28/// sample windows. Alternative [`SampledStat`] implementations can be provided,
29/// however, to record the rate of occurrences (e.g. the count of values measured
30/// over the time interval) or other such values.
31#[derive(Debug)]
32#[doc(alias = "org.apache.kafka.common.metrics.stats.Rate")]
33pub struct Rate {
34    unit: TimeUnit,
35    stat: Arc<SampledStat>,
36    time_window_ms: i64,
37}
38
39impl Rate {
40    /// Create a `Rate` over seconds backed by a [`WindowedSum`].
41    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#Rate")]
42    pub fn new() -> Self {
43        Self::with_unit(TimeUnit::Seconds)
44    }
45
46    /// Create a `Rate` with the given unit backed by a [`WindowedSum`].
47    ///
48    /// # Arguments
49    ///
50    /// - `unit` - the time unit of the rate
51    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#Rate")]
52    pub fn with_unit(unit: TimeUnit) -> Self {
53        Self::with_unit_stat(unit, Arc::new(WindowedSum::new().into_sampled_stat()))
54    }
55
56    /// Create a `Rate` over seconds backed by the given sampled stat.
57    ///
58    /// # Arguments
59    ///
60    /// - `stat` - the sampled stat whose total the rate divides
61    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#Rate")]
62    pub fn with_stat(stat: Arc<SampledStat>) -> Self {
63        Self::with_unit_stat(TimeUnit::Seconds, stat)
64    }
65
66    /// Create a `Rate` with the given unit and sampled stat.
67    ///
68    /// # Arguments
69    ///
70    /// - `unit` - the time unit of the rate
71    /// - `stat` - the sampled stat whose total the rate divides
72    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#Rate")]
73    pub fn with_unit_stat(unit: TimeUnit, stat: Arc<SampledStat>) -> Self {
74        Self::with_unit_stat_window(unit, stat, -1)
75    }
76
77    /// Create a `Rate` with the given unit, sampled stat and explicit window.
78    ///
79    /// # Arguments
80    ///
81    /// - `unit` - the time unit of the rate and of `window`
82    /// - `stat` - the sampled stat whose total the rate divides
83    /// - `window` - when positive, the stat's own time window, in `unit`
84    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#Rate")]
85    pub fn with_unit_stat_window(unit: TimeUnit, stat: Arc<SampledStat>, window: i64) -> Self {
86        let time_window_ms = if window > 0 {
87            let ms = unit.to_millis(window);
88            stat.with_time_window_ms(ms);
89            ms
90        } else {
91            -1
92        };
93        Self { unit, stat, time_window_ms }
94    }
95
96    /// Returns the lower-cased name of the rate's unit with the trailing "s"
97    /// stripped, e.g. `SECONDS` -> `second`.
98    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#unitName")]
99    pub fn unit_name(&self) -> String {
100        let name = self.unit.name();
101        name[..name.len() - 2].to_lowercase()
102    }
103
104    /// The backing sampled stat (shared with the metric value provider).
105    pub(crate) fn stat(&self) -> &Arc<SampledStat> {
106        &self.stat
107    }
108
109    /// Compute the window size in milliseconds used for the rate calculation.
110    ///
111    /// # Arguments
112    ///
113    /// - `config` - the metric's configuration
114    /// - `now` - the current POSIX time in milliseconds
115    ///
116    /// # Returns
117    ///
118    /// The window size in milliseconds.
119    #[doc(alias = "org.apache.kafka.common.metrics.stats.Rate#windowSize")]
120    pub fn window_size(&self, config: &MetricConfig, now: i64) -> i64 {
121        // purge old samples before we compute the window size
122        self.stat.purge_obsolete_samples(config, now);
123
124        // Here we check the total amount of time elapsed since the oldest
125        // non-obsolete window. This gives the total windowSize of the batch which
126        // is the time used for Rate computation. However, there is an issue if we
127        // do not have sufficient data: e.g. if only 1 second has elapsed in a
128        // 30-second window, the measured rate will be very high. Hence we assume
129        // that the elapsed time is always N-1 complete windows plus whatever
130        // fraction of the final window is complete.
131        let mut total_elapsed_time_ms = now - self.stat.oldest_start_time_ms(now);
132        // If explicit time window is provided, use that instead of the config value.
133        let window_ms = if self.time_window_ms > 0 {
134            self.time_window_ms
135        } else {
136            config.time_window_ms()
137        };
138        // Check how many full windows of data we have currently retained
139        let num_full_windows = (total_elapsed_time_ms / window_ms) as i32;
140        let min_full_windows = config.samples() - 1;
141
142        // If the available windows are less than the minimum required, add the
143        // difference to the totalElapsedTime
144        if num_full_windows < min_full_windows {
145            total_elapsed_time_ms += (min_full_windows - num_full_windows) as i64 * window_ms;
146        }
147
148        // If window size is being calculated at the exact beginning of the window
149        // with no prior samples, the window size will result in a value of 0.
150        // Calculation of rate over a window of size 0 is undefined, hence we assume
151        // the minimum window size to be at least 1ms.
152        total_elapsed_time_ms.max(1)
153    }
154}
155
156impl Default for Rate {
157    fn default() -> Self {
158        Self::new()
159    }
160}
161
162impl Stat for Rate {
163    fn record(&self, config: &MetricConfig, value: f64, time_ms: i64) {
164        self.stat.record(config, value, time_ms);
165    }
166}
167
168impl Measurable for Rate {
169    fn measure(&self, config: &MetricConfig, now: i64) -> f64 {
170        let value = self.stat.measure(config, now);
171        value / MetricsUtils::convert(self.window_size(config, now), self.unit)
172    }
173}
174
175impl std::fmt::Display for Rate {
176    /// Java's `toString()`, which `SimpleRate` inherits.
177    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
178        write!(f, "Rate(unit={}, stat={})", self.unit.name(), self.stat)
179    }
180}
181
182#[cfg(test)]
183mod tests {
184    use super::*;
185
186    #[test]
187    fn to_string_follows_java() {
188        assert_eq!(
189            Rate::new().to_string(),
190            "Rate(unit=SECONDS, stat=SampledStat(initialValue=0.0, current=0, samples=[]))"
191        );
192        assert_eq!(
193            Rate::with_unit(TimeUnit::Milliseconds).to_string(),
194            "Rate(unit=MILLISECONDS, stat=SampledStat(initialValue=0.0, current=0, samples=[]))"
195        );
196    }
197    use crate::common::metrics::internals::MetricsUtils;
198    use crate::common::utils::MockTime;
199    use crate::common::utils::Time;
200
201    const EPS: f64 = 0.000001;
202
203    // RateTest.testRateWithNoPriorAvailableSamples (@ParameterizedTest CsvSource).
204    #[test]
205    #[doc(alias = "org.apache.kafka.common.metrics.stats.RateTest#testRateWithNoPriorAvailableSamples")]
206    fn test_rate_with_no_prior_available_samples() {
207        // {numSample, sampleWindowSizeSec}
208        for (num_sample, sample_window_size_sec) in [(1, 1), (1, 11), (11, 1), (11, 11)] {
209            let config = MetricConfig::new()
210                .set_samples(num_sample)
211                .set_time_window(sample_window_size_sec, TimeUnit::Seconds);
212            let rate = Rate::new();
213            let time = MockTime::new();
214            let sample_value = 50.0;
215            // record at beginning of the window
216            rate.record(&config, sample_value, time.milliseconds());
217            // forward time till almost the end of window
218            let measurement_time = TimeUnit::Seconds.to_millis(sample_window_size_sec) - 1;
219            time.sleep(measurement_time);
220            // calculate rate at almost the end of window
221            let observed_rate = rate.measure(&config, time.milliseconds());
222            assert!(!observed_rate.is_nan());
223
224            // The rate calculation assumes N-1 prior samples of value 0.
225            let dummy_prior_samples_assumed = (num_sample - 1) as f64;
226            let window_size = MetricsUtils::convert(measurement_time, TimeUnit::Seconds)
227                + (dummy_prior_samples_assumed * sample_window_size_sec as f64);
228            let expected_rate_per_sec = sample_value / window_size;
229            assert!(
230                (expected_rate_per_sec - observed_rate).abs() <= EPS,
231                "numSample={num_sample}, window={sample_window_size_sec}: expected {expected_rate_per_sec}, got {observed_rate}"
232            );
233        }
234    }
235
236    // RateTest.testRateIsConsistentAfterTheFirstWindow
237    #[test]
238    #[doc(alias = "org.apache.kafka.common.metrics.stats.RateTest#testRateIsConsistentAfterTheFirstWindow")]
239    fn test_rate_is_consistent_after_the_first_window() {
240        let config = MetricConfig::new().set_time_window(1, TimeUnit::Seconds).set_samples(2);
241        let rate = Rate::new();
242        let time = MockTime::new();
243        let steps = [0, 99, 100, 100, 100, 100, 100, 100, 100, 100, 100];
244
245        // start the first window and record events at 0,99,199,...,999 ms
246        for step_ms in steps {
247            time.sleep(step_ms);
248            rate.record(&config, 1.0, time.milliseconds());
249        }
250
251        // making a gap of 100 ms between windows
252        time.sleep(101);
253
254        // start the second window and record events at 0,99,199,...,999 ms
255        for step_ms in steps {
256            time.sleep(step_ms);
257            rate.record(&config, 1.0, time.milliseconds());
258            let observed_rate = rate.measure(&config, time.milliseconds());
259            assert!((10.0..=11.0).contains(&observed_rate), "observed_rate={observed_rate}");
260            // make sure measurements are repeatable with the same timestamp
261            let measured_again = rate.measure(&config, time.milliseconds());
262            assert_eq!(observed_rate, measured_again);
263        }
264    }
265
266    #[test]
267    fn unit_name_strips_last_two_chars() {
268        // Faithful to Java Rate.unitName(): name().substring(0, length-2).toLowerCase().
269        // "SECONDS" (7) -> [0..5] = "SECON" -> "secon".
270        assert_eq!("secon", Rate::with_unit(TimeUnit::Seconds).unit_name());
271        // "MILLISECONDS" (12) -> [0..10] = "MILLISECON" -> "millisecon".
272        assert_eq!("millisecon", Rate::with_unit(TimeUnit::Milliseconds).unit_name());
273    }
274}