katra-core 0.1.0

//! The trace event — one correlated observation in a Katra trace.

use serde::{Deserialize, Serialize};

use crate::ResourceRef;
use crate::ids::{RequestId, Seq, SpanId};
use crate::kind::{EventKind, Phase};
use crate::payload::Payload;
use crate::scope::Scope;

/// A single captured event.
///
/// Events are correlated through:
/// * `seq` — global monotonic order;
/// * `span_id` — pairs a `Begin` with its `End`;
/// * `request_id` — groups events belonging to one logical request
///   (an asset load, a frame, a scene transition);
/// * `causes` — explicit causal links to earlier event seqs (the semantic
///   causal graph, KatraProfiler §6).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct TraceEvent {
    /// Global monotonic sequence number.
    pub seq: Seq,
    /// Monotonic timestamp in ns (relative to profiler start).
    pub ts_mono_ns: u64,
    /// Wall-clock timestamp in ns since the Unix epoch.
    pub ts_wall_ns: u64,
    /// Kernel thread id.
    pub thread_id: u64,
    /// Process id.
    pub process_id: u64,
    /// Producing layer.
    pub scope: Scope,
    /// Event kind.
    pub kind: EventKind,
    /// Phase.
    pub phase: Phase,
    /// Span id (for Begin/End pairing); `None` for standalone events.
    pub span_id: Option<SpanId>,
    /// Correlated request id; `None` if not part of a request.
    pub request_id: Option<RequestId>,
    /// Explicit causal links to earlier event seqs.
    pub causes: Vec<u64>,
    /// Optional resource reference `(domain, id)`.
    pub resource: Option<ResourceRef>,
    /// Structured payload.
    pub payload: Payload,
    /// Estimated/measured cost in ns (for aggregation).
    pub cost_estimate_ns: Option<u64>,
    /// Prediction confidence 0..1, when the event is a prediction.
    pub confidence: Option<f32>,
}

impl TraceEvent {
    /// A convenience constructor for a minimal `Instant` event.
    #[allow(clippy::too_many_arguments)]
    pub fn instant(
        seq: Seq,
        ts_mono_ns: u64,
        ts_wall_ns: u64,
        thread_id: u64,
        process_id: u64,
        scope: Scope,
        kind: EventKind,
        payload: Payload,
    ) -> Self {
        TraceEvent {
            seq,
            ts_mono_ns,
            ts_wall_ns,
            thread_id,
            process_id,
            scope,
            kind,
            phase: Phase::Instant,
            span_id: None,
            request_id: None,
            causes: Vec::new(),
            resource: None,
            payload,
            cost_estimate_ns: None,
            confidence: None,
        }
    }
}

/// Options that enrich an emitted event.
#[derive(Clone, Debug, Default)]
pub struct EmitOpts {
    /// Correlated request id.
    pub request_id: Option<RequestId>,
    /// Causal links to earlier event seqs (max 2 on the hot path).
    pub causes: Vec<u64>,
    /// Span id (for Begin/End pairing).
    pub span_id: Option<SpanId>,
    /// Resource reference.
    pub resource: Option<ResourceRef>,
    /// Estimated/measured cost in ns.
    pub cost_estimate_ns: Option<u64>,
    /// Prediction confidence 0..1.
    pub confidence: Option<f32>,
}