> ## 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 Ruby 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/ruby/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 Ruby SDK requires Ruby 3.2 or later. Add the SDK to your project:

```ruby title="Gemfile" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
gem "braintrust", require: "braintrust/setup"
```

```bash title="Shell" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
gem install braintrust
```

If you add the SDK to a Gemfile, run:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bundle install
```

## 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 picks up your API key automatically, so remember to set it locally and in production. Keep it out of version control.

## Set a project

Traces are logged to a project that you name. There are two ways to set it:

* `BRAINTRUST_DEFAULT_PROJECT`, an environment variable you set alongside your API key.
* `default_project:`, an argument to `Braintrust.init`.

Which one to use depends on how you instrument your app. Auto-instrumentation through `braintrust/setup` or `braintrust exec` calls `Braintrust.init` for you, so set the environment variable on those paths. If you call `Braintrust.init` yourself, pass `default_project:` and keep the project name with the rest of your application configuration.

```bash title="Environment variable" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_DEFAULT_PROJECT="My project"
```

```ruby title="Braintrust.init" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
Braintrust.init(default_project: "My project")
```

## Configure tracing

There are two ways to instrument your app:

* **Auto-instrumentation** (recommended): The SDK automatically traces supported AI provider gems.
* **Manual instrumentation**: Initialize Braintrust yourself and instrument specific provider clients. Use this approach if you need precise control over when instrumentation runs.

> [tab] Auto-instrumentation
>
> **1. Initialize the SDK**
>
> Auto-instrumentation patches supported AI libraries before you make provider calls. Pick the setup style that fits your app:
>
> > [accordion] Bundler applications
> >
> > Add the SDK to your Gemfile with `require: "braintrust/setup"`:
> >
> > ```ruby title="Gemfile" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > # List provider gems before braintrust so Bundler loads them first.
> > gem "openai"
> > gem "braintrust", require: "braintrust/setup"
> > ```
> >
> > Make sure your application loads Bundler before requiring application code:
> >
> > ```ruby title="app.rb" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > require "bundler/setup"
> > Bundler.require
> > ```
> >
> > When `braintrust/setup` loads, it calls `Braintrust.init` and instruments the supported provider gems already loaded in the process. List provider gems before `braintrust` in your Gemfile so `Bundler.require` loads them first. Gems loaded after `braintrust/setup` runs are not instrumented.
>
> > [accordion] Rails
> >
> > Add the SDK to your Gemfile with `require: "braintrust/setup"`:
> >
> > ```ruby title="Gemfile" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > gem "braintrust", require: "braintrust/setup"
> > ```
> >
> > Rails loads Bundler during boot, so the setup file runs as the app starts. If you prefer an initializer, require the setup file there instead:
> >
> > ```ruby title="config/initializers/braintrust.rb" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > require "braintrust/setup"
> > ```
>
> > [accordion] CLI wrapper
> >
> > To instrument a Ruby process without changing application source code, install the gem and wrap the command with `braintrust exec`:
> >
> > ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > gem install braintrust
> > braintrust exec -- ruby app.rb
> > braintrust exec -- bundle exec rails server
> > ```
> >
> > Use `--only` or `--except` to filter integrations:
> >
> > ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> > braintrust exec --only openai,anthropic -- ruby app.rb
> > braintrust exec --except ruby_llm -- ruby app.rb
> > ```
> >
> > To filter integrations without changing the command, set `BRAINTRUST_INSTRUMENT_ONLY` or `BRAINTRUST_INSTRUMENT_EXCEPT` to a comma-separated list instead. These apply to the `braintrust/setup` path as well.
>
> **2. Find your AI provider**
>
> To learn more about what gets traced, find your AI provider in [SDK integrations](https://docs.braintrust.dev/sdks/ruby/sdk-integrations.md).

> [tab] Manual instrumentation
>
> **1. Initialize Braintrust**
>
> Require the SDK and call `Braintrust.init` during application startup:
>
> ```ruby title="Initialize Braintrust" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> require "braintrust"
>
> Braintrust.init(
>   default_project: "My project",
>   auto_instrument: false
> )
> ```
>
> Set `auto_instrument: false` when you plan to instrument clients explicitly.
>
> **2. Instrument a provider**
>
> Instrument every loaded client for an integration, or pass a specific client with `target:`:
>
> ```ruby title="Instrument OpenAI" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> require "openai"
>
> Braintrust.instrument!(:openai)
>
> client = OpenAI::Client.new
> Braintrust.instrument!(:openai, target: client)
> ```
>
> Supported integration names are `:anthropic`, `:openai`, `:ruby_openai`, `:ruby_llm`, and `:roast`.
>
> **3. Create custom spans**
>
> The Ruby SDK uses OpenTelemetry. Wrap application work in spans to nest traced AI calls under your own operations:
>
> ```ruby title="Create a custom span" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> tracer = OpenTelemetry.tracer_provider.tracer("my-app")
>
> tracer.in_span("process-request") do |span|
>   span.set_attribute("user.id", user_id)
>   output = answer_question("Write a haiku about evals")
>   span.set_attribute("app.output", output)
> end
> ```

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