> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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](/sdks/go/quickstart).</Note>

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

<Tabs defaultTabIndex={0} sync={false} className="tabs-border">
  <Tab title="Auto-instrumentation">
    <Steps>
      <Step title="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.
        }
        ```
      </Step>

      <Step title="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
        ```

        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/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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Find your AI provider">
        To learn more about what gets traced, find your AI provider in [SDK integrations](/sdks/go/sdk-integrations).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual instrumentation">
    <Steps>
      <Step title="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)
          }
        }
        ```
      </Step>

      <Step title="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))
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<Check>If traces appear in Braintrust, you've successfully set up the SDK.</Check>

If your traces don't appear in Braintrust, see [Troubleshooting](/sdks/go/troubleshooting).

## Next steps

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

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