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