Troubleshooting - Braintrust

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.