Understanding spans

Goal

By the end of this guide, you should be able to:

• Understand what spans are and how they appear in DataPrime
• Recognize the differences and similarities between logs and spans
• Use span-specific keypaths like $l, $m, and $m.duration
• Access span attributes and tags using the correct syntax
• Write effective DataPrime queries against trace data

Why It Matters

Spans are the building blocks of trace data. They represent timed operations—like HTTP requests, function invocations, or database calls—and are essential for understanding latency, system dependencies, and distributed behavior. In DataPrime, spans are just another structured data source. Once you know how they work, you can filter, group, and analyze them just like logs.

Spans vs. Logs in DataPrime

Although both logs and spans are JSON documents, they serve different purposes and have different structures. Here’s how they compare in the context of DataPrime:

Concept	Logs	Spans
Source	source logs	source spans
Duration	Usually inferred or calculated	Always present via $m.duration
Relationships	Standalone or loosely correlated	Nested via $l.traceId, $l.spanId
Use cases	Content analysis, state tracking	Performance analysis, service dependency mapping

Working with spans in DataPrime

Spans are accessed in DataPrime using source spans. Once you do, you’ll encounter fields specific to tracing:

• $l.operationName — the name of the operation (e.g., /checkout, getUser)
• $m.duration — how long the span took (usually in microseconds or nanoseconds)
• $d.traceID, $d.spanId, $d.parentId — identifiers used to reconstruct trace trees
• $m.tags — metadata added at span generation time

All of these are available for filtering, grouping, and transformation using normal DataPrime syntax.

Accessing tags and attributes

Like logs, span metadata is stored in a nested and structured form. As with logs you can access data through flat dot notation or bracket notation

The key below has periods (.) within the key which requires the use of bracket notation.

source spans
| choose $d.tags['cx.event.id']

This is equivalent to:

source spans
| choose $m['tags']['cx.event.id']

Chaining filter and choose with spans

source spans
| filter $d.duration > 300
| choose parentId

Conclusion

Spans are a first-class data type in DataPrime. While they look different from logs, they work seamlessly with the same functions and operators—as long as you understand how their structure maps to DataPrime's keypath system. Once you do, you’ll be able to trace system behavior, analyze performance, and detect bottlenecks—all using the same query language you already know.

Previous Understanding logs

Next Understanding commands

Theme

Light

light

dark