xirang_kernel/registry_core/declaration/call_evidence.rs
1//! Observed call edges, evidence, and the trace mode that records them.
2//! 已观测的调用边、证据,以及记录它们的追踪模式。
3
4use super::*;
5
6/// One observed call site: which node and function were active in which trace frame, and
7/// where the call was written. A `CallEdge` is the pair of sites that make up the edge.
8/// 一处被观测到的调用点:哪个节点、哪个函数在哪个追踪帧里处于活动状态,以及这次调用写在哪儿。
9/// 一条 `CallEdge` 由两处这样的调用点组成。
10#[derive(Clone, Debug, PartialEq, Eq)]
11pub struct CallSite {
12 /// Registry node the active frame belongs to.
13 /// 当前活动帧所属的注册机节点。
14 pub node: NodeId,
15 /// Logical function name active in that frame.
16 /// 该帧中处于活动状态的逻辑函数名。
17 pub function: &'static str,
18 /// Identifier of the trace frame that observed this call, unique per invocation.
19 /// 观察到本次调用的追踪帧编号,每次调用实例都不同。
20 pub frame_id: u64,
21 /// Stable declaration/callsite location. `None` is reserved for callers
22 /// that construct a synthetic frame directly.
23 /// 稳定的声明/调用位置;`None` 仅保留给直接构造合成帧的调用者。
24 pub source: Option<SourceLocation>,
25}
26
27// ---------------------------------------------------------------------------
28// Observed call edges and evidence. Shared by run_method tracing and
29// debug_method tooling; defined here because they are pure protocol nouns.
30// 已观测调用边与证据。由 run_method 追踪与 debug_method 工具共用;
31// 作为纯协议名词定义在 kernel。
32
33/// One call edge that was observed while a `CallTrace` frame was active.
34/// `CallTrace` 中实际观察到的一条调用边。
35#[derive(Clone, Debug, PartialEq, Eq)]
36pub struct CallEdge {
37 /// Site that observed the call while its frame was active.
38 /// 调用发生、其帧处于活动状态的调用点。
39 pub caller: CallSite,
40 /// Site recorded as the target of that call.
41 /// 被记录为该调用目标的调用点。
42 pub callee: CallSite,
43}
44
45/// Provenance of a relationship across runtime, MIR, and source evidence.
46/// 运行时、MIR 与源码证据共用的关系来源。
47#[derive(Clone, Copy, Debug, PartialEq, Eq)]
48pub enum EvidenceKind {
49 /// Confirmed by a live `CallTrace` observation.
50 /// 由一次实时 `CallTrace` 观测确认。
51 Live,
52 /// Candidate found by source analysis without runtime confirmation.
53 /// 源码分析找到、未经运行期确认的候选。
54 Source,
55 /// Candidate inferred from MIR; it may not have executed.
56 /// 由 MIR 推断出的候选;它可能并未执行。
57 Mir,
58 /// Supplied by an external adapter without a local trace.
59 /// 由外部适配器提供,没有本地追踪。
60 External,
61 /// A relation whose producer is not known.
62 /// 产出方未知的关系。
63 Unknown,
64}
65
66impl EvidenceKind {
67 /// Compact marker used by text, DOT, and Studio renderers.
68 /// 文本、DOT 与 Studio 渲染器共用的紧凑标记。
69 pub const fn marker(self) -> &'static str {
70 match self {
71 Self::Live => "+",
72 Self::Mir => "?",
73 Self::Source => "~",
74 Self::External => "x",
75 Self::Unknown => "!",
76 }
77 }
78
79 /// Stable machine and human readable label.
80 /// 稳定的机器和人类可读标签。
81 pub const fn label(self) -> &'static str {
82 match self {
83 Self::Live => "live",
84 Self::Mir => "mir",
85 Self::Source => "source",
86 Self::External => "external",
87 Self::Unknown => "unknown",
88 }
89 }
90
91 /// Only a live observation confirms that an edge executed.
92 /// 只有 Live 观察能确认边实际执行过。
93 pub const fn confirmed(self) -> bool {
94 matches!(self, Self::Live)
95 }
96}
97
98/// A call edge with invocation IDs removed for topology queries.
99/// 去掉调用实例编号、用于拓扑查询的逻辑调用边。
100#[derive(Clone, Debug, PartialEq, Eq)]
101pub struct LogicalCallEdge {
102 /// Calling side with invocation ids dropped, so repeated calls share one edge.
103 /// 去掉调用实例编号后的调用方,因此重复调用共享同一条边。
104 pub caller: CallSite,
105 /// Called side with invocation ids dropped, so repeated calls share one edge.
106 /// 去掉调用实例编号后的被调用方,因此重复调用共享同一条边。
107 pub callee: CallSite,
108 /// Provenance that justifies treating this edge as real.
109 /// 支撑该边成立的证据来源。
110 pub evidence: EvidenceKind,
111}
112
113// ---------------------------------------------------------------------------
114// Plugin manifests and flow contracts.
115// These types are declared here because `RegistrationInfo`/`RegistrationSnapshot`
116// carry them; the runtime plugin modules re-export them at their historical
117// paths. 以下类型因被注册声明持有而定义在 kernel;runtime 插件模块在原路径重导出。
118
119/// Runtime collection policy.
120/// 运行时追踪收集策略。
121///
122/// `Off` is the release-safe default for runtime traces. `ErrorsOnly`
123/// keeps evidence only for a failed result/panic scope, while `Full` retains
124/// every observed frame, local, and data edge.
125/// `Off` 是运行时追踪的发布安全默认值;`ErrorsOnly` 只保留
126/// 失败结果或 panic 作用域中的证据;`Full` 保留全部帧、局部值和数据边。
127#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
128pub enum TraceMode {
129 /// Do not allocate or retain runtime evidence.
130 /// 不分配也不保留运行时证据。
131 #[default]
132 Off,
133 /// Retain evidence only when an error scope fails.
134 /// 只有错误作用域失败时才保留证据。
135 ErrorsOnly,
136 /// Retain all observed runtime evidence.
137 /// 保留全部观察到的运行时证据。
138 Full,
139}
140
141impl TraceMode {
142 /// Parses the value accepted by `XIRANG_TRACE`.
143 /// 解析 `XIRANG_TRACE` 支持的值。
144 pub fn parse_trace_mode(value: &str) -> Option<Self> {
145 match value.trim().to_ascii_lowercase().as_str() {
146 "off" | "0" | "disabled" => Some(Self::Off),
147 "errors-only" | "errors_only" | "errors" => Some(Self::ErrorsOnly),
148 "full" | "all" => Some(Self::Full),
149 _ => None,
150 }
151 }
152}
153
154#[cfg(test)]
155mod trace_mode_tests {
156 use super::TraceMode;
157
158 #[test]
159 fn parse_accepts_documented_spellings() {
160 assert_eq!(TraceMode::parse_trace_mode("off"), Some(TraceMode::Off));
161 assert_eq!(
162 TraceMode::parse_trace_mode("ERRORS-ONLY"),
163 Some(TraceMode::ErrorsOnly)
164 );
165 assert_eq!(TraceMode::parse_trace_mode(" full "), Some(TraceMode::Full));
166 assert_eq!(TraceMode::parse_trace_mode("sometimes"), None);
167 }
168}