saluki_core/data_model/event/trace/
mod.rs

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

saluki_core/data_model/event/trace/
mod.rs
