Troubleshooting - Braintrust

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

This page outlines common issues when setting up and using the Braintrust Ruby SDK and how to resolve them.

No traces after adding braintrust/setup to the Gemfile

Verify that your app loads Bundler before application code:

require "bundler/setup"
Bundler.require

Rails applications do this during boot. Add it explicitly for Sinatra, Rack, and custom Ruby processes that do not load Bundler before application code. You can also require the setup file directly from an application initializer:

require "braintrust/setup"

No traces from a short-lived script

For scripts that exit immediately after an AI call, force OpenTelemetry to flush before the process exits:

OpenTelemetry.tracer_provider.shutdown

braintrust/setup also registers an exit hook by default. If BRAINTRUST_FLUSH_ON_EXIT=false is set, remove that setting or flush manually.

An integration is not being auto-instrumented

Confirm that the provider gem is installed and loaded in the process. Auto-instrumentation only patches integrations that are available when setup runs. You can instrument a provider explicitly after requiring it:

require "braintrust"
require "openai"

Braintrust.init(auto_instrument: false)
Braintrust.instrument!(:openai)

If you use integration filters, check BRAINTRUST_INSTRUMENT_ONLY, BRAINTRUST_INSTRUMENT_EXCEPT, braintrust exec --only, and braintrust exec --except.

Traces are written to the wrong project

Set the default project in the environment:

BRAINTRUST_DEFAULT_PROJECT="My project"

Or pass it when initializing the SDK:

Braintrust.init(default_project: "My project")

Debug setup and API errors

Enable SDK debug logging:

BRAINTRUST_DEBUG=true

The SDK logs setup failures, auto-instrumentation decisions, and API request errors to help identify missing API keys, login failures, or provider loading issues.