Install and instrument

To use an agent for automatic setup, see the Quickstart.

If you don’t have a Braintrust account, sign up for free at braintrust.dev.

Install the SDK

The Braintrust Go SDK requires Go 1.25 or later. Add the SDK to your module:

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

Set an API key

Create an API key in API key settings and set it as an environment variable:

.env

BRAINTRUST_API_KEY="your-api-key"

The SDK reads BRAINTRUST_API_KEY from the environment. Keep it out of version control.

Configure tracing

There are two ways to instrument your app:

Auto-instrumentation (recommended): Build and run your application with Orchestrion so supported AI provider calls are traced automatically.
Manual instrumentation: Initialize Braintrust yourself and create OpenTelemetry spans around application work. Use this approach if you need precise custom spans or if your provider is not supported by auto-instrumentation.

Auto-instrumentation
Manual instrumentation

Initialize Braintrust

Set up OpenTelemetry and create a Braintrust client during application startup:

main.go

package main

import (
  "log"

  "github.com/braintrustdata/braintrust-sdk-go"
  "go.opentelemetry.io/otel"
  "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
  tp := trace.NewTracerProvider()
  otel.SetTracerProvider(tp)

  _, err := braintrust.New(tp, braintrust.WithProject("My project"))
  if err != nil {
    log.Fatal(err)
  }

  // Run your application.
}

Add Orchestrion and provider integrations

Orchestrion instruments supported provider calls at build time. Install a pinned Orchestrion version:

go list -m -versions github.com/DataDog/orchestrion
go install github.com/DataDog/orchestrion@vX.Y.Z

Then install and import the integrations your app uses. Each integration is its own Go module:

go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/openai
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/anthropic
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/bedrockruntime
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/genai
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/genkit
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/adk
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/cloudwego/eino
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/langchaingo
go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/github.com/sashabaranov/go-openai

Add a tools file in the same directory as your go.mod. Prefer importing only the integrations your app uses:

orchestrion.tool.go

//go:build tools

package main

import (
  _ "github.com/DataDog/orchestrion"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/adk"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/anthropic"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/bedrockruntime"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/cloudwego/eino"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/genai"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/genkit"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/github.com/sashabaranov/go-openai"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/langchaingo"
  _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/openai"
)

If your app uses many supported integrations, install and import github.com/braintrustdata/braintrust-sdk-go/trace/contrib/all instead.

Persist Orchestrion in your build and run path

Auto-instrumentation only works when your app is built or run through Orchestrion. Update the commands your team and CI use, for example:

orchestrion go run .
orchestrion go build ./...
orchestrion go test ./...

If your project uses a Makefile, Dockerfile, CI workflow, or checked-in script, update that normal path instead of relying on a one-off local command.

Find your AI provider

To learn more about what gets traced, find your AI provider in SDK integrations.

Initialize Braintrust

Set up OpenTelemetry and create a Braintrust client during application startup:

Initialize Braintrust

package main

import (
  "log"

  "github.com/braintrustdata/braintrust-sdk-go"
  "go.opentelemetry.io/otel"
  "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
  tp := trace.NewTracerProvider()
  otel.SetTracerProvider(tp)

  _, err := braintrust.New(tp, braintrust.WithProject("My project"))
  if err != nil {
    log.Fatal(err)
  }
}

Create custom spans

The Go SDK uses OpenTelemetry. Wrap application work in spans to nest traced AI calls under your own operations:

Create a custom span

ctx, span := otel.Tracer("my-app").Start(ctx, "process-request")
defer span.End()

span.SetAttributes(attribute.String("user.id", userID))
output := answerQuestion(ctx, "Write a haiku about evals")
span.SetAttributes(attribute.String("app.output", output))

Verify tracing

Run your app and make an AI call. A trace will show up in your Braintrust Logs, usually within seconds.

If traces appear in Braintrust, you’ve successfully set up the SDK.

If your traces don’t appear in Braintrust, see Troubleshooting.

Next steps

Learn more about using the SDK to observe, evaluate, and improve your AI application:

Instrument — trace LLM calls and application logic
Observe — search and analyze production traces
Annotate — label traces and build datasets
Evaluate — measure quality and catch regressions
Deploy — ship to production with the AI gateway

​Sign up

​Install the SDK

​Set an API key

​Configure tracing

​Verify tracing

​Next steps

Sign up

Install the SDK

Set an API key

Configure tracing

Verify tracing

Next steps