Help us shape the future of Go! Take the 2026 Go Developer Survey

braintrust

package module
v0.0.1-beta.1 Latest Latest
Warning

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

 Go to latest Published: Nov 7, 2025 License: Apache-2.0 Imports: 10 Imported by: 17

README

Braintrust Go Tracing & Eval SDK

Go Reference Beta

Overview

This library provides tools for evaluating and tracing AI applications in Braintrust. Use it to:

  • Evaluate your AI models with custom test cases and scoring functions
  • Trace LLM calls and monitor AI application performance with OpenTelemetry
  • Integrate seamlessly with OpenAI, Anthropic, Google Gemini, LangChainGo, and other LLM providers

This SDK is currently in BETA status and APIs may change.

Installation

go get github.com/braintrustdata/braintrust-sdk-go

Quick Start

Set up your API key
export BRAINTRUST_API_KEY="your-api-key"
Evals
package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    "github.com/braintrustdata/braintrust-sdk-go/eval"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    bt, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
        braintrust.WithBlockingLogin(true),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Create evaluator
    evaluator := braintrust.NewEvaluator[string, string](bt)

    // Run an evaluation
    _, err = evaluator.Run(context.Background(), eval.Opts[string, string]{
        Experiment: "greeting-experiment",
        Dataset: eval.NewDataset([]eval.Case[string, string]{
            {Input: "World", Expected: "Hello World"},
            {Input: "Alice", Expected: "Hello Alice"},
        }),
        Task: eval.T(func(ctx context.Context, input string) (string, error) {
            return "Hello " + input, nil
        }),
        Scorers: []eval.Scorer[string, string]{
            eval.NewScorer("exact_match", func(ctx context.Context, taskResult eval.TaskResult[string, string]) (eval.Scores, error) {
                if taskResult.Expected == taskResult.Output {
                    return eval.S(1.0), nil
                }
                return eval.S(0.0), nil
            }),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
}
OpenAI Tracing
package main

import (
    "context"
    "log"

    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    traceopenai "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/openai"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    _, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Create OpenAI client with tracing middleware
    client := openai.NewClient(
        option.WithMiddleware(traceopenai.NewMiddleware()),
    )

    // Your OpenAI API calls will now be automatically traced
    _ = client // Use the client for your API calls
}
Anthropic Tracing
package main

import (
    "context"
    "log"

    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"

    "github.com/braintrustdata/braintrust-sdk-go"
    traceanthropic "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/anthropic"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    _, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Create Anthropic client with tracing middleware
    client := anthropic.NewClient(
        option.WithMiddleware(traceanthropic.NewMiddleware()),
    )

    // Your Anthropic API calls will now be automatically traced
    _ = client // Use the client for your API calls
}
Google Gemini Tracing
package main

import (
    "context"
    "log"
    "os"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/sdk/trace"
    "google.golang.org/genai"

    "github.com/braintrustdata/braintrust-sdk-go"
    tracegenai "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/genai"
)

func main() {
    // Set up OpenTelemetry tracer
    tp := trace.NewTracerProvider()
    defer tp.Shutdown(context.Background())
    otel.SetTracerProvider(tp)

    // Initialize Braintrust
    _, err := braintrust.New(tp,
        braintrust.WithProject("my-project"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Create Gemini client with tracing
    client, err := genai.NewClient(context.Background(), &genai.ClientConfig{
        HTTPClient: tracegenai.Client(),
        APIKey:     os.Getenv("GOOGLE_API_KEY"),
        Backend:    genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Your Gemini API calls will now be automatically traced
    _ = client // Use the client for your API calls
}
LangChainGo Integration

The SDK provides comprehensive tracing support for LangChainGo applications. Automatically trace LLM calls, chains, tools, agents, and retrievers by passing the Braintrust callback handler to your LangChainGo components. See examples/langchaingo for a simple getting started example, or examples/internal/langchaingo for a comprehensive demonstration of all features.

Features

  • Evaluations: Run systematic evaluations of your AI systems with custom scoring functions
  • Tracing: Automatic instrumentation for OpenAI, Anthropic, Google Gemini, and LangChainGo
  • Datasets: Manage and version your evaluation datasets
  • Experiments: Track different versions and configurations of your AI systems
  • Observability: Monitor your AI applications in production

Examples

Check out the examples/ directory for complete working examples:

  • evals - Create and run evaluations with custom test cases and scoring functions
  • openai - Automatically trace OpenAI API calls
  • anthropic - Automatically trace Anthropic API calls
  • genai - Automatically trace Google Gemini API calls
  • langchaingo - Trace LangChainGo applications (chains, tools, agents, retrievers)
  • datasets - Run evaluations using datasets stored in Braintrust

Documentation

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Documentation

Overview

Package braintrust provides the core Braintrust SDK for Go.

Braintrust is a platform for building reliable AI applications. This SDK provides tools for evaluation, experimentation, and observability of AI systems.

Main Packages

For AI model evaluations, see the eval package.

For distributed tracing and observability, see the trace package.

Configuration

The SDK reads configuration from environment variables. See [GetConfig] for a complete list of supported environment variables.

Learn More

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewEvaluator 

func NewEvaluator[I, R any](client *Client) *eval.Evaluator[I, R]

NewEvaluator creates a new evaluator for running multiple evaluations with the same input and output types.

Example: 

client, _ := braintrust.New(tp, braintrust.WithProject("my-project"))

// Create an evaluator for string → string evaluations
evaluator := braintrust.NewEvaluator[string, string](client)

// Run multiple evaluations
result1, _ := evaluator.Run(ctx, eval.Opts[string, string]{
    Experiment: "test-1",
    Cases:      cases1,
    Task:       task1,
    Scorers:    scorers,
})

result2, _ := evaluator.Run(ctx, eval.Opts[string, string]{
    Experiment: "test-2",
    Cases:      cases2,
    Task:       task2,
    Scorers:    scorers,
})

Types

type Client 

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

Client is the main Braintrust SDK client

func New 

func New(tp *trace.TracerProvider, opts ...Option) (*Client, error)

New creates a new Braintrust client with the provided TracerProvider.

The TracerProvider is required and should be managed by the caller. The client will NOT shut down the provider - you must do this yourself.

Configuration is loaded from environment variables first, then explicit options are applied (options take precedence).

Login happens asynchronously in the background by default.

Example: 

tp := trace.NewTracerProvider()
bt, err := braintrust.New(tp,
    braintrust.WithAPIKey("your-api-key"),
    braintrust.WithProject("my-project"),
)
if err != nil {
    log.Fatal(err)
}
defer tp.Shutdown(context.Background())

func (*Client) API 

func (c *Client) API() *api.API

API returns an API client for making direct calls to the Braintrust API. This provides low-level access to projects, datasets, experiments, and other resources.

Example: 

client, _ := braintrust.New(tp, braintrust.WithAPIKey("your-key"))

// Create a dataset
apiClient := client.API()
project, _ := apiClient.Projects().Register(ctx, "my-project")
dataset, _ := apiClient.Datasets().Create(ctx, api.DatasetRequest{
    ProjectID:   project.ID,
    Name:        "my-dataset",
    Description: "My test dataset",
})

func (c *Client) Permalink(span oteltrace.Span) string

Permalink returns a URL to the span in the Braintrust UI. If the permalink cannot be generated, it returns an empty string and logs a warning.

Example: 

client, _ := braintrust.New(tp, braintrust.WithAPIKey("your-key"))
tracer := client.Tracer("my-app")
ctx, span := tracer.Start(ctx, "my-operation")
defer span.End()

// Get the permalink
link := client.Permalink(span)
fmt.Println("View trace:", link)

func (*Client) String 

func (c *Client) String() string

String returns a string representation of the client

func (*Client) Tracer 

func (c *Client) Tracer(name string, opts ...oteltrace.TracerOption) oteltrace.Tracer

Tracer returns an OpenTelemetry Tracer with the given name. This is a convenience method equivalent to calling TracerProvider().Tracer(name, opts...).

Example: 

tracer := client.Tracer("my-app")
ctx, span := tracer.Start(ctx, "my-operation")
defer span.End()

func (*Client) TracerProvider 

func (c *Client) TracerProvider() *trace.TracerProvider

TracerProvider returns the OpenTelemetry TracerProvider used by this client. This can be used to create tracers or access the provider for advanced use cases.

type Option 

type Option func(*config.Config)

Option is a functional option for configuring a Braintrust client

func WithAPIKey 

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key (overrides BRAINTRUST_API_KEY)

func WithAPIURL 

func WithAPIURL(apiURL string) Option

WithAPIURL sets the API URL (overrides BRAINTRUST_API_URL)

func WithAppURL 

func WithAppURL(appURL string) Option

WithAppURL sets the app URL (overrides BRAINTRUST_APP_URL)

func WithBlockingLogin 

func WithBlockingLogin(enabled bool) Option

WithBlockingLogin enables synchronous login By default, login happens asynchronously in the background Set to true for tests or scripts where you need login to complete before proceeding

func WithExporter 

func WithExporter(exporter trace.SpanExporter) Option

WithExporter injects a custom OpenTelemetry SpanExporter If not provided, an OTLP HTTP exporter will be created automatically This is primarily useful for testing with a memory exporter

func WithFilterAISpans 

func WithFilterAISpans(enabled bool) Option

WithFilterAISpans enables filtering to keep only AI-related spans When enabled, only spans with AI-related names or attributes will be sent

func WithLogger 

func WithLogger(l logger.Logger) Option

WithLogger sets a custom logger for the SDK If not provided, a default logger will be used

func WithOrgName 

func WithOrgName(orgName string) Option

WithOrgName sets the organization name (overrides BRAINTRUST_ORG_NAME)

func WithProject 

func WithProject(projectName string) Option

WithProject sets the default project name (overrides BRAINTRUST_DEFAULT_PROJECT)

func WithProjectID 

func WithProjectID(projectID string) Option

WithProjectID sets the default project ID (overrides BRAINTRUST_DEFAULT_PROJECT_ID)

func WithSpanFilterFuncs 

func WithSpanFilterFuncs(filterFuncs ...config.SpanFilterFunc) Option

WithSpanFilterFuncs adds custom span filter functions Filters are evaluated in order. Return >0 to keep, <0 to drop, 0 to continue

Source Files

View all Source files

Directories

Path Synopsis
api
Package api provides a client for interacting with the Braintrust API.
 Package api provides a client for interacting with the Braintrust API.
datasets
Package datasets provides operations for managing Braintrust datasets.
 Package datasets provides operations for managing Braintrust datasets.
experiments
Package experiments provides operations for managing Braintrust experiments.
 Package experiments provides operations for managing Braintrust experiments.
functions
Package functions provides operations for managing Braintrust functions (prompts, tools, scorers).
 Package functions provides operations for managing Braintrust functions (prompts, tools, scorers).
projects
Package projects provides operations for managing Braintrust projects.
 Package projects provides operations for managing Braintrust projects.
btx module
Package config provides configuration management for the Braintrust SDK.
 Package config provides configuration management for the Braintrust SDK.
Package eval provides evaluation functionality for the Braintrust SDK.
 Package eval provides evaluation functionality for the Braintrust SDK.
examples module
anthropic command
This example demonstrates basic Anthropic tracing with Braintrust.
 This example demonstrates basic Anthropic tracing with Braintrust.
attachments command
Package main demonstrates manual attachment usage in Braintrust traces.
 Package main demonstrates manual attachment usage in Braintrust traces.
dataset-api command
datasets command
distributed-tracing command
Package main demonstrates distributed tracing using W3C baggage propagation.
 Package main demonstrates distributed tracing using W3C baggage propagation.
evals command
genai command
This example demonstrates basic Google Gemini tracing with Braintrust.
 This example demonstrates basic Google Gemini tracing with Braintrust.
internal/anthropic command
Anthropic kitchen sink - tests all the Anthropic features with minimal code
 Anthropic kitchen sink - tests all the Anthropic features with minimal code
internal/email-evals command
This is a realistic eval example.
 This is a realistic eval example.
internal/eval-updates command
This example demonstrates using the Update option to append results to an existing experiment.
 This example demonstrates using the Update option to append results to an existing experiment.
internal/rewrite command
manual-llm-logging command
openai command
This example demonstrates basic OpenAI tracing with Braintrust.
 This example demonstrates basic OpenAI tracing with Braintrust.
otel command
prompts command
This example demonstrates using a Braintrust prompt in an evaluation.
 This example demonstrates using a Braintrust prompt in an evaluation.
scorers command
internal
auth
Package auth provides authentication functionality for the Braintrust SDK.
 Package auth provides authentication functionality for the Braintrust SDK.
https
Package https provides a unified HTTP client for making API requests with centralized auth, error handling, and debug logging.
 Package https provides a unified HTTP client for making API requests with centralized auth, error handling, and debug logging.
logger
Package logger provides internal logging utilities.
 Package logger provides internal logging utilities.
oteltest
Package oteltest provides testing utilities for OpenTelemetry tracing.
 Package oteltest provides testing utilities for OpenTelemetry tracing.
tests
Package tests provides test utilities for creating test sessions and other test helpers.
 Package tests provides test utilities for creating test sessions and other test helpers.
Package logger provides logging interfaces and implementations for the Braintrust SDK.
 Package logger provides logging interfaces and implementations for the Braintrust SDK.
Package trace provides distributed tracing functionality for Braintrust experiments.
 Package trace provides distributed tracing functionality for Braintrust experiments.
attachment
Package attachment provides utilities for creating and managing attachments in Braintrust traces.
 Package attachment provides utilities for creating and managing attachments in Braintrust traces.
contrib/anthropic
Package anthropic provides OpenTelemetry middleware for tracing Anthropic API calls.
 Package anthropic provides OpenTelemetry middleware for tracing Anthropic API calls.
contrib/genai
Package genai provides OpenTelemetry tracing for Google Gemini API calls.
 Package genai provides OpenTelemetry tracing for Google Gemini API calls.
contrib/langchaingo
Package langchaingo provides OpenTelemetry tracing for LangChainGo applications.
 Package langchaingo provides OpenTelemetry tracing for LangChainGo applications.
contrib/openai
Package openai provides OpenTelemetry middleware for tracing OpenAI API calls.
 Package openai provides OpenTelemetry middleware for tracing OpenAI API calls.
internal
Package internal provides shared middleware functionality for OpenTelemetry tracers.
 Package internal provides shared middleware functionality for OpenTelemetry tracers.
contrib/a2a module
contrib/adk module
contrib/all module
contrib/bedrockruntime module
contrib/cloudwego/eino module
contrib/genkit module
contrib/github.com/sashabaranov/go-openai module

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.