Skip to main content

yang_base/
observability.rs

1//! 引擎可观测性配置(C4 收口)
2//!
3//! 把运行期可观测性旋钮(慢查询阈值等)收敛为单一纯数据配置。
4//! 遵循「资源显式所有权」理念:启动期经
5//! [`ToolsBuilder::config`](crate::tools::ToolsBuilder::config) 注册进
6//! [`Tools`](crate::tools::Tools) 的只读配置槽,运行期由
7//! [`ActionContext::table_query`](crate::action::ActionContext::table_query) 经
8//! `tools.config::<ObservabilityConfig>()` 读取。
9//!
10//! 未注册时慢查询日志整体关闭(阈值解析为 `None`),可观测性对未配置的调用方完全无感。
11
12use std::time::Duration;
13
14/// 可观测性运行期配置。
15///
16/// 当前仅含慢查询阈值,预留后续扩展(如采样率、SQL 文本记录开关等)。
17/// 派生 `Default`(全部关闭),未向 `Tools` 注册时即等价于此默认值。
18#[derive(Debug, Clone, Default)]
19#[non_exhaustive]
20pub struct ObservabilityConfig {
21    /// 慢查询阈值:受保护层 `TableQuery` 单次执行耗时超过此值时 `warn` 日志。
22    ///
23    /// `None`(默认)表示不启用慢查询日志,执行边界计时分支整体短路。
24    pub slow_query_threshold: Option<Duration>,
25}
26
27impl ObservabilityConfig {
28    /// 构造一个空配置(全部关闭),等价于 `Default`。
29    pub fn new() -> Self {
30        Self::default()
31    }
32
33    /// 设置慢查询阈值(链式)。
34    pub fn with_slow_query_threshold(mut self, threshold: Duration) -> Self {
35        self.slow_query_threshold = Some(threshold);
36        self
37    }
38}
39
40#[cfg(test)]
41mod tests {
42    use super::*;
43    use crate::tools::ToolsBuilder;
44
45    #[test]
46    fn builder_sets_threshold() {
47        let cfg = ObservabilityConfig::new().with_slow_query_threshold(Duration::from_millis(500));
48        assert_eq!(cfg.slow_query_threshold, Some(Duration::from_millis(500)));
49    }
50
51    #[test]
52    fn default_disables_slow_query_log() {
53        let cfg = ObservabilityConfig::new();
54        assert_eq!(cfg.slow_query_threshold, None);
55    }
56
57    #[test]
58    fn config_slot_roundtrip_via_tools() {
59        let threshold = Duration::from_millis(200);
60        let tools = ToolsBuilder::new()
61            .config(ObservabilityConfig::new().with_slow_query_threshold(threshold))
62            .build()
63            .expect("注册可观测性配置后应构建成功");
64
65        let retrieved = tools
66            .config::<ObservabilityConfig>()
67            .expect("已注册的配置应可读回");
68        assert_eq!(retrieved.slow_query_threshold, Some(threshold));
69    }
70}