qubit_cas/observability/
cas_observability_config.rs

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

qubit_cas/observability/
cas_observability_config.rs
