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

# RubyLLM

> Trace RubyLLM applications in Braintrust to debug prompts, evaluate models, and monitor production usage

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[RubyLLM](https://rubyllm.com) is a Ruby gem that provides a unified interface for AI providers including OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Mistral. Braintrust traces chat completions, tool executions, and streaming responses across whichever provider you route through.

<View title="Ruby" icon="https://img.logo.dev/ruby-lang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-ruby">
    Setup
  </h2>

  Install the Braintrust and RubyLLM gems, then configure your API keys.

  <Steps>
    <Step title="Install gems">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      gem install braintrust ruby_llm
      ```
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=your-api-key
      BRAINTRUST_DEFAULT_PROJECT=your-project-name  # Project that spans are logged to

      # Configure your preferred provider(s)
      OPENAI_API_KEY=your-openai-key
      # ANTHROPIC_API_KEY=your-anthropic-key
      # GOOGLE_API_KEY=your-google-key
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-ruby">
    Auto-instrumentation
  </h2>

  To trace RubyLLM without modifying how you construct chats, load `braintrust/setup` before you require `ruby_llm`. Braintrust intercepts the `require` and patches `RubyLLM::Chat`, so every chat, tool, and streaming call emits a span. Loading `braintrust/setup` also initializes Braintrust for you and logs to the project set by `BRAINTRUST_DEFAULT_PROJECT`.

  <CodeGroup>
    ```ruby app.rb theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    require 'braintrust/setup'
    require 'ruby_llm'

    # Configure RubyLLM with your provider
    RubyLLM.configure do |config|
      config.openai_api_key = ENV['OPENAI_API_KEY']
    end

    # Create a chat and make requests (traced automatically)
    chat = RubyLLM.chat(model: 'gpt-4o-mini')
    response = chat.ask('What is machine learning?')

    puts response.content
    ```
  </CodeGroup>

  <Tip>
    In a Rails app, add `gem "braintrust", require: "braintrust/setup"` to your Gemfile to enable auto-instrumentation without an explicit `require` line.
  </Tip>

  <h2 id="manual-instrumentation-ruby">
    Manual instrumentation
  </h2>

  To trace RubyLLM calls manually, enable instrumentation yourself with `Braintrust.instrument!(:ruby_llm)`. Once enabled, every chat, tool, and streaming call emits a span. The following `app.rb` initializes Braintrust, instruments RubyLLM, and makes a request:

  <CodeGroup>
    ```ruby app.rb theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    require 'braintrust'
    require 'ruby_llm'

    # Initialize Braintrust
    Braintrust.init(default_project: 'My Project')

    # Enable Braintrust tracing for RubyLLM
    Braintrust.instrument!(:ruby_llm)

    # Configure RubyLLM with your provider
    RubyLLM.configure do |config|
      config.openai_api_key = ENV['OPENAI_API_KEY']
    end

    # Create a chat and make requests (traced)
    chat = RubyLLM.chat(model: 'gpt-4o-mini')
    response = chat.ask('What is machine learning?')

    puts response.content
    ```
  </CodeGroup>

  To instrument a single chat instead of every RubyLLM chat, pass the instance as a `target`: `Braintrust.instrument!(:ruby_llm, target: chat)`.

  <h2 id="what-traced-ruby">
    What Braintrust traces
  </h2>

  Braintrust captures:

  * Chat completion spans (`ruby_llm.chat`), with input messages, the model, and provider metadata, plus the assistant response and finish reason.
  * Tool execution spans (`ruby_llm.tool.<name>`), with the tool name, call ID, arguments, and returned result. Tool schemas passed to the model are captured on the chat span.
  * Token usage metrics (prompt, completion, total, and cached tokens) for chat completions.
  * Streaming responses, aggregated onto the chat span with time to first token.
  * Multimodal message content, including text with image and file attachments.
  * Errors, recorded on the span when a request raises.

  <h2 id="resources-ruby">
    Resources
  </h2>

  * [RubyLLM documentation](https://rubyllm.com)
  * [RubyLLM tracing example](https://github.com/braintrustdata/braintrust-sdk-ruby/blob/main/examples/contrib/ruby_llm.rb)
  * [Braintrust Ruby SDK](https://github.com/braintrustdata/braintrust-sdk-ruby)
  * [Trace application logic](/docs/instrument/trace-application-logic)
</View>