> ## 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](/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, such as ad-hoc lookups and exploration from your IDE.

[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](/instrument/trace-application-logic)
</View>