Skip to main content

kafka_client_engine/metrics/
error.rs

1//! Stable failures for operational-metrics admission and observation.
2
3use core::fmt;
4
5use crate::driver::owner::observation::{
6    DriverObservationAdmissionError, DriverObservationAdmissionErrorKind, DriverObservationError,
7    DriverObservationErrorKind,
8};
9use crate::producer::ingress::ProducerShardLockError;
10
11/// Stable category for a metrics request that never entered driver ownership.
12#[derive(Clone, Copy, Debug, Eq, PartialEq)]
13pub enum EngineMetricsAdmissionErrorKind {
14    /// A bounded metrics admission owner is temporarily full or contended.
15    Capacity,
16    /// Driver admission has closed permanently.
17    Closed,
18    /// A metrics owner was unavailable, could not be notified, or rejected an
19    /// impossible request category.
20    HostUnavailable,
21}
22
23/// Immediate failure to admit one operational-metrics snapshot.
24#[derive(Debug)]
25pub struct EngineMetricsAdmissionError {
26    kind: EngineMetricsAdmissionErrorKind,
27    source: EngineMetricsAdmissionSource,
28}
29
30impl EngineMetricsAdmissionError {
31    pub(crate) const fn from_driver(source: DriverObservationAdmissionError) -> Self {
32        let kind = match source.kind() {
33            DriverObservationAdmissionErrorKind::Capacity => {
34                EngineMetricsAdmissionErrorKind::Capacity
35            }
36            DriverObservationAdmissionErrorKind::Closed => EngineMetricsAdmissionErrorKind::Closed,
37            DriverObservationAdmissionErrorKind::HostUnavailable => {
38                EngineMetricsAdmissionErrorKind::HostUnavailable
39            }
40        };
41        Self {
42            kind,
43            source: EngineMetricsAdmissionSource::Driver(source),
44        }
45    }
46
47    pub(crate) const fn from_producer(source: ProducerShardLockError) -> Self {
48        let (kind, source) = match source {
49            ProducerShardLockError::Contended => (
50                EngineMetricsAdmissionErrorKind::Capacity,
51                EngineMetricsAdmissionSource::ProducerContended,
52            ),
53            ProducerShardLockError::Poisoned => (
54                EngineMetricsAdmissionErrorKind::HostUnavailable,
55                EngineMetricsAdmissionSource::ProducerUnavailable,
56            ),
57        };
58        Self { kind, source }
59    }
60
61    /// Returns the stable admission-failure category.
62    pub const fn kind(&self) -> EngineMetricsAdmissionErrorKind {
63        self.kind
64    }
65}
66
67impl fmt::Display for EngineMetricsAdmissionError {
68    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
69        write!(formatter, "metrics admission failed: {}", self.source)
70    }
71}
72
73impl std::error::Error for EngineMetricsAdmissionError {
74    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
75        match &self.source {
76            EngineMetricsAdmissionSource::Driver(source) => Some(source),
77            EngineMetricsAdmissionSource::ProducerContended
78            | EngineMetricsAdmissionSource::ProducerUnavailable => None,
79        }
80    }
81}
82
83#[derive(Debug)]
84enum EngineMetricsAdmissionSource {
85    Driver(DriverObservationAdmissionError),
86    ProducerContended,
87    ProducerUnavailable,
88}
89
90impl fmt::Display for EngineMetricsAdmissionSource {
91    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
92        match self {
93            Self::Driver(source) => source.fmt(formatter),
94            Self::ProducerContended => {
95                formatter.write_str("producer metrics ownership is temporarily contended")
96            }
97            Self::ProducerUnavailable => {
98                formatter.write_str("producer metrics ownership is unavailable")
99            }
100        }
101    }
102}
103
104/// Stable category for failure after metrics observation was admitted.
105#[derive(Clone, Copy, Debug, Eq, PartialEq)]
106pub enum EngineMetricsObserverErrorKind {
107    /// Graceful shutdown won before the reactor interpreted the snapshot.
108    Draining,
109    /// The snapshot completion owner disappeared or was observed twice.
110    Completion,
111}
112
113/// Failure to observe one accepted operational-metrics snapshot.
114#[derive(Clone, Copy, Debug, Eq, PartialEq)]
115pub struct EngineMetricsObserverError {
116    kind: EngineMetricsObserverErrorKind,
117}
118
119impl EngineMetricsObserverError {
120    pub(crate) const fn from_driver(source: DriverObservationError) -> Self {
121        let kind = match source.kind() {
122            DriverObservationErrorKind::Draining => EngineMetricsObserverErrorKind::Draining,
123            DriverObservationErrorKind::Completion => EngineMetricsObserverErrorKind::Completion,
124        };
125        Self { kind }
126    }
127
128    /// Returns the stable observation-failure category.
129    pub const fn kind(self) -> EngineMetricsObserverErrorKind {
130        self.kind
131    }
132}
133
134impl fmt::Display for EngineMetricsObserverError {
135    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
136        match self.kind {
137            EngineMetricsObserverErrorKind::Draining => {
138                formatter.write_str("the client began draining before metrics were captured")
139            }
140            EngineMetricsObserverErrorKind::Completion => {
141                formatter.write_str("the metrics completion owner became unavailable")
142            }
143        }
144    }
145}
146
147impl std::error::Error for EngineMetricsObserverError {}