trace

Documentation

Overview

Package trace holds the traces signal's ingest model: the []byte-based, OTLP-shaped, zero-alloc batch accepted at the storage boundary (in place of OTel-Go ptrace.Traces), and its projection into the columnar span model the record engine ingests.

A span is a record (mirroring signal/log): its stream identity is the producing Resource+Scope, and its per-record fields (name, kind, status, duration, trace/span ids, attributes, events, links) are columns the query filters by condition. Two trace-specific additions ride along as columns: the raw trace_id (with an equality bloom, so trace-by-id is a bloom-pruned equality fetch) and ingest-computed nested-set ids (so an embedder's TraceQL does ancestor/descendant as range comparisons). Events and links are serialized into byte columns.

Index

• Constants
• Variables
• func Project(td Traces, emit func(*recordengine.Batch)) (accepted int)
• func PutTraces(t *Traces)
• type Event
  • func DecodeEvents(data []byte) ([]Event, error)
• type Link
  • func DecodeLinks(data []byte) ([]Link, error)
• type ResourceSpans
  • func (rs *ResourceSpans) AddScope() *ScopeSpans
• type ScopeSpans
  • func (ss *ScopeSpans) AddSpan() *Span
• type Span
  • func (sp *Span) AddEvent() *Event
  • func (sp *Span) AddLink() *Link
• type Traces
  • func GetTraces() *Traces
  • func (t *Traces) AddResource() *ResourceSpans
  • func (t *Traces) Reset()

Constants

const (
	ColDuration     = "duration"
	ColKind         = "kind"
	ColStatusCode   = "status_code"
	ColParentID     = "parent_id"        // nested-set parent id (the parent's left), 0 for a root
	ColNestedLeft   = "nested_set_left"  // preorder enter index
	ColNestedRight  = "nested_set_right" // preorder exit index (descendant iff a.left<b.left && b.right<a.right)
	ColTraceID      = "trace_id"
	ColSpanID       = "span_id"
	ColParentSpanID = "parent_span_id"
	ColName         = "name"
	ColStatusMsg    = "status_message"
	ColAttrs        = "attrs"
	ColEvents       = "events"
	ColLinks        = "links"
)

Column names of the traces schema (per-record span columns; the span start time is the implicit primary timestamp / sort key, and the stream id is the Resource+Scope hash).

Variables

var Schema = recordengine.NewSchema(
	recordengine.Column{Name: ColDuration, Kind: recordengine.KindInt64, Codec: chunk.CodecT64},
	recordengine.Column{Name: ColKind, Kind: recordengine.KindInt64, Codec: chunk.CodecT64},
	recordengine.Column{Name: ColStatusCode, Kind: recordengine.KindInt64, Codec: chunk.CodecT64},
	recordengine.Column{Name: ColParentID, Kind: recordengine.KindInt64, Codec: chunk.CodecT64},
	recordengine.Column{Name: ColNestedLeft, Kind: recordengine.KindInt64, Codec: chunk.CodecT64},
	recordengine.Column{Name: ColNestedRight, Kind: recordengine.KindInt64, Codec: chunk.CodecT64},
	recordengine.Column{Name: ColTraceID, Kind: recordengine.KindBytes, Codec: chunk.CodecDict, Bloom: recordengine.BloomEquality},
	recordengine.Column{Name: ColSpanID, Kind: recordengine.KindBytes, Codec: chunk.CodecBytesRaw},
	recordengine.Column{Name: ColParentSpanID, Kind: recordengine.KindBytes, Codec: chunk.CodecDict},
	recordengine.Column{Name: ColName, Kind: recordengine.KindBytes, Codec: chunk.CodecDict, Bloom: recordengine.BloomFullText},
	recordengine.Column{Name: ColStatusMsg, Kind: recordengine.KindBytes, Codec: chunk.CodecDict},
	recordengine.Column{Name: ColAttrs, Kind: recordengine.KindBytes, Codec: chunk.CodecDict, Bloom: recordengine.BloomAttrs},
	recordengine.Column{Name: ColEvents, Kind: recordengine.KindBytes, Codec: chunk.CodecDict},
	recordengine.Column{Name: ColLinks, Kind: recordengine.KindBytes, Codec: chunk.CodecDict},
)

Schema is the traces vertical's record-engine column schema. trace_id carries an equality bloom (trace-by-id pruning); name carries a full-text bloom; attrs the attribute bloom.

Functions

func Project

func Project(td Traces, emit func(*recordengine.Batch)) (accepted int)

Project iterates a Traces batch and calls emit once per stream (each Resource+Scope group) with a recordengine.Batch of that stream's spans in the traces Schema's column order. It returns how many spans were emitted.

Before projecting, it computes nested-set ids per trace **within this batch**: spans are grouped by trace_id (across resources/scopes — a trace spans services), each trace's parent→child tree is built from parent_span_id, and a DFS assigns left/right/parent ids. A span whose parent is absent from the batch is treated as a root; cross-batch parents therefore get independent numbering (the raw parent_span_id column is always present for the embedder to reconcile). Events and links are serialized into their byte columns.

func PutTraces

func PutTraces(t *Traces)

PutTraces resets t and returns it to the pool. Do not use t afterward.

Types

type Event

type Event struct {
	Attributes signal.Attributes
	Time       int64
	Name       []byte
	Dropped    uint32
}

Event is a span event (a timestamped, named, attributed point within a span).

func DecodeEvents

func DecodeEvents(data []byte) ([]Event, error)

DecodeEvents parses [encodeEvents] output. Bounds-checked; byte fields alias data.

type Link

type Link struct {
	Attributes signal.Attributes
	TraceID    []byte
	SpanID     []byte
	TraceState []byte
	Dropped    uint32
}

Link is a span link to another span (possibly in another trace).

func DecodeLinks

func DecodeLinks(data []byte) ([]Link, error)

DecodeLinks parses [encodeLinks] output. Bounds-checked; byte fields alias data.

type ResourceSpans

type ResourceSpans struct {
	Resource signal.Resource
	Scopes   []ScopeSpans
}

ResourceSpans groups the spans emitted under one signal.Resource.

func (*ResourceSpans) AddScope

func (rs *ResourceSpans) AddScope() *ScopeSpans

AddScope appends a fresh ScopeSpans under the resource.

type ScopeSpans

type ScopeSpans struct {
	Scope signal.Scope
	Spans []Span
}

ScopeSpans groups the spans emitted under one signal.Scope. A (Resource, Scope) pair is one span **stream**.

func (*ScopeSpans) AddSpan

func (ss *ScopeSpans) AddSpan() *Span

AddSpan appends a fresh, fully-zeroed Span under the scope.

type Span

type Span struct {
	Attributes    signal.Attributes
	TraceID       []byte
	SpanID        []byte
	ParentSpanID  []byte
	Name          []byte
	StatusMessage []byte
	TraceState    []byte
	Start         int64
	End           int64
	Kind          int32
	StatusCode    int32
	Flags         uint32
	Dropped       uint32
	Events        []Event
	Links         []Link
}

Span is a single OTLP span. Start/End are unix nanos (Start is the record's primary timestamp; End-Start is the stored duration). TraceID is 16 bytes, SpanID/ParentSpanID are 8 (or nil).

func (*Span) AddEvent

func (sp *Span) AddEvent() *Event

AddEvent appends a zeroed Event to the span.

func (*Span) AddLink

func (sp *Span) AddLink() *Link

AddLink appends a zeroed Link to the span.

type Traces

type Traces struct {
	Resources []ResourceSpans
}

Traces is the internal traces ingest batch — the OTLP Resource→Scope→Span hierarchy with all identity as []byte. Resettable and pool-friendly (see GetTraces/PutTraces); build it with the Add* helpers, which reuse retained capacity.

func GetTraces

func GetTraces() *Traces

GetTraces returns a reset Traces from a shared pool; pair with PutTraces.

func (*Traces) AddResource

func (t *Traces) AddResource() *ResourceSpans

AddResource appends a fresh ResourceSpans and returns a pointer to it (Resource zeroed, Scopes emptied with capacity retained).

func (*Traces) Reset

func (t *Traces) Reset()

Reset clears the batch for reuse, retaining backing arrays.