Install and instrument

​

Sign up

​

Install the SDK

gem "braintrust", require: "braintrust/setup"

gem install braintrust

bundle install

​

Set an API key

BRAINTRUST_API_KEY="your-api-key"

​

Set a project

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

BRAINTRUST_DEFAULT_PROJECT="My project"

Braintrust.init(default_project: "My project")

​

Configure tracing

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

• Auto-instrumentation
• Manual instrumentation

1

Initialize the SDK

Auto-instrumentation patches supported AI libraries before you make provider calls. Pick the setup style that fits your app:

Bundler applications

Add the SDK to your Gemfile with require: "braintrust/setup":

Gemfile

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

app.rb

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.

Rails

Add the SDK to your Gemfile with require: "braintrust/setup":

Gemfile

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:

config/initializers/braintrust.rb

require "braintrust/setup"

CLI wrapper

To instrument a Ruby process without changing application source code, install the gem and wrap the command with braintrust exec:

gem install braintrust
braintrust exec -- ruby app.rb
braintrust exec -- bundle exec rails server

Use --only or --except to filter integrations:

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.

1

Initialize Braintrust

Require the SDK and call Braintrust.init during application startup:

Initialize Braintrust

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::

Instrument OpenAI

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.

3

Create custom spans

The Ruby SDK uses OpenTelemetry. Wrap application work in spans to nest traced AI calls under your own operations:

Create a custom span

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

​

Next steps

• Instrument — trace LLM calls and application logic
• Observe — search and analyze production traces
• Annotate — label traces and build datasets
• Evaluate — measure quality and catch regressions
• Deploy — ship to production with the AI gateway