tracing

package
v1.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: Apache-2.0 Imports: 14 Imported by: 2

Documentation

Overview

Package tracing provides distributed tracing infrastructure for Bifrost

Package tracing provides distributed tracing utilities for Bifrost.

Package tracing provides distributed tracing infrastructure for Bifrost

Package tracing provides distributed tracing infrastructure for Bifrost

Package tracing provides distributed tracing infrastructure for Bifrost

Index

Constants

View Source 
const (
	TraceParentHeader = "traceparent"
	TraceStateHeader  = "tracestate"
)

W3C Trace Context header names

Variables

This section is empty.

Functions

func AddChildSpan 

func AddChildSpan(ctx context.Context, store *TraceStore, parentSpanID, name string, kind schemas.SpanKind) *schemas.Span

AddChildSpan adds a new child span to the current trace under a specific parent

func AddSpan 

func AddSpan(ctx context.Context, store *TraceStore, name string, kind schemas.SpanKind) *schemas.Span

AddSpan adds a new span to the current trace

func AddSpanEvent 

func AddSpanEvent(ctx context.Context, store *TraceStore, spanID string, event schemas.SpanEvent)

AddSpanEvent adds an event to a span

func ApplyResponse added in v1.9.0 

func ApplyResponse(d *schemas.LLMSpanData, resp *schemas.BifrostResponse, bifrostErr *schemas.BifrostError, opts SpanBuildOptions)

ApplyResponse fills the response and error sides of a record built earlier in the request. The two halves are populated at different points in the request lifecycle, so the record is assembled in two passes.

func BuildLLMSpanData added in v1.9.0 

func BuildLLMSpanData(
	req *schemas.BifrostRequest,
	resp *schemas.BifrostResponse,
	bifrostErr *schemas.BifrostError,
	opts SpanBuildOptions,
) *schemas.LLMSpanData

BuildLLMSpanData assembles the typed payload for an LLM-call span.

Chat is the only family filled today; the others fall through with identity and usage populated, and land their params as the remaining Populate* functions are migrated.

func EndSpan 

func EndSpan(ctx context.Context, store *TraceStore, spanID string, status schemas.SpanStatus, statusMsg string, attrs map[string]any)

EndSpan completes a span with the given status

func ExtractParentID 

func ExtractParentID(header *fasthttp.RequestHeader) string

ExtractParentID extracts the trace ID from W3C traceparent header. This returns the trace ID (32 hex chars) which should be used to continue the distributed trace from the upstream service. Returns empty string if header is not present or invalid.

func ExtractTraceParentSpanID added in v1.2.1 

func ExtractTraceParentSpanID(header *fasthttp.RequestHeader) string

ExtractTraceParentSpanID extracts the parent span ID from W3C traceparent header. This returns the span ID (16 hex chars) of the upstream service's span that initiated this request. This should be set as the ParentID of the root span in the receiving service to establish the parent-child relationship. Returns empty string if header is not present or invalid.

func ExtractTraceState added in v1.10.0 

func ExtractTraceState(header *fasthttp.RequestHeader) string

ExtractTraceState returns the inbound W3C tracestate, or "" when absent.

func FormatTraceparent 

func FormatTraceparent(traceID, spanID, traceFlags string) string

FormatTraceparent formats a W3C traceparent header value. It normalizes trace ID and span ID to W3C-compliant format: - trace ID: 32 lowercase hex characters - span ID: 16 lowercase hex characters Returns empty string if IDs cannot be normalized to valid format.

func GetTrace 

func GetTrace(ctx context.Context, store *TraceStore) *schemas.Trace

GetTrace retrieves the current trace from context using the store

func GetTraceID 

func GetTraceID(ctx context.Context) string

GetTraceID retrieves the trace ID from the context

func InjectTraceContext 

func InjectTraceContext(header *fasthttp.RequestHeader, traceID, spanID, traceFlags, traceState string)

InjectTraceContext injects W3C trace context headers into outgoing request

func PopulateBatchCancelRequestAttributes 

func PopulateBatchCancelRequestAttributes(req *schemas.BifrostBatchCancelRequest, attrs map[string]any)

PopulateBatchCancelRequestAttributes extracts batch cancel request attributes.

func PopulateBatchCancelResponseAttributes 

func PopulateBatchCancelResponseAttributes(resp *schemas.BifrostBatchCancelResponse, attrs map[string]any)

PopulateBatchCancelResponseAttributes extracts batch cancel response attributes.

func PopulateBatchCreateRequestAttributes 

func PopulateBatchCreateRequestAttributes(req *schemas.BifrostBatchCreateRequest, attrs map[string]any)

PopulateBatchCreateRequestAttributes extracts batch create request attributes.

func PopulateBatchCreateResponseAttributes 

func PopulateBatchCreateResponseAttributes(resp *schemas.BifrostBatchCreateResponse, attrs map[string]any)

PopulateBatchCreateResponseAttributes extracts batch create response attributes.

func PopulateBatchListRequestAttributes 

func PopulateBatchListRequestAttributes(req *schemas.BifrostBatchListRequest, attrs map[string]any)

