> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and instrument

> Install the Go SDK, set an API key, and configure tracing by hand.

> [!NOTE]
>
> To use an agent for automatic setup, see the [Quickstart](https://docs.braintrust.dev/sdks/go/quickstart.md).

## Sign up

If you don't have a Braintrust account, sign up for free at [braintrust.dev](https://www.braintrust.dev/signup).

## Install the SDK

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
go get github.com/braintrustdata/braintrust-sdk-go
```

## Set an API key

Create an API key in [API key settings](https://www.braintrust.dev/app/~/settings/api-keys) and set it as an environment variable:

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

> [tab] Auto-instrumentation
>
> **1. Initialize Braintrust**
>
> Set up OpenTelemetry and create a Braintrust client during application startup:
>
> ```go title="main.go" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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.
> }
> ```
>
> **2. Add Orchestrion and provider integrations**
>
> Orchestrion instruments supported provider calls at build time. Install a pinned Orchestrion version:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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
> go get github.com/braintrustdata/braintrust-sdk-go/trace/contrib/a2a
> ```
>
> Add a tools file in the same directory as your `go.mod`. Prefer importing only the integrations your app uses:
>
> ```go title="orchestrion.tool.go" #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> //go:build tools
>
> package main
>
> import (
>   _ "github.com/DataDog/orchestrion"
>   _ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/a2a"
>   _ "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.
>
> **3. 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:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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.
>
> **4. Find your AI provider**
>
> To learn more about what gets traced, find your AI provider in [SDK integrations](https://docs.braintrust.dev/sdks/go/sdk-integrations.md).

> [tab] Manual instrumentation
>
> **1. Initialize Braintrust**
>
> Set up OpenTelemetry and create a Braintrust client during application startup:
>
> ```go title="Initialize Braintrust" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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)
>   }
> }
> ```
>
> **2. Create custom spans**
>
> The Go SDK uses OpenTelemetry. Wrap application work in spans to nest traced AI calls under your own operations:
>
> ```go title="Create a custom span" #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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](https://www.braintrust.dev/app/~/logs), usually within seconds.

> [!TIP]
>
> If traces appear in Braintrust, you've successfully set up the SDK.

If your traces don't appear in Braintrust, see [Troubleshooting](https://docs.braintrust.dev/sdks/go/troubleshooting.md).

## Next steps

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

* [Instrument](https://docs.braintrust.dev/instrument.md) — trace LLM calls and application logic
* [Observe](https://docs.braintrust.dev/observe.md) — search and analyze production traces
* [Annotate](https://docs.braintrust.dev/annotate.md) — label traces and build datasets
* [Evaluate](https://docs.braintrust.dev/evaluate.md) — measure quality and catch regressions
* [Deploy](https://docs.braintrust.dev/deploy.md) — ship to production with the AI gateway


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.