confluent_kafka/common/metrics/compound_stat.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 compound stat that feeds many metrics from a single measurement
16//! (`org.apache.kafka.common.metrics.CompoundStat`).
17
18use std::sync::Arc;
19
20use crate::common::MetricName;
21use crate::common::metrics::{Measurable, Stat};
22
23/// A compound stat is a stat where a single measurement and associated data
24/// structure feeds many metrics. This is the example for a histogram which has
25/// many associated percentiles.
26#[doc(alias = "org.apache.kafka.common.metrics.CompoundStat")]
27pub trait CompoundStat: Stat {
28 /// Returns the named measurable child metrics this compound stat exposes.
29 #[doc(alias = "org.apache.kafka.common.metrics.CompoundStat#stats")]
30 fn stats(&self) -> Vec<NamedMeasurable>;
31}
32
33/// A named [`Measurable`] child of a [`CompoundStat`].
34///
35/// Mirrors `CompoundStat.NamedMeasurable`. The `stat` is shared (`Arc`) because
36/// the compound stat records into the same object the child metric measures, so
37/// a record must be reflected in the measured value.
38#[derive(Clone)]
39#[doc(alias = "org.apache.kafka.common.metrics.CompoundStat$NamedMeasurable")]
40pub struct NamedMeasurable {
41 name: MetricName,
42 stat: Arc<dyn Measurable>,
43}
44
45impl std::fmt::Debug for NamedMeasurable {
46 // The name only; the stat is a trait object.
47 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
48 f.debug_struct("NamedMeasurable")
49 .field("name", &self.name)
50 .finish_non_exhaustive()
51 }
52}
53
54impl NamedMeasurable {
55 /// Creates a `NamedMeasurable`.
56 ///
57 /// # Arguments
58 ///
59 /// - `name` - the metric name of this child
60 /// - `stat` - the measurable backing this child
61 #[doc(alias = "org.apache.kafka.common.metrics.CompoundStat$NamedMeasurable#NamedMeasurable")]
62 pub fn new(name: MetricName, stat: Arc<dyn Measurable>) -> Self {
63 Self { name, stat }
64 }
65
66 /// Returns the metric name of this child.
67 #[doc(alias = "org.apache.kafka.common.metrics.CompoundStat$NamedMeasurable#name")]
68 pub fn name(&self) -> &MetricName {
69 &self.name
70 }
71
72 /// Returns the measurable backing this child.
73 #[doc(alias = "org.apache.kafka.common.metrics.CompoundStat$NamedMeasurable#stat")]
74 pub fn stat(&self) -> Arc<dyn Measurable> {
75 Arc::clone(&self.stat)
76 }
77}