> ## 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 Ruby SDK, set an API key, and configure tracing by hand.

<Note>To use an agent for automatic setup, see the [Quickstart](/sdks/ruby/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

Add the Braintrust SDK to your project:

<CodeGroup>
  ```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
  ```
</CodeGroup>

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"
BRAINTRUST_DEFAULT_PROJECT="My project"
```

The SDK picks up your API key automatically, so remember to set it locally and in production. Keep it out of version control.

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

<Tabs defaultTabIndex={0} sync={false} className="tabs-border">
  <Tab title="Auto-instrumentation">
    <Steps>
      <Step title="Initialize the SDK">
        Auto-instrumentation patches supported AI libraries before you make provider calls. Pick the setup style that fits your app:

        <AccordionGroup>
          <Accordion title="Bundler applications" icon="https://img.logo.dev/ruby-lang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
            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>

          <Accordion title="Rails" icon="https://img.logo.dev/rubyonrails.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
            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>

          <Accordion title="CLI wrapper" icon="terminal">
            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
            ```
          </Accordion>
        </AccordionGroup>
      </Step>

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

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

      <Step title="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`, and `:ruby_llm`.
      </Step>

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