## Documentation Index

Fetch the complete documentation index at: [/docs/llms.txt](/content/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:

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

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

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

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

```bash
BRAINTRUST_DEFAULT_PROJECT="My project"
```

Or pass it when initializing the SDK:

```ruby
Braintrust.init(default_project: "My project")
```

### Debug setup and API errors

Enable SDK debug logging:

```bash
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.