tracestore

Documentation

Index

• type Factory
• type FoundTraceID
• type GetTraceParams
• type Operation
• type OperationQueryParams
• type Reader
• type TraceQueryParams
  • func (t *TraceQueryParams) ToSpanStoreQueryParameters() *spanstore.TraceQueryParameters
• type Writer

Types

type Factory

type Factory interface {
	// CreateTraceReader creates a spanstore.Reader.
	CreateTraceReader() (Reader, error)

	// CreateTraceWriter creates a spanstore.Writer.
	CreateTraceWriter() (Writer, error)
}

Factory defines an interface for a factory that can create implementations of different span storage components.

type FoundTraceID

type FoundTraceID struct {
	TraceID pcommon.TraceID
	Start   time.Time
	End     time.Time
}

FoundTraceID is a wrapper around trace ID returned from FindTraceIDs with an optional time range that may be used in GetTraces calls.

The time range is provided as an optimization hint for some storage backends that can perform more efficient queries when they know the approximate time range. The value should not be used for precise time-based filtering or assumptions. It is meant as a rough boundary and may not be populated in all cases.

type GetTraceParams

type GetTraceParams struct {
	// TraceID is the ID of the trace to retrieve. Required.
	TraceID pcommon.TraceID
	// Start of the time interval to search for trace ID. Optional.
	Start time.Time
	// End of the time interval to search for trace ID. Optional.
	End time.Time
}

GetTraceParams contains single-trace parameters for a GetTraces request. Some storage backends (e.g. Tempo) perform GetTraces much more efficiently if they know the approximate time range of the trace.

type Operation

type Operation struct {
	Name     string
	SpanKind string
}

Operation contains operation name and span kind

type OperationQueryParams

type OperationQueryParams struct {
	ServiceName string
	SpanKind    string
}

OperationQueryParams contains parameters of query operations, empty spanKind means get operations for all kinds of span.

type Reader

type Reader interface {
	// GetTraces returns an iterator that retrieves all traces with given IDs.
	// The iterator is single-use: once consumed, it cannot be used again.
	//
	// Chunking requirements:
	// - A single ptrace.Traces chunk MUST NOT contain spans from multiple traces.
	// - Large traces MAY be split across multiple, *consecutive* ptrace.Traces chunks.
	// - Each returned ptrace.Traces object MUST NOT be empty.
	//
	// Edge cases:
	// - If no spans are found for any given trace ID, the ID is ignored.
	// - If none of the trace IDs are found in the storage, an empty iterator is returned.
	// - If an error is encountered, the iterator returns the error and stops.
	GetTraces(ctx context.Context, traceIDs ...GetTraceParams) iter.Seq2[[]ptrace.Traces, error]

	// GetServices returns all service names known to the backend from spans
	// within its retention period.
	GetServices(ctx context.Context) ([]string, error)

	// GetOperations returns all operation names for a given service
	// known to the backend from spans within its retention period.
	GetOperations(ctx context.Context, query OperationQueryParams) ([]Operation, error)

	// FindTraces returns an iterator that retrieves traces matching query parameters.
	// The iterator is single-use: once consumed, it cannot be used again.
	//
	// The chunking rules is the same as for GetTraces.
	//
	// If no matching traces are found, the function returns an empty iterator.
	// If an error is encountered, the iterator returns the error and stops.
	//
	// There's currently an implementation-dependent ambiguity whether all query filters
	// (such as multiple tags) must apply to the same span within a trace, or can be satisfied
	// by different spans.
	FindTraces(ctx context.Context, query TraceQueryParams) iter.Seq2[[]ptrace.Traces, error]

	// FindTraceIDs returns an iterator that retrieves IDs of traces matching query parameters.
	// The iterator is single-use: once consumed, it cannot be used again.
	//
	// If no matching traces are found, the function returns an empty iterator.
	// If an error is encountered, the iterator returns the error and stops.
	//
	// This function behaves identically to FindTraces, except that it returns only the list
	// of matching trace IDs. This is useful in some contexts, such as batch jobs, where a
	// large list of trace IDs may be queried first and then the full traces are loaded
	// in batches.
	FindTraceIDs(ctx context.Context, query TraceQueryParams) iter.Seq2[[]FoundTraceID, error]
}

Reader finds and loads traces and other data from storage.

type TraceQueryParams

type TraceQueryParams struct {
	ServiceName   string
	OperationName string
	Attributes    pcommon.Map
	StartTimeMin  time.Time
	StartTimeMax  time.Time
	DurationMin   time.Duration
	DurationMax   time.Duration
	SearchDepth   int
}

TraceQueryParams contains query parameters to find traces. For a detailed definition of each field in this message, refer to `TraceQueryParameters` in `jaeger.api_v3` (https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v3/query_service.proto).

func (*TraceQueryParams) ToSpanStoreQueryParameters

func (t *TraceQueryParams) ToSpanStoreQueryParameters() *spanstore.TraceQueryParameters

type Writer

type Writer interface {
	// WriteTraces writes a batch of spans to storage. Idempotent.
	// Implementations are not required to support atomic transactions,
	// so if any of the spans fail to be written an error is returned.
	// Compatible with OTLP Exporter API.
	WriteTraces(ctx context.Context, td ptrace.Traces) error
}

Writer writes spans to storage.