Skip to main content

confluent_kafka/common/metrics/
sensor.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 sensor applies a continuous sequence of numerical values to a set of
16//! associated metrics (`org.apache.kafka.common.metrics.Sensor`).
17
18use std::collections::HashSet;
19use std::sync::atomic::{AtomicI64, Ordering};
20use std::sync::{Arc, Mutex, Weak};
21
22use crate::common::Metric;
23use crate::common::metrics::MetricsShared;
24use crate::common::metrics::{
25    CompoundStat, KafkaMetric, Measurable, MeasurableStat, MetricConfig, Quota, QuotaViolationError, Stat,
26};
27use crate::common::utils::Time;
28use crate::common::{Error, MetricName};
29
30/// The recording level of a sensor or metric config.
31///
32/// Mirrors `Sensor.RecordingLevel`. The numeric ids are part of the protocol and
33/// must not change: INFO=0, DEBUG=1, TRACE=2.
34#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
35#[non_exhaustive]
36#[doc(alias = "org.apache.kafka.common.metrics.Sensor$RecordingLevel")]
37pub enum RecordingLevel {
38    /// INFO level (id 0).
39    Info,
40    /// DEBUG level (id 1).
41    Debug,
42    /// TRACE level (id 2).
43    Trace,
44}
45
46/// Java's inherited `Enum.toString()`: the constant's name.
47impl std::fmt::Display for RecordingLevel {
48    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
49        f.write_str(self.name())
50    }
51}
52
53impl RecordingLevel {
54    /// Returns the permanent and immutable id of this level.
55    #[doc(alias = "org.apache.kafka.common.metrics.Sensor$RecordingLevel#id")]
56    pub fn id(&self) -> i16 {
57        match self {
58            RecordingLevel::Info => 0,
59            RecordingLevel::Debug => 1,
60            RecordingLevel::Trace => 2,
61        }
62    }
63
64    /// Returns an English description of the level.
65    #[doc(alias = "org.apache.kafka.common.metrics.Sensor$RecordingLevel#name")]
66    pub fn name(&self) -> &'static str {
67        match self {
68            RecordingLevel::Info => "INFO",
69            RecordingLevel::Debug => "DEBUG",
70            RecordingLevel::Trace => "TRACE",
71        }
72    }
73
74    /// Lookup by id.
75    ///
76    /// # Arguments
77    ///
78    /// - `id` - the level's id
79    ///
80    /// # Returns
81    ///
82    /// The level with that id.
83    ///
84    /// # Errors
85    ///
86    /// - `Error::is_local_illegal_argument_error` if `id` is not between `0` and `2`
87    #[doc(alias = "org.apache.kafka.common.metrics.Sensor$RecordingLevel#forId")]
88    pub fn for_id(id: i16) -> Result<RecordingLevel, Error> {
89        match id {
90            0 => Ok(RecordingLevel::Info),
91            1 => Ok(RecordingLevel::Debug),
92            2 => Ok(RecordingLevel::Trace),
93            _ => Err(Error::local_illegal_argument(format!(
94                "Unexpected RecordLevel id `{id}`, it should be between `0` and `2` (inclusive)"
95            ))),
96        }
97    }
98
99    /// Case insensitive lookup by protocol name
100    ///
101    /// # Arguments
102    ///
103    /// - `name` - the level's name, in any case
104    ///
105    /// # Returns
106    ///
107    /// The level with that name.
108    ///
109    /// # Errors
110    ///
111    /// - `Error::is_local_illegal_argument_error` if no level has that name
112    #[doc(alias = "org.apache.kafka.common.metrics.Sensor$RecordingLevel#forName")]
113    pub fn for_name(name: &str) -> Result<RecordingLevel, Error> {
114        match name.to_uppercase().as_str() {
115            "INFO" => Ok(RecordingLevel::Info),
116            "DEBUG" => Ok(RecordingLevel::Debug),
117            "TRACE" => Ok(RecordingLevel::Trace),
118            other => Err(Error::local_illegal_argument(format!(
119                "No enum constant RecordingLevel.{other}"
120            ))),
121        }
122    }
123
124    /// Returns whether a sensor at this level should record given the config's
125    /// level id.
126    ///
127    /// # Arguments
128    ///
129    /// - `config_id` - the id of the config's recording level
130    ///
131    /// # Panics
132    ///
133    /// If `config_id` is not the id of a level, with the message of Java's
134    /// `IllegalStateException`.
135    #[doc(alias = "org.apache.kafka.common.metrics.Sensor$RecordingLevel#shouldRecord")]
136    pub fn should_record(&self, config_id: i16) -> bool {
137        if config_id == RecordingLevel::Info.id() {
138            self.id() == RecordingLevel::Info.id()
139        } else if config_id == RecordingLevel::Debug.id() {
140            self.id() == RecordingLevel::Info.id() || self.id() == RecordingLevel::Debug.id()
141        } else if config_id == RecordingLevel::Trace.id() {
142            true
143        } else {
144            // Java throws IllegalStateException; this is an internal invariant
145            // violation, treated as a programming error.
146            panic!("Did not recognize recording level {config_id}")
147        }
148    }
149}
150
151/// A registered stat paired with the config it should be recorded with.
152///
153/// Java's `StatAndConfig` holds the stat plus a `Supplier<MetricConfig>`. For the
154/// `add(MetricName, MeasurableStat, config)` path the supplier is `metric::config`
155/// so the stat always reads the backing metric's (possibly updated) config; for
156/// the `add(CompoundStat, config)` path it is a constant `statConfig` supplier.
157/// Both are modelled by [`StatConfigSource`].
158#[doc(alias = "org.apache.kafka.common.metrics.Sensor$StatAndConfig")]
159struct StatAndConfig {
160    stat: Box<dyn Stat>,
161    config: StatConfigSource,
162}
163
164/// Where a `StatAndConfig` reads its config from, mirroring Java's
165/// `Supplier<MetricConfig>`:
166///
167/// - `FromMetric` — the supplier is `metric::config`, so the stat always reads
168///   the backing metric's (possibly updated) config. Used by
169///   `add(MetricName, MeasurableStat, config)`.
170/// - `Constant` — a fixed `statConfig` supplier (`() -> statConfig`). Used by
171///   `add(CompoundStat, config)`, whose single recordable stat is not coupled to
172///   any one child metric.
173enum StatConfigSource {
174    FromMetric(Arc<KafkaMetric>),
175    Constant(Arc<MetricConfig>),
176}
177
178impl StatAndConfig {
179    fn record(&self, value: f64, time_ms: i64) {
180        let config = match &self.config {
181            StatConfigSource::FromMetric(metric) => metric.config(),
182            StatConfigSource::Constant(config) => Arc::clone(config),
183        };
184        self.stat.record(&config, value, time_ms);
185    }
186}
187
188/// A sensor applies a continuous sequence of numerical values to a set of
189/// associated metrics. For example a sensor on message size would record a
190/// sequence of message sizes using the `record` api and would maintain a set of
191/// metrics about request sizes such as the average or max.
192#[doc(alias = "org.apache.kafka.common.metrics.Sensor")]
193pub struct Sensor {
194    /// Java's `registry`, held weakly: the registry's metrics map holds the
195    /// providers of every metric, and a provider may capture an object that
196    /// holds this sensor (`BufferPool`'s gauges capture the pool, which holds
197    /// its `bufferpool-wait-time` sensor), so a strong reference would be an
198    /// `Arc` cycle keeping the registry and everything its providers capture
199    /// allocated forever. Java's garbage collector frees the same graph. The
200    /// registry is owned by its [`Metrics`](crate::common::metrics::Metrics);
201    /// once that is dropped no one can read the map, and `add` keeps the
202    /// metric on the sensor only, as for a standalone sensor.
203    registry: Option<Weak<MetricsShared>>,
204    name: String,
205    parents: Vec<Arc<Sensor>>,
206    inner: Mutex<SensorInner>,
207    config: Arc<MetricConfig>,
208    time: Arc<dyn Time>,
209    last_record_time: AtomicI64,
210    inactive_sensor_expiration_time_ms: i64,
211    recording_level: RecordingLevel,
212}
213
214/// The mutable interior of a sensor, guarded by a single `Mutex` mirroring
215/// Java's `synchronized` on the sensor object.
216struct SensorInner {
217    stats: Vec<StatAndConfig>,
218    metrics: indexmap::IndexMap<MetricName, Arc<KafkaMetric>>,
219}
220
221impl std::fmt::Debug for Sensor {
222    // The sensor's name, its identifier in the registry.
223    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
224        f.debug_struct("Sensor").field("name", &self.name).finish_non_exhaustive()
225    }
226}
227
228impl Sensor {
229    /// Create a sensor.
230    ///
231    /// `registry` is `None` for standalone sensors (mirroring Java's `null`
232    /// registry in `SensorTest`), in which case `add` does not register metrics
233    /// in a global repository.
234    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#Sensor")]
235    pub(crate) fn new(
236        registry: Option<Weak<MetricsShared>>,
237        name: impl Into<String>,
238        parents: Vec<Arc<Sensor>>,
239        config: Arc<MetricConfig>,
240        time: Arc<dyn Time>,
241        inactive_sensor_expiration_time_seconds: i64,
242        recording_level: RecordingLevel,
243    ) -> Result<Self, Error> {
244        let now = time.milliseconds();
245        let sensor = Sensor {
246            registry,
247            name: name.into(),
248            parents,
249            inner: Mutex::new(SensorInner { stats: Vec::new(), metrics: indexmap::IndexMap::new() }),
250            config,
251            time,
252            last_record_time: AtomicI64::new(now),
253            inactive_sensor_expiration_time_ms: inactive_sensor_expiration_time_seconds.saturating_mul(1000),
254            recording_level,
255        };
256        // Validate that this sensor doesn't reference itself.
257        let mut seen: HashSet<*const Sensor> = HashSet::new();
258        sensor.check_forest(&mut seen)?;
259        Ok(sensor)
260    }
261
262    /// Validate that this sensor doesn't end up referencing itself.
263    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#checkForest")]
264    fn check_forest(&self, sensors: &mut HashSet<*const Sensor>) -> Result<(), Error> {
265        if !sensors.insert(self as *const Sensor) {
266            return Err(Error::local_illegal_argument(format!(
267                "Circular dependency in sensors: {} is its own parent.",
268                self.name()
269            )));
270        }
271        for parent in &self.parents {
272            parent.check_forest(sensors)?;
273        }
274        Ok(())
275    }
276
277    /// Returns the name this sensor is registered with. This name will be unique
278    /// among all registered sensors.
279    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#name")]
280    pub fn name(&self) -> &str {
281        &self.name
282    }
283
284    /// The parents of this sensor.
285    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#parents")]
286    pub(crate) fn parents(&self) -> &[Arc<Sensor>] {
287        &self.parents
288    }
289
290    /// Returns true if the sensor's record level indicates that the metric will
291    /// be recorded, false otherwise.
292    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#shouldRecord")]
293    pub fn should_record(&self) -> bool {
294        self.recording_level.should_record(self.config.record_level().id())
295    }
296
297    // Java's `record` overloads have an EMPTY parameter-name intersection, and
298    // the no-arg `record()` matches it, so that one keeps the plain name and the
299    // others carry their Rust parameters.
300
301    /// Record an occurrence, this is just short-hand for `record_with_value(1.0)`.
302    ///
303    /// # Errors
304    ///
305    /// - `Error::is_quota_violation_error` if recording moves a metric beyond its
306    ///   configured maximum or minimum bound
307    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#record")]
308    pub fn record(&self) -> Result<(), Error> {
309        if self.should_record() {
310            self.record_internal(1.0, self.time.milliseconds(), true)?;
311        }
312        Ok(())
313    }
314
315    /// Record a value with this sensor
316    ///
317    /// # Arguments
318    ///
319    /// - `value` - The value to record
320    ///
321    /// # Errors
322    ///
323    /// - `Error::is_quota_violation_error` if recording this value moves a metric
324    ///   beyond its configured maximum or minimum bound
325    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#record")]
326    pub fn record_with_value(&self, value: f64) -> Result<(), Error> {
327        if self.should_record() {
328            self.record_internal(value, self.time.milliseconds(), true)?;
329        }
330        Ok(())
331    }
332
333    /// Record a value at a known time. This method is slightly faster than
334    /// `record_with_value` since it will reuse the time stamp.
335    ///
336    /// # Arguments
337    ///
338    /// - `value` - The value we are recording
339    /// - `time_ms` - The current POSIX time in milliseconds
340    ///
341    /// # Errors
342    ///
343    /// - `Error::is_quota_violation_error` if recording this value moves a metric
344    ///   beyond its configured maximum or minimum bound
345    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#record")]
346    pub fn record_with_value_time_ms(&self, value: f64, time_ms: i64) -> Result<(), Error> {
347        if self.should_record() {
348            self.record_internal(value, time_ms, true)?;
349        }
350        Ok(())
351    }
352
353    /// Record a value at a known time. This method is slightly faster than
354    /// `record_with_value` since it will reuse the time stamp.
355    ///
356    /// # Arguments
357    ///
358    /// - `value` - The value we are recording
359    /// - `time_ms` - The current POSIX time in milliseconds
360    /// - `check_quotas` - Indicate if quota must be enforced or not
361    ///
362    /// # Errors
363    ///
364    /// - `Error::is_quota_violation_error` if recording this value moves a metric
365    ///   beyond its configured maximum or minimum bound
366    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#record")]
367    pub fn record_with_value_time_ms_check_quotas(
368        &self,
369        value: f64,
370        time_ms: i64,
371        check_quotas: bool,
372    ) -> Result<(), Error> {
373        if self.should_record() {
374            self.record_internal(value, time_ms, check_quotas)?;
375        }
376        Ok(())
377    }
378
379    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#recordInternal")]
380    fn record_internal(&self, value: f64, time_ms: i64, check_quotas: bool) -> Result<(), Error> {
381        self.last_record_time.store(time_ms, Ordering::SeqCst);
382        {
383            let inner = self.inner.lock().expect("sensor mutex poisoned");
384            // Increment all the stats.
385            for stat_and_config in &inner.stats {
386                stat_and_config.record(value, time_ms);
387            }
388        }
389        if check_quotas {
390            self.check_quotas_with_time_ms(time_ms)?;
391        }
392        for parent in &self.parents {
393            parent.record_with_value_time_ms_check_quotas(value, time_ms, check_quotas)?;
394        }
395        Ok(())
396    }
397
398    /// Check if we have violated our quota for any metric that has a configured
399    /// quota
400    ///
401    /// # Errors
402    ///
403    /// - `Error::is_quota_violation_error` if a metric's value is outside its quota
404    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#checkQuotas")]
405    pub fn check_quotas(&self) -> Result<(), Error> {
406        self.check_quotas_with_time_ms(self.time.milliseconds())
407    }
408
409    /// Check if we have violated our quota for any metric that has a configured
410    /// quota, as of `time_ms`.
411    ///
412    /// # Arguments
413    ///
414    /// - `time_ms` - the POSIX time in milliseconds to measure the metrics at
415    ///
416    /// # Errors
417    ///
418    /// - `Error::is_quota_violation_error` if a metric's value is outside its quota
419    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#checkQuotas")]
420    // Java guards on `config != null`; a Rust `MetricConfig` is always present,
421    // so only the `quota != null` guard survives as `Option<Quota>`. Java also
422    // special-cases `metric.measurable() instanceof TokenBucket`, treating any
423    // negative value as a violation; `TokenBucket` is not translated, so no
424    // metric can take that branch. It must be restored together with it.
425    pub fn check_quotas_with_time_ms(&self, time_ms: i64) -> Result<(), Error> {
426        // The metrics are cloned out of the guard rather than measured under it:
427        // `measurable_value` calls into user-supplied `Measurable` code, and
428        // holding the sensor lock across that would let a measurable that
429        // re-enters the sensor deadlock. Java has the same call under
430        // `synchronized (this)` but its monitor is reentrant.
431        // Only the metrics with a quota are collected, so the common case (no
432        // quota anywhere, as for every client sensor) collects nothing and does
433        // not allocate on the per-record path `record` calls this from.
434        let metrics: Vec<(Arc<KafkaMetric>, Quota)> = {
435            let inner = self.inner.lock().expect("sensor mutex poisoned");
436            inner
437                .metrics
438                .values()
439                .filter_map(|metric| metric.config().quota().map(|quota| (Arc::clone(metric), quota.clone())))
440                .collect()
441        };
442        for (metric, quota) in metrics {
443            let value = metric.measurable_value(time_ms);
444            if !quota.acceptable(value) {
445                return Err(Error::QuotaViolation(Box::new(QuotaViolationError::new(
446                    metric.metric_name().clone(),
447                    value,
448                    quota.bound(),
449                ))));
450            }
451        }
452        Ok(())
453    }
454
455    // Java's four `add` overloads all name their statistic parameter `stat`, so
456    // the parameter-name intersection is `{stat}`, and the overload whose
457    // parameters are exactly that is the COMPOUND form `add(CompoundStat stat)`.
458    // So the compound form keeps the plain name `add` and the metric-name forms
459    // are suffixed with their Rust parameters beyond the intersection. The two families differ
460    // in type as well as arity, but the derived names are already distinct, so
461    // §2's type tie-break does not fire.
462
463    /// Register a metric with this sensor
464    ///
465    /// # Arguments
466    ///
467    /// - `metric_name` - The name of the metric
468    /// - `stat` - The statistic to keep
469    ///
470    /// # Returns
471    ///
472    /// true if metric is added to sensor, false if sensor is expired
473    ///
474    /// # Errors
475    ///
476    /// - `Error::is_local_illegal_argument_error` if a metric of the same name is
477    ///   already registered in the registry by another sensor
478    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#add")]
479    pub fn add_with_metric_name(&self, metric_name: MetricName, stat: Box<dyn MeasurableStat>) -> Result<bool, Error> {
480        self.add_with_metric_name_config(metric_name, stat, None)
481    }
482
483    /// Register a metric with this sensor
484    ///
485    /// # Arguments
486    ///
487    /// - `metric_name` - The name of the metric
488    /// - `stat` - The statistic to keep
489    /// - `config` - A special configuration for this metric. If None use the sensor default
490    ///   configuration.
491    ///
492    /// # Returns
493    ///
494    /// true if metric is added to sensor, false if sensor is expired
495    ///
496    /// # Errors
497    ///
498    /// - `Error::is_local_illegal_argument_error` if a metric of the same name is
499    ///   already registered in the registry by another sensor
500    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#add")]
501    pub fn add_with_metric_name_config(
502        &self,
503        metric_name: MetricName,
504        stat: Box<dyn MeasurableStat>,
505        config: Option<Arc<MetricConfig>>,
506    ) -> Result<bool, Error> {
507        if self.has_expired() {
508            return Ok(false);
509        }
510        let mut inner = self.inner.lock().expect("sensor mutex poisoned");
511        if inner.metrics.contains_key(&metric_name) {
512            return Ok(true);
513        }
514        let stat_config = config.unwrap_or_else(|| Arc::clone(&self.config));
515
516        // A `MeasurableStat` is both `Stat` and `Measurable`. We need the stat
517        // both as a value provider (Measurable) for the KafkaMetric and as a
518        // recordable Stat for the sensor; they must be the SAME object so a
519        // record is reflected in the measured value. We hold it behind an `Arc`
520        // and expose both views.
521        let stat: Arc<dyn MeasurableStat> = Arc::from(stat);
522        let measurable_view: Arc<dyn Measurable> = Arc::clone(&stat) as Arc<dyn Measurable>;
523        let metric = Arc::new(KafkaMetric::new(
524            metric_name.clone(),
525            Box::new(MeasurableArc(measurable_view)),
526            Arc::clone(&stat_config),
527            Arc::clone(&self.time),
528        ));
529
530        if let Some(registry) = self.registry.as_ref().and_then(Weak::upgrade) {
531            let existing = registry.register_metric(Arc::clone(&metric));
532            if existing.is_some() {
533                return Err(Error::local_illegal_argument(format!(
534                    "A metric named '{metric_name}' already exists, can't register another one."
535                )));
536            }
537        }
538        inner.metrics.insert(metric_name, Arc::clone(&metric));
539        inner
540            .stats
541            .push(StatAndConfig { stat: Box::new(StatArc(stat)), config: StatConfigSource::FromMetric(metric) });
542        Ok(true)
543    }
544
545    /// Register a compound statistic with this sensor with no config override
546    ///
547    /// # Arguments
548    ///
549    /// - `stat` - The stat to register
550    ///
551    /// # Returns
552    ///
553    /// true if stat is added to sensor, false if sensor is expired
554    ///
555    /// # Errors
556    ///
557    /// - `Error::is_local_illegal_argument_error` if a metric of the same name is
558    ///   already registered in the registry by another sensor
559    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#add")]
560    pub fn add(&self, stat: Box<dyn CompoundStat>) -> Result<bool, Error> {
561        self.add_with_config(stat, None)
562    }
563
564    /// Register a compound statistic with this sensor which yields multiple
565    /// measurable quantities (like a histogram)
566    ///
567    /// # Arguments
568    ///
569    /// - `stat` - The stat to register
570    /// - `config` - The configuration for this stat. If None then the stat will use the default
571    ///   configuration for this sensor.
572    ///
573    /// # Returns
574    ///
575    /// true if stat is added to sensor, false if sensor is expired
576    ///
577    /// # Errors
578    ///
579    /// - `Error::is_local_illegal_argument_error` if a metric of the same name is
580    ///   already registered in the registry by another sensor
581    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#add")]
582    // The compound stat is recorded once per `record`; each `NamedMeasurable`
583    // child gets its own `KafkaMetric` reading the (constant) `statConfig`, and
584    // shares state with the compound stat.
585    pub fn add_with_config(
586        &self,
587        stat: Box<dyn CompoundStat>,
588        config: Option<Arc<MetricConfig>>,
589    ) -> Result<bool, Error> {
590        if self.has_expired() {
591            return Ok(false);
592        }
593        let mut inner = self.inner.lock().expect("sensor mutex poisoned");
594        let stat_config = config.unwrap_or_else(|| Arc::clone(&self.config));
595
596        // Snapshot the child measurables before moving the compound stat into the
597        // recordable stats list.
598        let children = stat.stats();
599
600        inner.stats.push(StatAndConfig {
601            stat: Box::new(CompoundStatBox(stat)),
602            config: StatConfigSource::Constant(Arc::clone(&stat_config)),
603        });
604
605        for child in children {
606            let metric = Arc::new(KafkaMetric::new(
607                child.name().clone(),
608                Box::new(MeasurableArc(child.stat())),
609                Arc::clone(&stat_config),
610                Arc::clone(&self.time),
611            ));
612            if !inner.metrics.contains_key(child.name()) {
613                if let Some(registry) = self.registry.as_ref().and_then(Weak::upgrade) {
614                    let existing = registry.register_metric(Arc::clone(&metric));
615                    if existing.is_some() {
616                        return Err(Error::local_illegal_argument(format!(
617                            "A metric named '{}' already exists, can't register another one.",
618                            child.name()
619                        )));
620                    }
621                }
622                inner.metrics.insert(child.name().clone(), metric);
623            }
624        }
625        Ok(true)
626    }
627
628    /// Return if metrics were registered with this sensor.
629    ///
630    /// # Returns
631    ///
632    /// true if metrics were registered, false otherwise
633    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#hasMetrics")]
634    pub fn has_metrics(&self) -> bool {
635        !self.inner.lock().expect("sensor mutex poisoned").metrics.is_empty()
636    }
637
638    /// Returns true if the sensor is eligible for removal due to inactivity.
639    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#hasExpired")]
640    pub fn has_expired(&self) -> bool {
641        (self.time.milliseconds() - self.last_record_time.load(Ordering::SeqCst))
642            > self.inactive_sensor_expiration_time_ms
643    }
644
645    /// The metrics registered with this sensor.
646    #[doc(alias = "org.apache.kafka.common.metrics.Sensor#metrics")]
647    pub(crate) fn metrics(&self) -> Vec<Arc<KafkaMetric>> {
648        self.inner
649            .lock()
650            .expect("sensor mutex poisoned")
651            .metrics
652            .values()
653            .cloned()
654            .collect()
655    }
656}
657
658/// A `Stat` view over an `Arc<dyn MeasurableStat>`, so the recordable stat and
659/// the metric's value provider share the same underlying object.
660struct StatArc(Arc<dyn MeasurableStat>);
661
662impl Stat for StatArc {
663    fn record(&self, config: &MetricConfig, value: f64, time_ms: i64) {
664        self.0.record(config, value, time_ms);
665    }
666}
667
668/// A `Measurable` view over a shared `Arc<dyn Measurable>` (used both for the
669/// `MeasurableStat` `add` path and the `CompoundStat` child measurables).
670struct MeasurableArc(Arc<dyn Measurable>);
671
672impl Measurable for MeasurableArc {
673    fn measure(&self, config: &MetricConfig, now: i64) -> f64 {
674        self.0.measure(config, now)
675    }
676
677    /// The shared stat's own type: Java registers the stat itself as the
678    /// metric's provider, so its class is what `KafkaMetric.toString` names.
679    fn type_name(&self) -> Option<&'static str> {
680        self.0.type_name()
681    }
682}
683
684/// A `Stat` view over a `Box<dyn CompoundStat>` so the compound stat can sit in
685/// the sensor's recordable stats list.
686struct CompoundStatBox(Box<dyn CompoundStat>);
687
688impl Stat for CompoundStatBox {
689    fn record(&self, config: &MetricConfig, value: f64, time_ms: i64) {
690        self.0.record(config, value, time_ms);
691    }
692}
693
694/// Logs the error a client's own `record` call returns, instead of passing it on.
695///
696/// The client builds its sensors without a quota, but `KafkaMetric::set_config` can add one, and
697/// then `record` reports the violation. Java's I/O tasks log what a sensor throws
698/// (`org.apache.kafka.clients.producer.internals.Sender#run`,
699/// `org.apache.kafka.clients.consumer.internals.ConsumerNetworkThread#run`); here the operation
700/// the metric measures then carries on.
701pub(crate) fn record_or_log(result: Result<(), Error>) {
702    if let Err(error) = result {
703        log::error!("Recording a client metric failed: {error}");
704    }
705}
706
707#[cfg(test)]
708mod tests {
709    use super::*;
710    use crate::common::metrics::Quota;
711    use crate::common::metrics::stats::{CumulativeCount, Value};
712    use crate::common::protocol::Errors;
713    use crate::common::utils::MockTime;
714    use crate::common::utils::SystemTime;
715    use std::collections::BTreeMap;
716
717    fn level_id(level: RecordingLevel) -> i16 {
718        level.id()
719    }
720
721    fn info_config() -> Arc<MetricConfig> {
722        Arc::new(MetricConfig::new().set_record_level(RecordingLevel::Info))
723    }
724    fn debug_config() -> Arc<MetricConfig> {
725        Arc::new(MetricConfig::new().set_record_level(RecordingLevel::Debug))
726    }
727    fn trace_config() -> Arc<MetricConfig> {
728        Arc::new(MetricConfig::new().set_record_level(RecordingLevel::Trace))
729    }
730
731    fn standalone(config: Arc<MetricConfig>, expiration_secs: i64, level: RecordingLevel) -> Sensor {
732        Sensor::new(None, "sensor", Vec::new(), config, Arc::new(SystemTime), expiration_secs, level).unwrap()
733    }
734
735    fn name(n: &str, g: &str) -> MetricName {
736        MetricName::new(n, g, "", BTreeMap::new())
737    }
738
739    fn quota_config(quota: Quota) -> Arc<MetricConfig> {
740        Arc::new(MetricConfig::new().set_quota(quota).set_record_level(RecordingLevel::Info))
741    }
742
743    /// The check itself, recording with `check_quotas = false` as Java's
744    /// `SensorTest.strictRecord` does and then calling `check_quotas`.
745    ///
746    /// An upper bound is crossed once the recorded value exceeds it, and the
747    /// error carries the metric, the offending value and the bound — Java's
748    /// three `QuotaViolationException` fields.
749    /// New test, no Java original: a quota violation a client's own `record` reports is
750    /// logged at error level, as Java's I/O tasks log what they catch, and an `Ok` logs nothing.
751    #[test]
752    fn record_or_log_logs_the_violation() {
753        let sensor = standalone(quota_config(Quota::upper_bound(5.0)), 60, RecordingLevel::Info);
754        assert!(
755            sensor
756                .add_with_metric_name(name("value", "test-group"), Box::new(Value::new()))
757                .unwrap()
758        );
759        let ((), lines) = crate::test_log_capture::capture_logs(|| {
760            record_or_log(sensor.record_with_value_time_ms(4.0, 1));
761            record_or_log(sensor.record_with_value_time_ms(10.0, 2));
762        });
763        let errors: Vec<_> = lines.into_iter().filter(|(level, _)| *level == log::Level::Error).collect();
764        assert_eq!(errors.len(), 1, "{errors:?}");
765        assert!(
766            errors[0]
767                .1
768                .starts_with("Recording a client metric failed: QuotaViolationError: "),
769            "{}",
770            errors[0].1
771        );
772        assert!(errors[0].1.ends_with("Actual: 10.0, Threshold: 5.0"), "{}", errors[0].1);
773    }
774
775    #[test]
776    fn test_check_quotas_reports_an_upper_bound_violation() {
777        let sensor = standalone(quota_config(Quota::upper_bound(5.0)), 60, RecordingLevel::Info);
778        let metric_name = name("value", "test-group");
779        assert!(
780            sensor
781                .add_with_metric_name(metric_name.clone(), Box::new(Value::new()))
782                .unwrap()
783        );
784
785        // Under the bound: no violation, in either accessor.
786        sensor.record_with_value_time_ms(4.0, 1).unwrap();
787        assert!(sensor.check_quotas_with_time_ms(1).is_ok());
788        assert!(sensor.check_quotas().is_ok());
789
790        // Over it: Java throws `QuotaViolationException(metric, value, bound)`.
791        sensor.record_with_value_time_ms_check_quotas(10.0, 2, false).unwrap();
792        let error = sensor
793            .check_quotas_with_time_ms(2)
794            .expect_err("10.0 exceeds the upper bound of 5.0");
795        let Error::QuotaViolation(violation) = &error else {
796            panic!("expected a quota violation, got {error:?}");
797        };
798        assert_eq!(violation.metric_name().name(), "value");
799        assert_eq!(violation.value(), 10.0);
800        assert_eq!(violation.bound(), 5.0);
801
802        // `QuotaViolationException extends KafkaException` and nothing else, so
803        // it is not an `ApiException` and carries no protocol code.
804        assert!(error.is_kafka_error());
805        assert!(!error.is_api_error());
806        assert!(!error.is_retriable_error());
807        assert_eq!(error.error(), Errors::UnknownServerError);
808        // Java's constructor calls the no-argument `super()`, so `getMessage()`
809        // is null; the descriptive text is in the `toString()` override.
810        assert_eq!(error.message(), "");
811        assert_eq!(
812            error.to_string(),
813            format!("QuotaViolationError: '{metric_name}' violated quota. Actual: 10.0, Threshold: 5.0")
814        );
815    }
816
817    /// A lower bound is crossed from the other side — Java's
818    /// `Quota.acceptable` is the whole test in `checkQuotas`, and a
819    /// lower-bound quota must not be read as an upper one.
820    #[test]
821    fn test_check_quotas_reports_a_lower_bound_violation() {
822        let sensor = standalone(quota_config(Quota::lower_bound(5.0)), 60, RecordingLevel::Info);
823        assert!(
824            sensor
825                .add_with_metric_name(name("value", "test-group"), Box::new(Value::new()))
826                .unwrap()
827        );
828
829        sensor.record_with_value_time_ms(10.0, 1).unwrap();
830        assert!(sensor.check_quotas_with_time_ms(1).is_ok());
831
832        sensor.record_with_value_time_ms_check_quotas(1.0, 2, false).unwrap();
833        let error = sensor
834            .check_quotas_with_time_ms(2)
835            .expect_err("1.0 is below the lower bound of 5.0");
836        let Error::QuotaViolation(violation) = &error else {
837            panic!("expected a quota violation, got {error:?}");
838        };
839        assert_eq!(violation.value(), 1.0);
840        assert_eq!(violation.bound(), 5.0);
841    }
842
843    /// Java's `record` checks the quotas after recording the stats and throws
844    /// on a violation, which stops the parents from recording: a child whose
845    /// quota is violated leaves its parent untouched, while
846    /// `check_quotas = false` records both.
847    #[test]
848    fn test_record_violation_does_not_record_the_parents() {
849        use crate::common::metrics::Metrics;
850        let metrics = Metrics::new();
851        let parent = metrics.sensor("parent").unwrap();
852        let parent_count = metrics.metric_name("parent.count", "grp1");
853        parent
854            .add_with_metric_name(parent_count.clone(), Box::new(CumulativeCount::new()))
855            .unwrap();
856        let child = metrics
857            .sensor_with_config_parents("child", Some(quota_config(Quota::upper_bound(5.0))), &[Arc::clone(&parent)])
858            .unwrap();
859        let child_value = metrics.metric_name("child.value", "grp1");
860        child.add_with_metric_name(child_value.clone(), Box::new(Value::new())).unwrap();
861        let value_of = |name: &MetricName| metrics.metric(name).unwrap().measurable_value(0);
862
863        child.record_with_value(1.0).unwrap();
864        assert_eq!(value_of(&parent_count), 1.0);
865
866        let error = child.record_with_value(10.0).expect_err("10.0 exceeds the upper bound of 5.0");
867        assert!(error.is_quota_violation_error());
868        assert_eq!(
869            error.to_string(),
870            format!("QuotaViolationError: '{child_value}' violated quota. Actual: 10.0, Threshold: 5.0")
871        );
872        // The child's stats are recorded before the check, the parent's are not.
873        assert_eq!(value_of(&child_value), 10.0);
874        assert_eq!(value_of(&parent_count), 1.0);
875
876        child.record_with_value_time_ms_check_quotas(10.0, 0, false).unwrap();
877        assert_eq!(value_of(&parent_count), 2.0);
878    }
879
880    /// `SensorTest.testStrictQuotaEnforcementWithRate`
881    #[test]
882    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testStrictQuotaEnforcementWithRate")]
883    fn test_strict_quota_enforcement_with_rate() {
884        use crate::common::metrics::stats::Rate;
885        use crate::common::metrics::{Metrics, TimeUnit};
886        let wall_clock_ms = SystemTime.milliseconds();
887        let time = Arc::new(MockTime::with_auto_tick_ms_current_time_ms_current_high_res_time_ns(
888            0,
889            wall_clock_ms,
890            0,
891        ));
892        let metrics = Metrics::with_time(Arc::clone(&time) as Arc<dyn Time>);
893        let config = MetricConfig::new()
894            .set_quota(Quota::upper_bound(2.0))
895            .set_time_window(1, TimeUnit::Seconds)
896            .set_samples(11);
897        let sensor = metrics
898            .sensor_with_config_parents("sensor", Some(Arc::new(config)), &[])
899            .unwrap();
900        let metric_name = metrics.metric_name("rate", "test-group");
901        assert!(sensor.add_with_metric_name(metric_name.clone(), Box::new(Rate::new())).unwrap());
902        let rate_metric = metrics.metric(&metric_name).unwrap();
903        let strict_record = |value: f64, time_ms: i64| -> Result<(), Error> {
904            sensor.check_quotas_with_time_ms(time_ms)?;
905            sensor.record_with_value_time_ms_check_quotas(value, time_ms, false)
906        };
907
908        // Recording a first value at T+0 to bring the avg rate to 3 which is already
909        // above the quota.
910        strict_record(30.0, time.milliseconds()).unwrap();
911        assert!((rate_metric.measurable_value(time.milliseconds()) - 3.0).abs() <= 0.1);
912
913        // Theoretically, we should wait 5s to bring back the avg rate to the define quota:
914        // ((30 / 10) - 2) / 2 * 10 = 5s
915        time.sleep(5000);
916
917        // But, recording a second value is rejected because the avg rate is still equal
918        // to 3 after 5s.
919        assert!((rate_metric.measurable_value(time.milliseconds()) - 3.0).abs() <= 0.1);
920        let error = strict_record(30.0, time.milliseconds()).expect_err("the rate is still above the quota");
921        assert!(error.is_quota_violation_error());
922    }
923
924    /// A `MeasurableStat` that logs the quota bound of the config each call
925    /// receives: Java's `Mockito.verify(stat).record(config, ..)` /
926    /// `.measure(config, ..)`.
927    struct RecordingStat(Arc<Mutex<Vec<StatCall>>>);
928
929    /// One call a `RecordingStat` received: method, quota bound, value, time.
930    type StatCall = (&'static str, f64, f64, i64);
931
932    impl Stat for RecordingStat {
933        fn record(&self, config: &MetricConfig, value: f64, time_ms: i64) {
934            let bound = config.quota().map_or(f64::NAN, Quota::bound);
935            self.0.lock().unwrap().push(("record", bound, value, time_ms));
936        }
937    }
938
939    impl Measurable for RecordingStat {
940        fn measure(&self, config: &MetricConfig, now: i64) -> f64 {
941            let bound = config.quota().map_or(f64::NAN, Quota::bound);
942            self.0.lock().unwrap().push(("measure", bound, 0.0, now));
943            0.0
944        }
945    }
946
947    /// `SensorTest.testRecordAndCheckQuotaUseMetricConfigOfEachStat`
948    #[test]
949    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testRecordAndCheckQuotaUseMetricConfigOfEachStat")]
950    fn test_record_and_check_quota_use_metric_config_of_each_stat() {
951        use crate::common::metrics::Metrics;
952        let metrics = Metrics::with_time(Arc::new(MockTime::new()));
953        let sensor = metrics.sensor("sensor").unwrap();
954
955        let calls1 = Arc::new(Mutex::new(Vec::new()));
956        let stat1_config = Arc::new(MetricConfig::new().set_quota(Quota::upper_bound(5.0)));
957        sensor
958            .add_with_metric_name_config(
959                metrics.metric_name("stat1", "test-group"),
960                Box::new(RecordingStat(Arc::clone(&calls1))),
961                Some(stat1_config),
962            )
963            .unwrap();
964        let calls2 = Arc::new(Mutex::new(Vec::new()));
965        let stat2_config = Arc::new(MetricConfig::new().set_quota(Quota::upper_bound(10.0)));
966        sensor
967            .add_with_metric_name_config(
968                metrics.metric_name("stat2", "test-group"),
969                Box::new(RecordingStat(Arc::clone(&calls2))),
970                Some(stat2_config),
971            )
972            .unwrap();
973
974        sensor.record_with_value_time_ms(10.0, 1).unwrap();
975        assert!(calls1.lock().unwrap().contains(&("record", 5.0, 10.0, 1)));
976        assert!(calls2.lock().unwrap().contains(&("record", 10.0, 10.0, 1)));
977
978        sensor.check_quotas_with_time_ms(2).unwrap();
979        assert!(calls1.lock().unwrap().contains(&("measure", 5.0, 0.0, 2)));
980        assert!(calls2.lock().unwrap().contains(&("measure", 10.0, 0.0, 2)));
981    }
982
983    /// `SensorTest.testUpdatingMetricConfigIsReflectedInTheSensor`
984    #[test]
985    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testUpdatingMetricConfigIsReflectedInTheSensor")]
986    fn test_updating_metric_config_is_reflected_in_the_sensor() {
987        use crate::common::metrics::Metrics;
988        let metrics = Metrics::with_time(Arc::new(MockTime::new()));
989        let sensor = metrics.sensor("sensor").unwrap();
990
991        let calls = Arc::new(Mutex::new(Vec::new()));
992        let stat_name = metrics.metric_name("stat", "test-group");
993        let stat_config = Arc::new(MetricConfig::new().set_quota(Quota::upper_bound(5.0)));
994        sensor
995            .add_with_metric_name_config(
996                stat_name.clone(),
997                Box::new(RecordingStat(Arc::clone(&calls))),
998                Some(stat_config),
999            )
1000            .unwrap();
1001
1002        sensor.record_with_value_time_ms(10.0, 1).unwrap();
1003        assert!(calls.lock().unwrap().contains(&("record", 5.0, 10.0, 1)));
1004
1005        sensor.check_quotas_with_time_ms(2).unwrap();
1006        assert!(calls.lock().unwrap().contains(&("measure", 5.0, 0.0, 2)));
1007
1008        // Update the config of the KafkaMetric
1009        let new_config = Arc::new(MetricConfig::new().set_quota(Quota::upper_bound(10.0)));
1010        metrics.metric(&stat_name).unwrap().set_config(new_config);
1011
1012        sensor.record_with_value_time_ms(10.0, 3).unwrap();
1013        assert!(calls.lock().unwrap().contains(&("record", 10.0, 10.0, 3)));
1014
1015        sensor.check_quotas_with_time_ms(4).unwrap();
1016        assert!(calls.lock().unwrap().contains(&("measure", 10.0, 0.0, 4)));
1017    }
1018
1019    /// A sensor whose config carries no quota can never violate one, however
1020    /// much is recorded — Java's `if (quota != null)` guard.
1021    #[test]
1022    fn test_check_quotas_is_a_no_op_without_a_quota() {
1023        let sensor = standalone(info_config(), 60, RecordingLevel::Info);
1024        assert!(
1025            sensor
1026                .add_with_metric_name(name("value", "test-group"), Box::new(Value::new()))
1027                .unwrap()
1028        );
1029        sensor.record_with_value_time_ms(f64::MAX, 1).unwrap();
1030        assert!(sensor.check_quotas_with_time_ms(1).is_ok());
1031        assert!(sensor.check_quotas().is_ok());
1032    }
1033
1034    /// `SensorTest.testCheckQuotasInMultiThreads`: `check_quotas` is called from
1035    /// many tasks at once (Java's ReplicaFetcherThreads) and must neither
1036    /// deadlock nor report a violation for an upper bound of `f64::MAX`.
1037    #[test]
1038    fn test_check_quotas_in_multiple_threads() {
1039        let sensor = Arc::new(standalone(quota_config(Quota::upper_bound(f64::MAX)), 60, RecordingLevel::Info));
1040        assert!(
1041            sensor
1042                .add_with_metric_name(name("test-metric", "test-group"), Box::new(Value::new()))
1043                .unwrap()
1044        );
1045
1046        let mut handles = Vec::new();
1047        for index in 0..10i64 {
1048            let sensor = Arc::clone(&sensor);
1049            handles.push(std::thread::spawn(move || {
1050                for j in 0..20i64 {
1051                    sensor
1052                        .record_with_value_time_ms_check_quotas((j * index) as f64, j, false)
1053                        .unwrap();
1054                    sensor.check_quotas().expect("an upper bound of f64::MAX is never violated");
1055                }
1056            }));
1057        }
1058        for handle in handles {
1059            handle.join().expect("check_quotas must be safe to call from many tasks");
1060        }
1061    }
1062
1063    // SensorTest.testRecordLevelEnum
1064    #[test]
1065    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testRecordLevelEnum")]
1066    fn test_record_level_enum() {
1067        let config_level = RecordingLevel::Info;
1068        assert!(RecordingLevel::Info.should_record(level_id(config_level)));
1069        assert!(!RecordingLevel::Debug.should_record(level_id(config_level)));
1070        assert!(!RecordingLevel::Trace.should_record(level_id(config_level)));
1071
1072        let config_level = RecordingLevel::Debug;
1073        assert!(RecordingLevel::Info.should_record(level_id(config_level)));
1074        assert!(RecordingLevel::Debug.should_record(level_id(config_level)));
1075        assert!(!RecordingLevel::Trace.should_record(level_id(config_level)));
1076
1077        let config_level = RecordingLevel::Trace;
1078        assert!(RecordingLevel::Info.should_record(level_id(config_level)));
1079        assert!(RecordingLevel::Debug.should_record(level_id(config_level)));
1080        assert!(RecordingLevel::Trace.should_record(level_id(config_level)));
1081
1082        assert_eq!(
1083            RecordingLevel::Debug,
1084            RecordingLevel::for_name(RecordingLevel::Debug.name()).unwrap()
1085        );
1086        assert_eq!(
1087            RecordingLevel::Info,
1088            RecordingLevel::for_name(RecordingLevel::Info.name()).unwrap()
1089        );
1090        assert_eq!(
1091            RecordingLevel::Trace,
1092            RecordingLevel::for_name(RecordingLevel::Trace.name()).unwrap()
1093        );
1094    }
1095
1096    // SensorTest.testShouldRecordForInfoLevelSensor
1097    #[test]
1098    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testShouldRecordForInfoLevelSensor")]
1099    fn test_should_record_for_info_level_sensor() {
1100        assert!(standalone(info_config(), 0, RecordingLevel::Info).should_record());
1101        assert!(standalone(debug_config(), 0, RecordingLevel::Info).should_record());
1102        assert!(standalone(trace_config(), 0, RecordingLevel::Info).should_record());
1103    }
1104
1105    // SensorTest.testShouldRecordForDebugLevelSensor
1106    #[test]
1107    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testShouldRecordForDebugLevelSensor")]
1108    fn test_should_record_for_debug_level_sensor() {
1109        assert!(!standalone(info_config(), 0, RecordingLevel::Debug).should_record());
1110        assert!(standalone(debug_config(), 0, RecordingLevel::Debug).should_record());
1111        assert!(standalone(trace_config(), 0, RecordingLevel::Debug).should_record());
1112    }
1113
1114    // SensorTest.testShouldRecordForTraceLevelSensor
1115    #[test]
1116    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testShouldRecordForTraceLevelSensor")]
1117    fn test_should_record_for_trace_level_sensor() {
1118        assert!(!standalone(info_config(), 0, RecordingLevel::Trace).should_record());
1119        assert!(!standalone(debug_config(), 0, RecordingLevel::Trace).should_record());
1120        assert!(standalone(trace_config(), 0, RecordingLevel::Trace).should_record());
1121    }
1122
1123    // SensorTest.shouldReturnPresenceOfMetrics (standalone-sensor part)
1124    #[test]
1125    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#shouldReturnPresenceOfMetrics")]
1126    fn should_return_presence_of_metrics() {
1127        let sensor = standalone(Arc::new(MetricConfig::new()), i64::MAX, RecordingLevel::Info);
1128        assert!(!sensor.has_metrics());
1129        sensor
1130            .add_with_metric_name(name("name1", "group1"), Box::new(CumulativeCount::new()))
1131            .unwrap();
1132        assert!(sensor.has_metrics());
1133        sensor
1134            .add_with_metric_name(name("name2", "group2"), Box::new(Value::new()))
1135            .unwrap();
1136        assert!(sensor.has_metrics());
1137    }
1138
1139    // SensorTest.testExpiredSensor
1140    //
1141    // Java uses `Avg`/`Meter` (M2 stats) as the *thing being added*, but the
1142    // behavioral assertion is purely on the boolean returned by `add` — which is
1143    // the same for any `MeasurableStat`. We substitute the M1 stats
1144    // `CumulativeCount` / `Value` (the same substitution principle already
1145    // applied to `testIdempotentAdd` / `testSimpleStats`). The Java test uses a
1146    // `Metrics`-backed sensor; here we use a standalone sensor (registry `None`)
1147    // driven by `MockTime`, which exercises the identical `has_expired()` /
1148    // `add`-returns-`false` path without needing the registry.
1149    #[test]
1150    #[doc(alias = "org.apache.kafka.common.metrics.SensorTest#testExpiredSensor")]
1151    fn test_expired_sensor() {
1152        let time = Arc::new(MockTime::new());
1153        let inactive_sensor_expiration_time_seconds = 60i64;
1154        let sensor = Sensor::new(
1155            None,
1156            "sensor",
1157            Vec::new(),
1158            Arc::new(MetricConfig::new()),
1159            Arc::clone(&time) as Arc<dyn Time>,
1160            inactive_sensor_expiration_time_seconds,
1161            RecordingLevel::Info,
1162        )
1163        .unwrap();
1164
1165        // Before expiry, adds succeed.
1166        assert!(
1167            sensor
1168                .add_with_metric_name(name("test1", "grp1"), Box::new(CumulativeCount::new()))
1169                .unwrap()
1170        );
1171        assert!(
1172            sensor
1173                .add_with_metric_name(name("test2", "grp1"), Box::new(Value::new()))
1174                .unwrap()
1175        );
1176        assert_eq!(2, sensor.metrics().len());
1177        assert!(!sensor.has_expired());
1178
1179        // Advance past the inactivity window.
1180        time.sleep((inactive_sensor_expiration_time_seconds + 1) * 1000);
1181        assert!(sensor.has_expired());
1182
1183        // Adds to an expired sensor are a no-op returning `false`; the metric is
1184        // NOT registered (count unchanged).
1185        assert!(
1186            !sensor
1187                .add_with_metric_name(name("test3", "grp1"), Box::new(CumulativeCount::new()))
1188                .unwrap()
1189        );
1190        assert!(
1191            !sensor
1192                .add_with_metric_name_config(name("test4", "grp1"), Box::new(Value::new()), None)
1193                .unwrap()
1194        );
1195        assert_eq!(2, sensor.metrics().len());
1196
1197        // Java's `record` does not gate on expiry; recording resets
1198        // `last_record_time`, so the sensor is no longer expired afterwards and
1199        // the metric count remains unchanged.
1200        sensor.record_with_value(1.0).unwrap();
1201        assert!(!sensor.has_expired());
1202        assert_eq!(2, sensor.metrics().len());
1203    }
1204
1205    // ---------------------------------------------------------------------
1206    // Milestone-9 Phase M8 — pure in-process micro-bench (no broker needed).
1207    //
1208    // Quantifies the per-call cost of `Sensor::record_with_value_time_ms` on a realistic
1209    // fetch-shaped sensor (a `Meter` = Rate + CumulativeSum, plus `Avg` +
1210    // `Max` — the stat shape used by `bytes-fetched` / `fetch-latency` and
1211    // friends). This is the unit of cost that the consumer pays PER FETCH /
1212    // PER PARTITION (never per record — see
1213    // `completed_fetch::tests::test_per_record_loop_is_pure_counter_no_sensor_record`).
1214    //
1215    // Marked `#[ignore]` so it does not run in CI (timing is environment
1216    // dependent), but it BUILDS in CI and is runnable on demand:
1217    //
1218    //     cargo test --lib bench_sensor_record_ns -- --ignored --nocapture
1219    //
1220    // The printed ns/call, multiplied by the per-fetch/per-partition record
1221    // frequency in `design/current/consumer-metrics-perf-analysis.md`, gives
1222    // the metrics-on overhead per poll cycle without needing a broker.
1223    #[test]
1224    #[ignore = "micro-bench; run with --ignored --nocapture"]
1225    fn bench_sensor_record_ns() {
1226        use crate::common::metrics::stats::{Avg, Max, Meter};
1227        use std::time::Instant;
1228
1229        let time = Arc::new(MockTime::new());
1230        let sensor = Sensor::new(
1231            None,
1232            "bench",
1233            Vec::new(),
1234            info_config(),
1235            Arc::clone(&time) as Arc<dyn Time>,
1236            i64::MAX,
1237            RecordingLevel::Info,
1238        )
1239        .unwrap();
1240        // Realistic fetch-sensor stat shape: a Meter (rate + total) + Avg + Max.
1241        sensor.add(Box::new(Meter::new(name("rate", "g"), name("total", "g")))).unwrap();
1242        sensor.add_with_metric_name(name("avg", "g"), Box::new(Avg::new())).unwrap();
1243        sensor.add_with_metric_name(name("max", "g"), Box::new(Max::new())).unwrap();
1244
1245        // Warm up (JIT-free, but warms caches / branch predictors and forces
1246        // the first sample-buffer allocation outside the timed loop).
1247        let mut now = time.milliseconds();
1248        for i in 0..10_000 {
1249            sensor.record_with_value_time_ms(i as f64, now).unwrap();
1250        }
1251
1252        const ITERS: u64 = 2_000_000;
1253        let start = Instant::now();
1254        for i in 0..ITERS {
1255            // Advance the mock clock occasionally so window rollover is
1256            // exercised the way a real fetch loop would (samples age out).
1257            if i % 4096 == 0 {
1258                now += 1;
1259            }
1260            sensor.record_with_value_time_ms(i as f64, now).unwrap();
1261        }
1262        let elapsed = start.elapsed();
1263        let ns_per_call = elapsed.as_nanos() as f64 / ITERS as f64;
1264        eprintln!(
1265            "M8 micro-bench: Sensor::record_with_value_time_ms over Meter+Avg+Max = {ns_per_call:.1} ns/call \
1266             ({ITERS} iters in {elapsed:?})"
1267        );
1268        // Sanity floor: the work is non-trivial (mutex + 3 compound stats), so
1269        // a sub-nanosecond reading would mean the call was optimized away.
1270        assert!(ns_per_call > 0.0);
1271    }
1272}