PopulateBatchListRequestAttributes extracts batch list request attributes.

func PopulateBatchListResponseAttributes 

func PopulateBatchListResponseAttributes(resp *schemas.BifrostBatchListResponse, attrs map[string]any)

PopulateBatchListResponseAttributes extracts batch list response attributes.

func PopulateBatchResultsRequestAttributes 

func PopulateBatchResultsRequestAttributes(req *schemas.BifrostBatchResultsRequest, attrs map[string]any)

PopulateBatchResultsRequestAttributes extracts batch results request attributes.

func PopulateBatchResultsResponseAttributes 

func PopulateBatchResultsResponseAttributes(resp *schemas.BifrostBatchResultsResponse, attrs map[string]any)

PopulateBatchResultsResponseAttributes extracts batch results response attributes.

func PopulateBatchRetrieveRequestAttributes 

func PopulateBatchRetrieveRequestAttributes(req *schemas.BifrostBatchRetrieveRequest, attrs map[string]any)

PopulateBatchRetrieveRequestAttributes extracts batch retrieve request attributes.

func PopulateBatchRetrieveResponseAttributes 

func PopulateBatchRetrieveResponseAttributes(resp *schemas.BifrostBatchRetrieveResponse, attrs map[string]any)

PopulateBatchRetrieveResponseAttributes extracts batch retrieve response attributes.

func PopulateChatRequestAttributes 

func PopulateChatRequestAttributes(req *schemas.BifrostChatRequest, attrs map[string]any)

PopulateChatRequestAttributes extracts chat completion request attributes.

func PopulateChatResponseAttributes 

func PopulateChatResponseAttributes(resp *schemas.BifrostChatResponse, attrs map[string]any)

PopulateChatResponseAttributes extracts chat completion response attributes.

func PopulateContextAttributes deprecated 

func PopulateContextAttributes(
	attrs map[string]any,
	virtualKeyID, virtualKeyName string,
	selectedKeyID, selectedKeyName string,
	routingRuleID, routingRuleName string,
	teamID, teamName string,
	customerID, customerName string,
	businessUnitID, businessUnitName string,
	projectID, projectName string,
	userID, userName, userEmail string,
	numberOfRetries, fallbackIndex int,
)

PopulateContextAttributes extracts context-related attributes (virtual keys, retries, routing rules, etc.)

Deprecated: has no callers. Superseded by the span-based context enrichment in core (applyContextSpanAttributes), which writes the same dimensions straight onto the span instead of into an attribute map.

func PopulateEmbeddingRequestAttributes 

func PopulateEmbeddingRequestAttributes(req *schemas.BifrostEmbeddingRequest, attrs map[string]any)

PopulateEmbeddingRequestAttributes extracts embedding request attributes.

func PopulateEmbeddingResponseAttributes 

func PopulateEmbeddingResponseAttributes(resp *schemas.BifrostEmbeddingResponse, attrs map[string]any)

PopulateEmbeddingResponseAttributes extracts embedding response attributes.

func PopulateErrorAttributes 

func PopulateErrorAttributes(err *schemas.BifrostError) map[string]any

PopulateErrorAttributes extracts error attributes from a BifrostError.

func PopulateFileContentRequestAttributes 

func PopulateFileContentRequestAttributes(req *schemas.BifrostFileContentRequest, attrs map[string]any)

PopulateFileContentRequestAttributes extracts file content request attributes.

func PopulateFileContentResponseAttributes 

func PopulateFileContentResponseAttributes(resp *schemas.BifrostFileContentResponse, attrs map[string]any)

PopulateFileContentResponseAttributes extracts file content response attributes.

func PopulateFileDeleteRequestAttributes 

func PopulateFileDeleteRequestAttributes(req *schemas.BifrostFileDeleteRequest, attrs map[string]any)

PopulateFileDeleteRequestAttributes extracts file delete request attributes.

func PopulateFileDeleteResponseAttributes 

func PopulateFileDeleteResponseAttributes(resp *schemas.BifrostFileDeleteResponse, attrs map[string]any)

PopulateFileDeleteResponseAttributes extracts file delete response attributes.

func PopulateFileListRequestAttributes 

func PopulateFileListRequestAttributes(req *schemas.BifrostFileListRequest, attrs map[string]any)

PopulateFileListRequestAttributes extracts file list request attributes.

func PopulateFileListResponseAttributes 

func PopulateFileListResponseAttributes(resp *schemas.BifrostFileListResponse, attrs map[string]any)

PopulateFileListResponseAttributes extracts file list response attributes.

func PopulateFileRetrieveRequestAttributes 

func PopulateFileRetrieveRequestAttributes(req *schemas.BifrostFileRetrieveRequest, attrs map[string]any)

PopulateFileRetrieveRequestAttributes extracts file retrieve request attributes.

func PopulateFileRetrieveResponseAttributes 

func PopulateFileRetrieveResponseAttributes(resp *schemas.BifrostFileRetrieveResponse, attrs map[string]any)

