dial9_trace_format/
lib.rs

1//! # dial9-trace-format
2//!
3//! A compact binary trace format for recording timestamped events with
4//! schema-driven encoding. Events are described by schemas (registered at
5//! write time) and encoded with delta-compressed timestamps, LEB128 varints,
6//! and an interned string pool.
7//!
8//! ## Crate layout
9//!
10//! - [`encoder`] — high-level [`Encoder`](encoder::Encoder) for writing traces
11//! - [`decoder`] — streaming [`Decoder`](decoder::Decoder) for reading traces
12//! - [`codec`]   — wire-format types ([`WireTypeId`](codec::WireTypeId),
13//!   [`PoolEntry`](codec::PoolEntry)) that appear in decoded frames
14//! - [`schema`]  — [`SchemaEntry`] and
15//!   [`FieldDef`] describing event layouts
16//! - [`types`]   — field value types, the [`TraceField`]
17//!   trait, and the [`EventEncoder`] used by derived code
18
19pub mod codec;
20pub mod decoder;
21pub mod encoder;
22pub(crate) mod leb128;
23pub mod schema;
24pub mod types;
25
26pub use dial9_trace_format_derive::TraceEvent;
27pub use types::DynamicListRef;
28pub use types::DynamicMapRef;
29pub use types::EventEncoder;
30pub use types::FieldValue;
31pub use types::InternedStackFrames;
32pub use types::InternedString;
33pub use types::StackFrames;
34pub use types::TraceField;
35
36use schema::{FieldDef, SchemaEntry};
37use types::FieldValueRef;
38
39/// Trait implemented by `#[derive(TraceEvent)]` for compile-time event types.
40pub trait TraceEvent {
41    /// Decoded form of this event, potentially borrowing from the input buffer.
42    type Ref<'a>;
43
44    /// The event type name (used in schema registration).
45    fn event_name() -> &'static str;
46    /// Field definitions for schema registration.
47    /// When `has_timestamp()` is true, the timestamp is NOT included here —
48    /// it is encoded in the event frame header.
49    fn field_defs() -> Vec<FieldDef>;
50    /// Whether this event type carries a packed timestamp in the event header.
51    fn has_timestamp() -> bool {
52        true
53    }
54    /// Return the event's timestamp in nanoseconds.
55    fn timestamp(&self) -> u64;
56    /// Encode this event's non-timestamp fields into the encoder.
57    fn encode_fields<W: std::io::Write>(
58        &self,
59        enc: &mut types::EventEncoder<'_, W>,
60    ) -> std::io::Result<()>;
61    /// Decode from field values using field definitions for name resolution.
62    /// `timestamp_ns` is the absolute timestamp from the event header (if present).
63    fn decode<'a>(
64        timestamp_ns: Option<u64>,
65        fields: &[FieldValueRef<'a>],
66        field_defs: &[FieldDef],
67    ) -> Option<Self::Ref<'a>>;
68
69    /// Build a SchemaEntry for this event type.
70    fn schema_entry() -> SchemaEntry {
71        SchemaEntry {
72            name: Self::event_name().to_string(),
73            has_timestamp: Self::has_timestamp(),
74            fields: Self::field_defs(),
75            annotations: Vec::new(),
76        }
77    }
78}
dial9_trace_format/lib.rs

dial9_trace_format/
lib.rs
