saluki_core/data_model/event/trace/
mod.rs

1//! Traces.
2
3use saluki_common::collections::FastHashMap;
4use stringtheory::MetaString;
5
6/// A trace event.
7///
8/// A trace is a collection of spans that represent a distributed trace.
9#[derive(Clone, Debug, PartialEq)]
10pub struct Trace {
11    /// The spans that make up this trace.
12    spans: Vec<Span>,
13}
14
15impl Trace {
16    /// Creates a new `Trace` with the given spans.
17    pub fn new(spans: Vec<Span>) -> Self {
18        Self { spans }
19    }
20
21    /// Returns a reference to the spans in this trace.
22    pub fn spans(&self) -> &[Span] {
23        &self.spans
24    }
25
26    /// Returns a mutable reference to the spans in this trace.
27    pub fn spans_mut(&mut self) -> &mut Vec<Span> {
28        &mut self.spans
29    }
30}
31
32/// A span event.
33#[derive(Clone, Debug, PartialEq, Default)]
34pub struct Span {
35    /// The name of the service associated with this span.
36    service: MetaString,
37    /// The operation name of this span.
38    name: MetaString,
39    /// The resource associated with this span.
40    resource: MetaString,
41    /// The trace identifier this span belongs to.
42    trace_id: u64,
43    /// The unique identifier of this span.
44    span_id: u64,
45    /// The identifier of this span's parent, if any.
46    parent_id: u64,
47    /// The start timestamp of this span in nanoseconds since Unix epoch.
48    start: i64,
49    /// The duration of this span in nanoseconds.
50    duration: i64,
51    /// Error flag represented as 0 (no error) or 1 (error).
52    error: i32,
53    /// String-valued tags attached to this span.
54    meta: FastHashMap<MetaString, MetaString>,
55    /// Numeric-valued tags attached to this span.
56    metrics: FastHashMap<MetaString, f64>,
57    /// Span type classification (e.g., web, db, lambda).
58    span_type: MetaString,
59    /// Structured metadata payloads.
60    meta_struct: FastHashMap<MetaString, Vec<u8>>,
61    /// Links describing relationships to other spans.
62    span_links: Vec<SpanLink>,
63    /// Events associated with this span.
64    span_events: Vec<SpanEvent>,
65}
66
67impl Span {
68    /// Creates a new `Span` with the required identifiers and names.
69    pub fn new(
70        service: impl Into<MetaString>, name: impl Into<MetaString>, resource: impl Into<MetaString>, trace_id: u64,
71        span_id: u64,
72    ) -> Self {
73        Self {
74            service: service.into(),
75            name: name.into(),
76            resource: resource.into(),
77            trace_id,
78            span_id,
79            ..Self::default()
80        }
81    }
82
83    /// Sets the service name.
84    pub fn with_service(mut self, service: impl Into<MetaString>) -> Self {
85        self.service = service.into();
86        self
87    }
88
89    /// Sets the operation name.
90    pub fn with_name(mut self, name: impl Into<MetaString>) -> Self {
91        self.name = name.into();
92        self
93    }
94
95    /// Sets the resource name.
96    pub fn with_resource(mut self, resource: impl Into<MetaString>) -> Self {
97        self.resource = resource.into();
98        self
99    }
100
101    /// Sets the trace identifier.
102    pub fn with_trace_id(mut self, trace_id: u64) -> Self {
103        self.trace_id = trace_id;
104        self
105    }
106
107    /// Sets the span identifier.
108    pub fn with_span_id(mut self, span_id: u64) -> Self {
109        self.span_id = span_id;
110        self
111    }
112
113    /// Sets the parent span identifier.
114    pub fn with_parent_id(mut self, parent_id: u64) -> Self {
115        self.parent_id = parent_id;
116        self
117    }
118
119    /// Sets the start timestamp.
120    pub fn with_start(mut self, start: i64) -> Self {
121        self.start = start;
122        self
123    }
124
125    /// Sets the span duration.
126    pub fn with_duration(mut self, duration: i64) -> Self {
127        self.duration = duration;
128        self
129    }
130
131    /// Sets the error flag.
132    pub fn with_error(mut self, error: i32) -> Self {
133        self.error = error;
134        self
135    }
136
137    /// Sets the span type (e.g., web, db, lambda).
138    pub fn with_span_type(mut self, span_type: impl Into<MetaString>) -> Self {
139        self.span_type = span_type.into();
140        self
141    }
142
143    /// Replaces the string-valued tag map.
144    pub fn with_meta(mut self, meta: impl Into<Option<FastHashMap<MetaString, MetaString>>>) -> Self {
145        self.meta = meta.into().unwrap_or_default();
146        self
147    }
148
149    /// Replaces the numeric-valued tag map.
150    pub fn with_metrics(mut self, metrics: impl Into<Option<FastHashMap<MetaString, f64>>>) -> Self {
151        self.metrics = metrics.into().unwrap_or_default();
152        self
153    }
154
155    /// Replaces the structured metadata map.
156    pub fn with_meta_struct(mut self, meta_struct: impl Into<Option<FastHashMap<MetaString, Vec<u8>>>>) -> Self {
157        self.meta_struct = meta_struct.into().unwrap_or_default();
158        self
159    }
160
161    /// Replaces the span links collection.
162    pub fn with_span_links(mut self, span_links: impl Into<Option<Vec<SpanLink>>>) -> Self {
163        self.span_links = span_links.into().unwrap_or_default();
164        self
165    }
166
167    /// Replaces the span events collection.
168    pub fn with_span_events(mut self, span_events: impl Into<Option<Vec<SpanEvent>>>) -> Self {
169        self.span_events = span_events.into().unwrap_or_default();
170        self
171    }
172
173    /// Returns the service name.
174    pub fn service(&self) -> &str {
175        &self.service
176    }
177
178    /// Returns the operation name.
179    pub fn name(&self) -> &str {
180        &self.name
181    }
182
183    /// Returns the resource name.
184    pub fn resource(&self) -> &str {
185        &self.resource
186    }
187
188    /// Returns the trace identifier.
189    pub fn trace_id(&self) -> u64 {
190        self.trace_id
191    }
192
193    /// Returns the span identifier.
194    pub fn span_id(&self) -> u64 {
195        self.span_id
196    }
197
198    /// Returns the parent span identifier.
199    pub fn parent_id(&self) -> u64 {
200        self.parent_id
201    }
202
203    /// Returns the start timestamp.
204    pub fn start(&self) -> i64 {
205        self.start
206    }
207
208    /// Returns the span duration.
209    pub fn duration(&self) -> i64 {
210        self.duration
211    }
212
213    /// Returns the error flag.
214    pub fn error(&self) -> i32 {
215        self.error
216    }
217
218    /// Returns the span type.
219    pub fn span_type(&self) -> &str {
220        &self.span_type
221    }
222
223    /// Returns the string-valued tag map.
224    pub fn meta(&self) -> &FastHashMap<MetaString, MetaString> {
225        &self.meta
226    }
227
228    /// Returns the numeric-valued tag map.
229    pub fn metrics(&self) -> &FastHashMap<MetaString, f64> {
230        &self.metrics
231    }
232
233    /// Returns the structured metadata map.
234    pub fn meta_struct(&self) -> &FastHashMap<MetaString, Vec<u8>> {
235        &self.meta_struct
236    }
237
238    /// Returns the span links collection.
239    pub fn span_links(&self) -> &[SpanLink] {
240        &self.span_links
241    }
242
243    /// Returns the span events collection.
244    pub fn span_events(&self) -> &[SpanEvent] {
245        &self.span_events
246    }
247}
248
249/// A link between spans describing a causal relationship.
250#[derive(Clone, Debug, PartialEq, Default)]
251pub struct SpanLink {
252    /// Trace identifier for the linked span.
253    trace_id: u64,
254    /// High bits of the trace identifier when 128-bit IDs are used.
255    trace_id_high: u64,
256    /// Span identifier for the linked span.
257    span_id: u64,
258    /// Additional attributes attached to the link.
259    attributes: FastHashMap<MetaString, MetaString>,
260    /// W3C tracestate value.
261    tracestate: MetaString,
262    /// W3C trace flags where the high bit must be set when provided.
263    flags: u32,
264}
265
266impl SpanLink {
267    /// Creates a new span link for the provided identifiers.
268    pub fn new(trace_id: u64, span_id: u64) -> Self {
269        Self {
270            trace_id,
271            span_id,
272            ..Self::default()
273        }
274    }
275
276    /// Sets the trace identifier.
277    pub fn with_trace_id(mut self, trace_id: u64) -> Self {
278        self.trace_id = trace_id;
279        self
280    }
281
282    /// Sets the high bits of the trace identifier.
283    pub fn with_trace_id_high(mut self, trace_id_high: u64) -> Self {
284        self.trace_id_high = trace_id_high;
285        self
286    }
287
288    /// Sets the span identifier.
289    pub fn with_span_id(mut self, span_id: u64) -> Self {
290        self.span_id = span_id;
291        self
292    }
293
294    /// Replaces the attributes map.
295    pub fn with_attributes(mut self, attributes: impl Into<Option<FastHashMap<MetaString, MetaString>>>) -> Self {
296        self.attributes = attributes.into().unwrap_or_default();
297        self
298    }
299
300    /// Sets the W3C tracestate value.
301    pub fn with_tracestate(mut self, tracestate: impl Into<MetaString>) -> Self {
302        self.tracestate = tracestate.into();
303        self
304    }
305
306    /// Sets the W3C trace flags.
307    pub fn with_flags(mut self, flags: u32) -> Self {
308        self.flags = flags;
309        self
310    }
311
312    /// Returns the trace identifier.
313    pub fn trace_id(&self) -> u64 {
314        self.trace_id
315    }
316
317    /// Returns the high bits of the trace identifier.
318    pub fn trace_id_high(&self) -> u64 {
319        self.trace_id_high
320    }
321
322    /// Returns the span identifier.
323    pub fn span_id(&self) -> u64 {
324        self.span_id
325    }
326
327    /// Returns the attributes map.
328    pub fn attributes(&self) -> &FastHashMap<MetaString, MetaString> {
329        &self.attributes
330    }
331
332    /// Returns the W3C tracestate value.
333    pub fn tracestate(&self) -> &str {
334        &self.tracestate
335    }
336
337    /// Returns the W3C trace flags.
338    pub fn flags(&self) -> u32 {
339        self.flags
340    }
341}
342
343/// An event associated with a span.
344#[derive(Clone, Debug, PartialEq, Default)]
345pub struct SpanEvent {
346    /// Event timestamp in nanoseconds since Unix epoch.
347    time_unix_nano: u64,
348    /// Event name.
349    name: MetaString,
350    /// Arbitrary attributes describing the event.
351    attributes: FastHashMap<MetaString, AttributeValue>,
352}
353
354impl SpanEvent {
355    /// Creates a new span event with the given timestamp and name.
356    pub fn new(time_unix_nano: u64, name: impl Into<MetaString>) -> Self {
357        Self {
358            time_unix_nano,
359            name: name.into(),
360            ..Self::default()
361        }
362    }
363
364    /// Sets the event timestamp.
365    pub fn with_time_unix_nano(mut self, time_unix_nano: u64) -> Self {
366        self.time_unix_nano = time_unix_nano;
367        self
368    }
369
370    /// Sets the event name.
371    pub fn with_name(mut self, name: impl Into<MetaString>) -> Self {
372        self.name = name.into();
373        self
374    }
375
376    /// Replaces the attributes map.
377    pub fn with_attributes(mut self, attributes: impl Into<Option<FastHashMap<MetaString, AttributeValue>>>) -> Self {
378        self.attributes = attributes.into().unwrap_or_default();
379        self
380    }
381
382    /// Returns the event timestamp.
383    pub fn time_unix_nano(&self) -> u64 {
384        self.time_unix_nano
385    }
386
387    /// Returns the event name.
388    pub fn name(&self) -> &str {
389        &self.name
390    }
391
392    /// Returns the attributes map.
393    pub fn attributes(&self) -> &FastHashMap<MetaString, AttributeValue> {
394        &self.attributes
395    }
396}
397
398/// Values supported for span and event attributes.
399#[derive(Clone, Debug, PartialEq)]
400pub enum AttributeValue {
401    /// String attribute value.
402    String(MetaString),
403    /// Boolean attribute value.
404    Bool(bool),
405    /// Integer attribute value.
406    Int(i64),
407    /// Floating-point attribute value.
408    Double(f64),
409    /// Array attribute values.
410    Array(Vec<AttributeScalarValue>),
411}
412
413/// Scalar values supported inside attribute arrays.
414#[derive(Clone, Debug, PartialEq)]
415pub enum AttributeScalarValue {
416    /// String array value.
417    String(MetaString),
418    /// Boolean array value.
419    Bool(bool),
420    /// Integer array value.
421    Int(i64),
422    /// Floating-point array value.
423    Double(f64),
424}
saluki_core/data_model/event/trace/mod.rs

saluki_core/data_model/event/trace/
mod.rs