PopulateFileRetrieveResponseAttributes extracts file retrieve response attributes.

func PopulateFileUploadRequestAttributes 

func PopulateFileUploadRequestAttributes(req *schemas.BifrostFileUploadRequest, attrs map[string]any)

PopulateFileUploadRequestAttributes extracts file upload request attributes.

func PopulateFileUploadResponseAttributes 

func PopulateFileUploadResponseAttributes(resp *schemas.BifrostFileUploadResponse, attrs map[string]any)

PopulateFileUploadResponseAttributes extracts file upload response attributes.

func PopulateRequestAttributes 

func PopulateRequestAttributes(req *schemas.BifrostRequest) map[string]any

PopulateRequestAttributes extracts common request attributes from a BifrostRequest. This is the main entry point for populating request attributes on a span.

func PopulateResponseAttributes 

func PopulateResponseAttributes(resp *schemas.BifrostResponse) map[string]any

PopulateResponseAttributes extracts common response attributes from a BifrostResponse. This is the main entry point for populating response attributes on a span.

func PopulateResponsesRequestAttributes 

func PopulateResponsesRequestAttributes(req *schemas.BifrostResponsesRequest, attrs map[string]any)

PopulateResponsesRequestAttributes extracts responses API request attributes.

func PopulateResponsesResponseAttributes 

func PopulateResponsesResponseAttributes(resp *schemas.BifrostResponsesResponse, attrs map[string]any)

PopulateResponsesResponseAttributes extracts responses API response attributes.

func PopulateSpeechRequestAttributes 

func PopulateSpeechRequestAttributes(req *schemas.BifrostSpeechRequest, attrs map[string]any)

PopulateSpeechRequestAttributes extracts speech request attributes.

func PopulateSpeechResponseAttributes 

func PopulateSpeechResponseAttributes(resp *schemas.BifrostSpeechResponse, attrs map[string]any)

PopulateSpeechResponseAttributes extracts speech response attributes.

func PopulateTextCompletionRequestAttributes 

func PopulateTextCompletionRequestAttributes(req *schemas.BifrostTextCompletionRequest, attrs map[string]any)

PopulateTextCompletionRequestAttributes extracts text completion request attributes.

func PopulateTextCompletionResponseAttributes 

func PopulateTextCompletionResponseAttributes(resp *schemas.BifrostTextCompletionResponse, attrs map[string]any)

PopulateTextCompletionResponseAttributes extracts text completion response attributes.

func PopulateTranscriptionRequestAttributes 

func PopulateTranscriptionRequestAttributes(req *schemas.BifrostTranscriptionRequest, attrs map[string]any)

PopulateTranscriptionRequestAttributes extracts transcription request attributes.

func PopulateTranscriptionResponseAttributes 

func PopulateTranscriptionResponseAttributes(resp *schemas.BifrostTranscriptionResponse, attrs map[string]any)

PopulateTranscriptionResponseAttributes extracts transcription response attributes.

func SetSpanAttribute 

func SetSpanAttribute(ctx context.Context, store *TraceStore, spanID, key string, value any)

SetSpanAttribute sets an attribute on a span

Types

type AudioSummary 

type AudioSummary = schemas.AudioSummary

Aliases kept so existing importers (the Datadog connector reads tracing.MessageSummary) compile unchanged after the types moved to core/schemas.

type DeferredSpanInfo 

type DeferredSpanInfo struct {
	SpanID              string
	StartTime           time.Time
	Tracer              schemas.Tracer           // Reference to tracer for completing the span
	RequestID           string                   // Request ID for accumulator lookup
	FirstChunkTime      time.Time                // Timestamp of first chunk (for TTFT calculation)
	ChunkCount          int                      // Count of received streaming chunks (for AttrTotalChunks)
	AccumulatedResponse *schemas.BifrostResponse // Full accumulated response from streaming chunks
	// contains filtered or unexported fields
}

DeferredSpanInfo stores information about a deferred span for streaming requests

type MessageSummary 

type MessageSummary = schemas.MessageSummary

Aliases kept so existing importers (the Datadog connector reads tracing.MessageSummary) compile unchanged after the types moved to core/schemas.

type ReasoningDetailSummary 

type ReasoningDetailSummary = schemas.ReasoningDetailSummary

Aliases kept so existing importers (the Datadog connector reads tracing.MessageSummary) compile unchanged after the types moved to core/schemas.

type ResponsesMessageSummary 

type ResponsesMessageSummary struct {
	Role        string                      `json:"role"`
	Content     string                      `json:"content"`
	Attachments []schemas.AttachmentSummary `json:"attachments,omitempty"`
	Reasoning   string                      `json:"reasoning,omitempty"`
	ToolCalls   []ToolCallSummary           `json:"tool_calls,omitempty"`
	ToolCallID  string                      `json:"tool_call_id,omitempty"`
}

ResponsesMessageSummary extends MessageSummary with reasoning

type SpanBuildOptions added in v1.9.0 

