katra_core/
event.rs

1//! The trace event — one correlated observation in a Katra trace.
2
3use serde::{Deserialize, Serialize};
4
5use crate::ResourceRef;
6use crate::ids::{RequestId, Seq, SpanId};
7use crate::kind::{EventKind, Phase};
8use crate::payload::Payload;
9use crate::scope::Scope;
10
11/// A single captured event.
12///
13/// Events are correlated through:
14/// * `seq` — global monotonic order;
15/// * `span_id` — pairs a `Begin` with its `End`;
16/// * `request_id` — groups events belonging to one logical request
17///   (an asset load, a frame, a scene transition);
18/// * `causes` — explicit causal links to earlier event seqs (the semantic
19///   causal graph, KatraProfiler §6).
20#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
21pub struct TraceEvent {
22    /// Global monotonic sequence number.
23    pub seq: Seq,
24    /// Monotonic timestamp in ns (relative to profiler start).
25    pub ts_mono_ns: u64,
26    /// Wall-clock timestamp in ns since the Unix epoch.
27    pub ts_wall_ns: u64,
28    /// Kernel thread id.
29    pub thread_id: u64,
30    /// Process id.
31    pub process_id: u64,
32    /// Producing layer.
33    pub scope: Scope,
34    /// Event kind.
35    pub kind: EventKind,
36    /// Phase.
37    pub phase: Phase,
38    /// Span id (for Begin/End pairing); `None` for standalone events.
39    pub span_id: Option<SpanId>,
40    /// Correlated request id; `None` if not part of a request.
41    pub request_id: Option<RequestId>,
42    /// Explicit causal links to earlier event seqs.
43    pub causes: Vec<u64>,
44    /// Optional resource reference `(domain, id)`.
45    pub resource: Option<ResourceRef>,
46    /// Structured payload.
47    pub payload: Payload,
48    /// Estimated/measured cost in ns (for aggregation).
49    pub cost_estimate_ns: Option<u64>,
50    /// Prediction confidence 0..1, when the event is a prediction.
51    pub confidence: Option<f32>,
52}
53
54impl TraceEvent {
55    /// A convenience constructor for a minimal `Instant` event.
56    #[allow(clippy::too_many_arguments)]
57    pub fn instant(
58        seq: Seq,
59        ts_mono_ns: u64,
60        ts_wall_ns: u64,
61        thread_id: u64,
62        process_id: u64,
63        scope: Scope,
64        kind: EventKind,
65        payload: Payload,
66    ) -> Self {
67        TraceEvent {
68            seq,
69            ts_mono_ns,
70            ts_wall_ns,
71            thread_id,
72            process_id,
73            scope,
74            kind,
75            phase: Phase::Instant,
76            span_id: None,
77            request_id: None,
78            causes: Vec::new(),
79            resource: None,
80            payload,
81            cost_estimate_ns: None,
82            confidence: None,
83        }
84    }
85}
86
87/// Options that enrich an emitted event.
88#[derive(Clone, Debug, Default)]
89pub struct EmitOpts {
90    /// Correlated request id.
91    pub request_id: Option<RequestId>,
92    /// Causal links to earlier event seqs (max 2 on the hot path).
93    pub causes: Vec<u64>,
94    /// Span id (for Begin/End pairing).
95    pub span_id: Option<SpanId>,
96    /// Resource reference.
97    pub resource: Option<ResourceRef>,
98    /// Estimated/measured cost in ns.
99    pub cost_estimate_ns: Option<u64>,
100    /// Prediction confidence 0..1.
101    pub confidence: Option<f32>,
102}
katra_core/event.rs

katra_core/
event.rs
