tracing

package
v1.2.19 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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 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 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 

func PopulateContextAttributes(
	attrs map[string]any,
	virtualKeyID, virtualKeyName string,
	selectedKeyID, selectedKeyName string,
	routingRuleID, routingRuleName string,
	teamID, teamName string,
	customerID, customerName string,
	numberOfRetries, fallbackIndex int,
)

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

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 struct {
	ID         string `json:"id,omitempty"`
	Transcript string `json:"transcript,omitempty"`
}

AudioSummary represents summarized audio data for tracing

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)
	AccumulatedChunks []*schemas.BifrostResponse // Accumulated streaming chunks
	// contains filtered or unexported fields
}

DeferredSpanInfo stores information about a deferred span for streaming requests

type MessageSummary 

type MessageSummary struct {
	Role             string                   `json:"role"`
	Content          string                   `json:"content"`
	ToolCalls        []ToolCallSummary        `json:"tool_calls,omitempty"`
	Reasoning        string                   `json:"reasoning,omitempty"`
	ReasoningDetails []ReasoningDetailSummary `json:"reasoning_details,omitempty"`
	Audio            *AudioSummary            `json:"audio,omitempty"`
	Refusal          string                   `json:"refusal,omitempty"`
}

MessageSummary represents a summarized chat message for tracing

type ReasoningDetailSummary 

type ReasoningDetailSummary struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

ReasoningDetailSummary represents a summarized reasoning detail for tracing

type ResponsesMessageSummary 

type ResponsesMessageSummary struct {
	Role      string `json:"role"`
	Content   string `json:"content"`
	Reasoning string `json:"reasoning,omitempty"`
}

ResponsesMessageSummary extends MessageSummary with reasoning

type ToolCallSummary 

type ToolCallSummary struct {
	ID   string `json:"id"`
	Type string `json:"type"`
	Name string `json:"name"`
	Args string `json:"args,omitempty"`
}

ToolCallSummary represents a summarized tool call for tracing

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 adds a streaming chunk to the deferred span's accumulated data

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) string

CreateTrace creates a new trace and stores it, returns trace ID only. The inheritedTraceID parameter is the trace ID from an incoming W3C traceparent header. If provided, this trace will use that ID to continue the distributed trace. If empty, a new trace ID will be generated. 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) ([]*schemas.BifrostResponse, int64)

GetAccumulatedData returns the accumulated chunks and TTFT for a deferred span

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) 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) 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 accumulates a streaming chunk for the deferred span. This stores the full BifrostResponse chunk for later reconstruction. Note: This method still uses the store for backward compatibility with existing code. For new code, prefer using ProcessStreamingChunk which uses the embedded accumulator.

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) 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) string

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

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) 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) GetAccumulatedChunks 

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

GetAccumulatedChunks returns the accumulated BifrostResponse, TTFT, and chunk count for a deferred span. It reconstructs a complete response from all accumulated streaming chunks. Note: This method still uses the store for backward compatibility with existing code. For new code, prefer using ProcessStreamingChunk which uses the embedded accumulator.

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) 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(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(traceID string, isFinalChunk bool, result *schemas.BifrostResponse, err *schemas.BifrostError) *schemas.StreamAccumulatorResult

ProcessStreamingChunk processes a streaming chunk and accumulates it. Returns the accumulated result. IsFinal will be true when the stream is complete. This method is used by plugins to access accumulated streaming data. The ctx parameter must contain the stream end indicator for proper final chunk detection.

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) 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) 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) 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.

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.