trace

Documentation

Overview

Package trace provides distributed tracing functionality for Braintrust experiments.

This package is built on OpenTelemetry and integrates with the Braintrust Client for session-based authentication.

To enable tracing, create a TracerProvider and Braintrust client:

tp := trace.NewTracerProvider()
defer tp.Shutdown(context.Background())

bt, err := braintrust.New(tp,
    braintrust.WithAPIKey(os.Getenv("BRAINTRUST_API_KEY")),
    braintrust.WithProject("my-project"),
)
if err != nil {
    log.Fatal(err)
}

Once the client is created, create spans using OpenTelemetry:

tracer := bt.Tracer("my-app")
ctx, span := tracer.Start(ctx, "my-operation")
span.SetAttributes(attribute.String("user.id", "123"))
span.End()

Index

• Constants
• func AddSpanProcessor(tp *sdktrace.TracerProvider, session *auth.Session, cfg Config) error
• func GetSpanProcessor(session *auth.Session, cfg Config) (sdktrace.SpanProcessor, error)
• func Permalink(span oteltrace.Span) (string, error)
• func SetParent(ctx context.Context, parent Parent) context.Context
• type Config
• type Parent
  • func GetParent(ctx context.Context) (bool, Parent)
  • func NewParent(t ParentType, id string) Parent
  • func (p Parent) Attr() attribute.KeyValue
  • func (p Parent) String() string
• type ParentType
  • func (p ParentType) IsValid() bool
• type SpanFilterFunc

Constants

const ParentOtelAttrKey = "braintrust.parent"

ParentOtelAttrKey is the OpenTelemetry attribute key used to associate spans with Braintrust parents. This enables spans to be grouped under specific projects or experiments in the Braintrust platform. Parents are formatted as "project_id:{uuid}" or "experiment_id:{uuid}".

Functions

func AddSpanProcessor

func AddSpanProcessor(tp *sdktrace.TracerProvider, session *auth.Session, cfg Config) error

AddSpanProcessor creates and registers a Braintrust span processor.

func GetSpanProcessor

func GetSpanProcessor(session *auth.Session, cfg Config) (sdktrace.SpanProcessor, error)

GetSpanProcessor creates a Braintrust span processor.

func Permalink

func Permalink(span oteltrace.Span) (string, error)

Permalink returns a URL to the span in the Braintrust UI.

func SetParent

func SetParent(ctx context.Context, parent Parent) context.Context

SetParent will add a parent to the given context. Any span started with that context will be marked with that parent, and sent to the given project or experiment in Braintrust.

The parent is stored in both context values (for same-process access) and W3C baggage (for distributed tracing across process boundaries).

Example:

ctx = trace.SetParent(ctx, trace.Parent{Type: trace.ParentTypeProjectName, ID: "my-project"})
_, span := tracer.Start(ctx, "database-query")

Types

type Config

type Config struct {
	// Default parent for spans
	DefaultProjectID   string
	DefaultProjectName string

	// Span filtering
	FilterAISpans          bool
	EnableBuiltinAdkTraces bool // if false (default), drop spans from Google ADK (gcp.vertex.agent) to avoid duplicates
	SpanFilterFuncs        []SpanFilterFunc

	// Debug
	EnableTraceConsoleLog bool

	// Test override: provide custom exporter (e.g., memory exporter for tests)
	Exporter sdktrace.SpanExporter

	// Logger
	Logger logger.Logger
}

Config holds configuration for Braintrust tracing

type Parent

type Parent struct {
	Type ParentType
	ID   string
}

Parent represents where data goes in Braintrust - a project, an experiment, etc.

func GetParent

func GetParent(ctx context.Context) (bool, Parent)

GetParent returns the parent from the context and a boolean indicating if it was set. It first checks the context value (for same-process access), then falls back to baggage (for distributed tracing across process boundaries).

func NewParent

func NewParent(t ParentType, id string) Parent

NewParent creates a new parent with the given type and ID.

func (Parent) Attr

func (p Parent) Attr() attribute.KeyValue

Attr returns the OTel attribute for this parent.

func (Parent) String

func (p Parent) String() string

type ParentType

type ParentType string

ParentType represents the different places spans can be sent to in Braintrust - projects, experiments, etc.

const (
	// ParentTypeProjectName is the type of parent that represents a project by name.
	ParentTypeProjectName ParentType = "project_name"
	// ParentTypeProjectID is the type of parent that represents a project by ID.
	ParentTypeProjectID ParentType = "project_id"
	// ParentTypeExperimentID is the type of parent that represents an experiment by ID.
	ParentTypeExperimentID ParentType = "experiment_id"
)

func (ParentType) IsValid

func (p ParentType) IsValid() bool

IsValid returns true if the ParentType is a valid type.

type SpanFilterFunc

type SpanFilterFunc func(span sdktrace.ReadOnlySpan) int

SpanFilterFunc decides which spans to send to Braintrust. Return >0 to keep, <0 to drop, 0 to not influence.