qubit_cas/observability/
cas_observability_config.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9
10use super::{CasObservabilityMode, ContentionThresholds, ListenerPanicPolicy};
11
12/// Observability settings shared by every execution of an executor.
13#[derive(Debug, Clone, PartialEq)]
14pub struct CasObservabilityConfig {
15    /// Selected observability mode.
16    mode: CasObservabilityMode,
17    /// Panic policy for event and alert listeners.
18    listener_panic_policy: ListenerPanicPolicy,
19    /// Optional contention threshold used for alerting.
20    contention_thresholds: Option<ContentionThresholds>,
21}
22
23impl CasObservabilityConfig {
24    /// Creates a report-only observability configuration (lowest overhead).
25    ///
26    /// Equivalent to the default.
27    ///
28    /// # Returns
29    /// A [`CasObservabilityConfig`] with report-only mode and no alerts.
30    #[inline]
31    pub fn report_only() -> Self {
32        Self::default()
33    }
34
35    /// Creates an event-stream observability configuration.
36    ///
37    /// # Returns
38    /// A [`CasObservabilityConfig`] that emits lifecycle events but no alerts.
39    #[inline]
40    pub fn event_stream() -> Self {
41        Self {
42            mode: CasObservabilityMode::EventStream,
43            ..Self::default()
44        }
45    }
46
47    /// Creates an event-stream configuration with contention alerts.
48    ///
49    /// # Parameters
50    /// - `thresholds`: Thresholds used to detect hot contention for alerts.
51    ///
52    /// # Returns
53    /// A [`CasObservabilityConfig`] with event streaming and alert enabled.
54    #[inline]
55    pub fn event_stream_with_alert(thresholds: ContentionThresholds) -> Self {
56        Self {
57            mode: CasObservabilityMode::EventStreamWithAlert,
58            contention_thresholds: Some(thresholds),
59            ..Self::default()
60        }
61    }
62
63    /// Returns the selected observability mode.
64    ///
65    /// # Returns
66    /// The current [`CasObservabilityMode`].
67    #[inline]
68    pub fn mode(&self) -> CasObservabilityMode {
69        self.mode
70    }
71
72    /// Switches to report-only observability.
73    ///
74    /// This disables lifecycle event streaming and clears contention thresholds.
75    ///
76    /// # Returns
77    /// Updated builder-style config (consumes self).
78    #[inline]
79    pub fn with_report_only(mut self) -> Self {
80        self.mode = CasObservabilityMode::ReportOnly;
81        self.contention_thresholds = None;
82        self
83    }
84
85    /// Switches to event-stream observability without alerts.
86    ///
87    /// This enables lifecycle events and clears contention thresholds.
88    ///
89    /// # Returns
90    /// Updated builder-style config (consumes self).
91    #[inline]
92    pub fn with_event_stream(mut self) -> Self {
93        self.mode = CasObservabilityMode::EventStream;
94        self.contention_thresholds = None;
95        self
96    }
97
98    /// Switches to event-stream observability with contention alerts.
99    ///
100    /// # Parameters
101    /// - `thresholds`: Thresholds used to detect hot contention for alerts.
102    ///
103    /// # Returns
104    /// Updated builder-style config with alert mode enabled (consumes self).
105    #[inline]
106    pub fn with_event_stream_with_alert(mut self, thresholds: ContentionThresholds) -> Self {
107        self.mode = CasObservabilityMode::EventStreamWithAlert;
108        self.contention_thresholds = Some(thresholds);
109        self
110    }
111
112    /// Disables contention alerts while keeping lifecycle event streaming.
113    ///
114    /// # Returns
115    /// Updated builder-style config with event streaming and no alert thresholds.
116    #[inline]
117    pub fn without_contention_alerts(self) -> Self {
118        self.with_event_stream()
119    }
120
121    /// Returns the listener panic policy.
122    ///
123    /// # Returns
124    /// Current [`ListenerPanicPolicy`] for event/alert hooks.
125    #[inline]
126    pub fn listener_panic_policy(&self) -> ListenerPanicPolicy {
127        self.listener_panic_policy
128    }
129
130    /// Sets the listener panic policy.
131    ///
132    /// # Parameters
133    /// - `policy`: How to handle panics from registered hooks.
134    ///
135    /// # Returns
136    /// Updated builder-style config (consumes self).
137    #[inline]
138    pub fn with_listener_panic_policy(mut self, policy: ListenerPanicPolicy) -> Self {
139        self.listener_panic_policy = policy;
140        self
141    }
142
143    /// Returns configured contention thresholds, when alerting is enabled.
144    ///
145    /// # Returns
146    /// `Some(thresholds)` if alert mode is active, otherwise `None`.
147    #[inline]
148    pub fn contention_thresholds(&self) -> Option<ContentionThresholds> {
149        self.contention_thresholds
150    }
151
152    /// Sets contention thresholds and enables alert-capable event streaming.
153    ///
154    /// # Parameters
155    /// - `thresholds`: Thresholds for classifying executions as hot contention.
156    ///
157    /// # Returns
158    /// Updated builder-style config with alert mode enabled (consumes self).
159    #[inline]
160    pub fn with_contention_thresholds(self, thresholds: ContentionThresholds) -> Self {
161        self.with_event_stream_with_alert(thresholds)
162    }
163}
164
165impl Default for CasObservabilityConfig {
166    /// Returns report-only observability (the default, lowest overhead mode).
167    ///
168    /// # Returns
169    /// Config with `ReportOnly` mode, propagate panics, and no contention
170    /// thresholds.
171    #[inline]
172    fn default() -> Self {
173        Self {
174            mode: CasObservabilityMode::ReportOnly,
175            listener_panic_policy: ListenerPanicPolicy::Propagate,
176            contention_thresholds: None,
177        }
178    }
179}
qubit_cas/observability/cas_observability_config.rs

qubit_cas/observability/
cas_observability_config.rs
