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

saluki_core/data_model/event/trace/
mod.rs