type SpanBuildOptions struct {
	Attachments schemas.AttachmentOptions
	Cost        *schemas.BifrostCost
	// WantContent is false when no connector reads message content, in which
	// case messages are never summarized and never marshalled.
	WantContent bool
	// WantRawPayloads is true only when a connector declared RawPayloadConsumer.
	WantRawPayloads bool
}

SpanBuildOptions carries the per-request values that are not derivable from the request or response alone.

type ToolCallSummary 

type ToolCallSummary = schemas.ToolCallSummary

Aliases kept so existing importers (the Datadog connector reads tracing.MessageSummary) compile unchanged after the types moved to core/schemas.

type TraceDemand added in v1.9.0 

type TraceDemand struct {
	// Any is false when no observability plugin is attached at all.
	Any bool
	// Content is true when at least one connector reads message content.
	Content bool
	// PluginSpans is true when at least one connector exports plugin hook spans
	// or decomposes them into an overhead breakdown.
	PluginSpans bool
	// RawPayloads is true only when a connector explicitly asks; unstated means false.
	RawPayloads bool
}

TraceDemand is the union of what the attached connectors read. It is computed once at registration and loaded atomically, so the per-request path never rebuilds it.

Producing what nobody consumes is the single largest cost in the tracing path: with no connector attached the trace was still deep-cloned for export, and message content was still summarized and marshalled.

type TraceStore 

type TraceStore struct {
	// contains filtered or unexported fields
}

TraceStore manages traces with thread-safe access and object pooling

func NewTraceStore 

func NewTraceStore(ttl time.Duration, logger schemas.Logger) *TraceStore

NewTraceStore creates a new TraceStore with the given TTL for cleanup

func (*TraceStore) AppendStreamingChunk 

func (s *TraceStore) AppendStreamingChunk(traceID string, chunk *schemas.BifrostResponse)

AppendStreamingChunk tracks TTFT and chunk count for the deferred span. Chunks are no longer stored — the new streaming.Accumulator handles full content accumulation for plugins (logging, maxim). This eliminates storing 1M+ BifrostResponse objects in the old accumulator at high concurrency.

func (*TraceStore) ClearDeferredSpan 

func (s *TraceStore) ClearDeferredSpan(traceID string)

ClearDeferredSpan removes the deferred span info for a trace ID

func (*TraceStore) CompleteTrace 

func (s *TraceStore) CompleteTrace(traceID string) *schemas.Trace

CompleteTrace marks the trace as complete, removes it from store, and returns it for flushing

func (*TraceStore) CreateTrace 

func (s *TraceStore) CreateTrace(inheritedTraceID string, requestID ...string) string

CreateTrace creates a new trace and stores it, returns the trace's store key. The inheritedTraceID parameter is the trace ID from an incoming W3C traceparent header. If provided, the trace's exported TraceID uses that value to continue the distributed trace. If empty, a new trace ID is generated.

The returned key is unique per call, NOT the (possibly shared) W3C trace ID: concurrent sibling requests of one distributed trace legitimately carry the same inherited trace ID, and keying the store by it made siblings overwrite each other — the first CompleteTrace stole the entry and the rest flushed nothing (lost log rows, issue #5256). Callers treat the returned value as an opaque handle; the W3C ID lives on trace.TraceID for span export and linking. Note: The parent span ID (for linking to upstream spans) is handled separately via context in StartSpan, not stored on the trace itself.

func (*TraceStore) EndSpan 

func (s *TraceStore) EndSpan(traceID, spanID string, status schemas.SpanStatus, statusMsg string, attrs map[string]any)

EndSpan marks a span as complete with the given status and attributes

func (*TraceStore) GetAccumulatedData 

func (s *TraceStore) GetAccumulatedData(traceID string) (ttftNs int64, chunkCount int)

GetAccumulatedData returns TTFT and chunk count for a deferred span. Chunks are no longer stored; full content is available via the streaming.Accumulator.

func (*TraceStore) GetAccumulatedResponse added in v1.2.33 

func (s *TraceStore) GetAccumulatedResponse(traceID string) *schemas.BifrostResponse

GetAccumulatedResponse returns the accumulated BifrostResponse for a deferred span. Returns nil if no accumulated response has been stored.

func (*TraceStore) GetDeferredSpan 

func (s *TraceStore) GetDeferredSpan(traceID string) *DeferredSpanInfo

GetDeferredSpan retrieves the deferred span info for a trace ID

func (*TraceStore) GetTrace 

func (s *TraceStore) GetTrace(traceID string) *schemas.Trace

GetTrace retrieves a trace by ID

func (*TraceStore) ReleaseTrace 

func (s *TraceStore) ReleaseTrace(trace *schemas.Trace)

ReleaseTrace returns the trace and its spans to the pools for reuse

func (*TraceStore) SetAccumulatedResponse added in v1.2.33 

func (s *TraceStore) SetAccumulatedResponse(traceID string, resp *schemas.BifrostResponse)

SetAccumulatedResponse stores the accumulated BifrostResponse on the deferred span info. Called during the final ProcessStreamingChunk to make the full response available for span attribute population in completeDeferredSpan.

func (*TraceStore) SetRequestHeaders added in v1.3.17 

func (s *TraceStore) SetRequestHeaders(traceID string, headers map[string]string)

SetRequestHeaders sets the captured request headers for the trace

func (*TraceStore) SetRequestID added in v1.3.0 

func (s *TraceStore) SetRequestID(traceID string, requestID string)

SetRequestID sets the request ID for the trace

func (*TraceStore) SetTraceAttribute added in v1.3.19 

func (s *TraceStore) SetTraceAttribute(traceID string, key string, value any)

SetTraceAttribute sets a trace-level attribute on the trace

func (*TraceStore) StartChildSpan 

func (s *TraceStore) StartChildSpan(traceID, parentSpanID, name string, kind schemas.SpanKind) *schemas.Span

StartChildSpan creates a new span as a child of the specified parent span

func (*TraceStore) StartSpan 

func (s *TraceStore) StartSpan(traceID, name string, kind schemas.SpanKind) *schemas.Span

StartSpan creates a new span and adds it to the trace

func (*TraceStore) Stop 

func (s *TraceStore) Stop()

Stop stops the cleanup goroutine and releases resources

func (*TraceStore) StoreDeferredSpan 

func (s *TraceStore) StoreDeferredSpan(traceID, spanID string)

StoreDeferredSpan stores a span ID for later completion (used for streaming requests)

type Tracer 

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer implements schemas.Tracer using TraceStore. It provides the bridge between the core Tracer interface and the framework's TraceStore implementation. It also embeds a streaming.Accumulator for centralized streaming chunk accumulation.

func NewTracer 

func NewTracer(store *TraceStore, pricingManager *modelcatalog.ModelCatalog, logger schemas.Logger) *Tracer

NewTracer creates a new Tracer wrapping the given TraceStore. The accumulator is embedded for centralized streaming chunk accumulation. The pricingManager is used for cost calculation in span attributes.

func (*Tracer) A2AContentDemand added in v1.10.0 

func (t *Tracer) A2AContentDemand() (content, raw bool)

A2AContentDemand lets the core gateway avoid retaining content that no connector consumes without depending on this framework package.

func (*Tracer) AddEvent 

func (t *Tracer) AddEvent(handle schemas.SpanHandle, name string, attrs map[string]any)

AddEvent adds a timestamped event to the span identified by the handle.

func (*Tracer) AddStreamingChunk 

func (t *Tracer) AddStreamingChunk(traceID string, response *schemas.BifrostResponse)

AddStreamingChunk tracks TTFT and chunk count for the deferred span. Chunk contents are no longer stored here; full content accumulation is handled by the embedded streaming.Accumulator (via ProcessStreamingChunk) for plugins.

func (*Tracer) AttachPluginLogs added in v1.3.0 

func (t *Tracer) AttachPluginLogs(traceID string, logs []schemas.PluginLogEntry)

AttachPluginLogs appends plugin log entries to the trace identified by traceID.

func (*Tracer) AwaitTransportHandoff added in v1.9.0 

func (t *Tracer) AwaitTransportHandoff(traceID string)

AwaitTransportHandoff blocks until the transport has handed the trace over.

func (*Tracer) CleanupStreamAccumulator 

func (t *Tracer) CleanupStreamAccumulator(traceID string)

CleanupStreamAccumulator removes the stream accumulator for the given trace ID. This should be called after the streaming request is complete.

func (*Tracer) ClearDeferredSpan 

func (t *Tracer) ClearDeferredSpan(traceID string)

ClearDeferredSpan removes the deferred span handle for a trace ID. Should be called after the deferred span has been completed.

func (*Tracer) ClearPausedStreamBuffer added in v1.4.4 

func (t *Tracer) ClearPausedStreamBuffer(traceID string) error

ClearPausedStreamBuffer drops chunks buffered while traceID is paused.

func (*Tracer) ClearTraceCompletionDeferral added in v1.9.0 

func (t *Tracer) ClearTraceCompletionDeferral(traceID string)

Drops the marker once the worker has completed the trace.

func (*Tracer) CollectRequestHeaderPatterns added in v1.3.17 

func (t *Tracer) CollectRequestHeaderPatterns() []string

CollectRequestHeaderPatterns returns the deduplicated union of header patterns requested by all observability plugins. The middleware uses this to capture only matched headers onto the trace, keeping the trace lean. The union is precomputed in SetObservabilityPlugins; this is a single atomic load.

func (*Tracer) CompleteAndFlushTrace added in v1.3.1 

func (t *Tracer) CompleteAndFlushTrace(traceID string)

CompleteAndFlushTrace ends a trace and forwards it to any observability plugins asynchronously. Realtime transports need this explicit flush because they bypass the HTTP tracing middleware that normally injects completed traces.

func (*Tracer) CreateStreamAccumulator 

func (t *Tracer) CreateStreamAccumulator(traceID string, startTime time.Time)

CreateStreamAccumulator creates a new stream accumulator for the given trace ID. This should be called at the start of a streaming request.

func (*Tracer) CreateTrace 

func (t *Tracer) CreateTrace(parentID string, requestID ...string) string

CreateTrace creates a new trace with optional parent ID and returns the trace ID.

func (*Tracer) DeferTraceCompletion added in v1.9.0 

func (t *Tracer) DeferTraceCompletion(traceID string)

Marks a trace as still being written by a worker, so the HTTP side skips CompleteAndFlushTrace. The stored channel closes once the transport has attached its own logs, which the worker waits for.

func (*Tracer) Demand added in v1.9.0 

func (t *Tracer) Demand() TraceDemand

Demand returns the connector demand union.

Before SetObservabilityPlugins has run, demand is unknown rather than absent, so full demand is returned: a request in flight during boot must not lose attributes or spans that a connector registered a moment later would have wanted. Declaring an empty plugin set is what expresses "nothing is listening".

func (*Tracer) EndSpan 

func (t *Tracer) EndSpan(handle schemas.SpanHandle, status schemas.SpanStatus, statusMsg string)

EndSpan completes a span with the given status and message.

func (*Tracer) EndStream added in v1.4.0 

func (t *Tracer) EndStream(traceID string, err *schemas.BifrostError)

EndStream terminates the streaming response. Any buffered chunks are flushed first; if err is non-nil it is then delivered as a terminal error chunk. After EndStream, all further provider chunks are dropped (PostLLMHook still fires).

func (*Tracer) EndTrace 

func (t *Tracer) EndTrace(traceID string) *schemas.Trace

EndTrace completes a trace and returns the trace data for observation/export. The returned trace should be released after use by calling ReleaseTrace.

func (*Tracer) FlushExpiredTrace added in v1.9.0 

func (t *Tracer) FlushExpiredTrace(trace *schemas.Trace)

FlushExpiredTrace exports a trace the TTL sweep is about to discard. A trace only expires when its completion never arrived, so dropping it unexported would hide the request from every connector while billing still recorded it.

func (*Tracer) ForceCleanupStreamAccumulator added in v1.4.0 

func (t *Tracer) ForceCleanupStreamAccumulator(traceID string)

ForceCleanupStreamAccumulator reaps the stream accumulator for the given trace ID regardless of its reference counter. It is the guaranteed end-of-stream backstop, called from the transport's trace completer once the stream has fully drained, so an aborted or otherwise non-cleanly-terminated stream (or a multi-plugin refcount imbalance) cannot leak its accumulator.

func (*Tracer) GateSend added in v1.4.0 

func (t *Tracer) GateSend(traceID string, chunk *schemas.BifrostStreamChunk, isFinal, isHardErr bool, ch chan *schemas.BifrostStreamChunk, ctx *schemas.BifrostContext) (ok bool)

GateSend delivers a stream chunk through the pause/resume/end gate. Replaces direct channel sends in provider helpers so plugin-driven pause/resume can take effect. See schemas.Tracer.GateSend for full semantics.

func (*Tracer) GetAccumulatedChunks 

func (t *Tracer) GetAccumulatedChunks(traceID string) (*schemas.BifrostResponse, int64, int)

GetAccumulatedChunks returns the accumulated response, TTFT, and chunk count for the deferred span. The response is built from the streaming accumulator during the final ProcessStreamingChunk call and stored on the DeferredSpanInfo. Returns nil response if no accumulated data is available (e.g., when no plugin calls ProcessStreamingChunk).

func (*Tracer) GetAccumulatedResponse added in v1.4.0 

func (t *Tracer) GetAccumulatedResponse(traceID string) *schemas.BifrostResponse

GetAccumulatedResponse returns a snapshot BifrostResponse built on demand from the accumulator's current chunks. See schemas.Tracer.GetAccumulatedResponse for full semantics.

func (*Tracer) GetAccumulator 

func (t *Tracer) GetAccumulator() *streaming.Accumulator

GetAccumulator returns the embedded streaming accumulator. This is useful for plugins that need direct access to accumulator methods.

func (*Tracer) GetDeferredSpanHandle 

func (t *Tracer) GetDeferredSpanHandle(traceID string) schemas.SpanHandle

GetDeferredSpanHandle retrieves a deferred span handle by trace ID. Returns nil if no deferred span exists for the given trace ID.

func (*Tracer) GetDeferredSpanID 

func (t *Tracer) GetDeferredSpanID(traceID string) string

GetDeferredSpanID returns the span ID for the deferred span. Returns empty string if no deferred span exists.

func (*Tracer) GetSpanHandleByID added in v1.3.9 

func (t *Tracer) GetSpanHandleByID(traceID string, spanID *string) schemas.SpanHandle

GetSpanHandleByID retrieves a span handle for the given trace and span ID. If spanID is nil, it returns a handle for the trace's root span.

func (*Tracer) HoldTraceFlush added in v1.11.0 

func (t *Tracer) HoldTraceFlush(traceID string) func()

HoldTraceFlush keeps CompleteAndFlushTrace from exporting the trace until the returned release runs, so a background writer (e.g. an output guardrail evaluating after the response was delivered) can still add spans to it. A flush requested while held runs on the last release. Unlike DeferTraceCompletion, the transport still completes the trace as usual; only the export waits. A trace that already ended gets a no-op release.

Take the hold while the request is still being handled (e.g. from a plugin hook), before the trace completes. A hold taken once completion has started does not delay the export, and spans written under it may be dropped. Closing that window would serialize every request's completion with admission, so it is left to the caller's ordering instead.

func (*Tracer) IsStreamEnded added in v1.4.0 

func (t *Tracer) IsStreamEnded(traceID string) bool

IsStreamEnded reports whether the gate for traceID is in the Ended state. See schemas.Tracer.IsStreamEnded for full semantics.

func (*Tracer) IsStreamPaused added in v1.4.0 

func (t *Tracer) IsStreamPaused(traceID string) bool

IsStreamPaused reports whether the gate for traceID is currently Paused. See schemas.Tracer.IsStreamPaused for full semantics.

func (*Tracer) IsTraceCompletionDeferred added in v1.9.0 

func (t *Tracer) IsTraceCompletionDeferred(traceID string) bool

Reports whether a worker still owns this trace.

func (*Tracer) MergeTraceDimensions added in v1.11.0 

func (t *Tracer) MergeTraceDimensions(traceID string, dims map[string]string)

MergeTraceDimensions adds dims to the trace's dimensions, overwriting a name already there.

func (*Tracer) ObservabilityDropCounts added in v1.5.5 

func (t *Tracer) ObservabilityDropCounts() map[string]int64

ObservabilityDropCounts returns, per observability plugin name, how many traces were skipped because that plugin was already at its concurrency cap. A non-zero and rising count means the connector's backend is unreachable or too slow to keep up.

func (*Tracer) PauseStream added in v1.4.0 

func (t *Tracer) PauseStream(traceID string)

PauseStream marks the active streaming response identified by traceID as paused. While paused, post-processed chunks are buffered (not delivered to the client) but PostLLMHooks continue to fire. Idempotent. No-op if no accumulator is associated.

func (*Tracer) PopulateLLMRequestAttributes 

func (t *Tracer) PopulateLLMRequestAttributes(handle schemas.SpanHandle, req *schemas.BifrostRequest)

PopulateLLMRequestAttributes populates all LLM-specific request attributes on the span.

func (*Tracer) PopulateLLMResponseAttributes 

func (t *Tracer) PopulateLLMResponseAttributes(ctx *schemas.BifrostContext, handle schemas.SpanHandle, resp *schemas.BifrostResponse, err *schemas.BifrostError)

PopulateLLMResponseAttributes populates all LLM-specific response attributes on the span.

func (*Tracer) ProcessStreamingChunk 

func (t *Tracer) ProcessStreamingChunk(ctx *schemas.BifrostContext, traceID string, isFinalChunk bool, result *schemas.BifrostResponse, err *schemas.BifrostError) *schemas.StreamAccumulatorResult

ProcessStreamingChunk processes a streaming chunk and accumulates it. Returns the accumulated result when isFinalChunk is true and the stream is complete; returns nil for non-final chunks. This method is used by plugins to access accumulated streaming data. Set isFinalChunk to indicate whether the current chunk is the last in the stream.

func (*Tracer) ReleaseTrace 

func (t *Tracer) ReleaseTrace(trace *schemas.Trace)

ReleaseTrace returns the trace to the pool for reuse. Should be called after EndTrace when the trace data is no longer needed.

func (*Tracer) ResetStreamAccumulator added in v1.9.0 

func (t *Tracer) ResetStreamAccumulator(traceID string)

ResetStreamAccumulator drops the chunks accumulated for the given trace ID so a retried stream attempt starts clean.

func (*Tracer) ResumeStream added in v1.4.0 

func (t *Tracer) ResumeStream(traceID string)

ResumeStream resumes a previously paused stream. Buffered chunks are flushed to the client in order, then live streaming continues. Idempotent.

func (*Tracer) ResumeStreamWithReplayInterval added in v1.5.3 

func (t *Tracer) ResumeStreamWithReplayInterval(traceID string, eventInterval time.Duration) bool

ResumeStreamWithReplayInterval arms fixed-interval replay after the in-flight chunk reaches the core gate.

func (*Tracer) SetAttribute 

func (t *Tracer) SetAttribute(handle schemas.SpanHandle, key string, value any)

SetAttribute sets an attribute on the span identified by the handle.

func (*Tracer) SetObservabilityPlugins added in v1.3.1 

func (t *Tracer) SetObservabilityPlugins(obsPlugins []schemas.ObservabilityPlugin, limits map[string]schemas.ObservabilityLimits)

SetObservabilityPlugins updates the plugins that receive completed traces. limits is keyed by plugin name (GetName()), sourced from each plugin's generic PluginConfig (schemas.PluginConfig.SemaphoreSize/InjectTimeout) — a plugin absent from the map, or with unset fields, gets the tracer's defaults. It also precomputes the deduplicated, normalized union of request-header patterns requested by those plugins so the per-request capture path is a single atomic load.

func (*Tracer) SetSpanStartTime added in v1.11.0 

func (t *Tracer) SetSpanStartTime(handle schemas.SpanHandle, start time.Time)

SetSpanStartTime moves the start time of the span identified by the handle.

func (*Tracer) SetTraceAttribute added in v1.3.19 

func (t *Tracer) SetTraceAttribute(traceID string, key string, value any)

SetTraceAttribute sets a trace-level attribute. Trace attributes are never exported as OTEL/Datadog span attributes; observability connectors read them directly off the completed trace.

func (*Tracer) SetTraceRedactionReplacements added in v1.4.4 

func (t *Tracer) SetTraceRedactionReplacements(traceID string, phase schemas.RedactionPhase, replacements map[string]string)

SetTraceRedactionReplacements stores phase-scoped connector-facing replacements on a trace.

func (*Tracer) SetTraceRequestHeaders added in v1.3.17 

func (t *Tracer) SetTraceRequestHeaders(traceID string, headers map[string]string)

SetTraceRequestHeaders filters the given request headers down to the union of patterns requested by observability plugins and stores the matched subset on the trace. Header keys are expected to be lowercased by the caller.

func (*Tracer) ShouldCaptureRequestHeaders added in v1.3.17 

func (t *Tracer) ShouldCaptureRequestHeaders() bool

ShouldCaptureRequestHeaders reports whether any observability plugin has opted into request-header capture (by implementing RequestHeaderPatterns). Derived from the cached pattern union computed in SetObservabilityPlugins, so there is no per-request recompute.

func (*Tracer) SignalTransportHandoff added in v1.9.0 

func (t *Tracer) SignalTransportHandoff(traceID string)

Reports that the transport is done, releasing the worker to complete the trace. Idempotent: the defer can run more than once.

func (*Tracer) SpanFromHandle added in v1.6.0 

func (t *Tracer) SpanFromHandle(handle schemas.SpanHandle) *schemas.Span

SpanFromHandle resolves the *Span for a handle once. Callers writing many attributes use it to avoid a trace+span lookup per attribute; span.SetAttribute is nil-safe, so a nil return is fine to write against.

func (*Tracer) StartSpan 

func (t *Tracer) StartSpan(ctx context.Context, name string, kind schemas.SpanKind) (context.Context, schemas.SpanHandle)

StartSpan creates a new span as a child of the current span in context. It reads the trace ID and parent span ID from context, creates the span, and returns an updated context with the new span ID.

Parent span resolution order: 1. BifrostContextKeySpanID - existing span in this service (for child spans) 2. BifrostContextKeyParentSpanID - incoming parent from W3C traceparent (for root spans) 3. No parent - creates a root span with no parent

func (*Tracer) StartSpanID added in v1.6.0 

func (t *Tracer) StartSpanID(ctx context.Context, name string, kind schemas.SpanKind) (string, schemas.SpanHandle)

StartSpanID creates a span exactly like StartSpan but returns the new span's ID instead of wrapping ctx in a context.WithValue node. Callers that only need the ID (e.g. to mirror it into a *BifrostContext via SetValue, as the plugin-hook pipeline does) use this to avoid a valueCtx allocation per span. Returns ("", nil) when there is no trace in ctx or span creation fails.

func (*Tracer) Stop 

func (t *Tracer) Stop()

Stop stops the tracer and releases its resources. This stops the internal TraceStore's cleanup goroutine.

func (*Tracer) StoreDeferredSpan 

func (t *Tracer) StoreDeferredSpan(traceID string, handle schemas.SpanHandle)

StoreDeferredSpan stores a span handle for later completion (used for streaming requests). The span handle is stored keyed by trace ID so it can be retrieved when the stream completes.

func (*Tracer) TransformPausedStreamBuffer added in v1.6.1 

func (t *Tracer) TransformPausedStreamBuffer(traceID string, transform schemas.PausedStreamBufferTransform) error

TransformPausedStreamBuffer forwards atomic rewrites of paused client chunks to the streaming accumulator.

func (*Tracer) WaitForFlusher added in v1.4.0 

func (t *Tracer) WaitForFlusher(traceID string)

WaitForFlusher blocks until the gate flusher for traceID has finished delivering buffered chunks (or aborted via ctx cancellation). Used by provider close paths to coordinate with paused streams. See schemas.Tracer.WaitForFlusher for full semantics.

type W3CTraceContext 

type W3CTraceContext struct {
	TraceID    string // 32 hex characters
	ParentID   string // 16 hex characters (span ID of parent)
	TraceFlags string // 2 hex characters
	TraceState string // Optional vendor-specific trace state
}

W3CTraceContext holds parsed W3C trace context values

func ExtractTraceContext 

func ExtractTraceContext(header *fasthttp.RequestHeader) *W3CTraceContext

ExtractTraceContext extracts full W3C trace context from headers

func ParseTraceparent 

func ParseTraceparent(traceparent string) *W3CTraceContext

ParseTraceparent parses a W3C traceparent header value Format: version-traceid-parentid-traceflags Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.