Module: Braintrust::Contrib

Defined in:
lib/braintrust/contrib.rb,
lib/braintrust/contrib/setup.rb,
lib/braintrust/contrib/context.rb,
lib/braintrust/contrib/patcher.rb,
lib/braintrust/contrib/registry.rb,
lib/braintrust/contrib/integration.rb,
lib/braintrust/contrib/support/otel.rb,
lib/braintrust/contrib/rails/railtie.rb,
lib/braintrust/contrib/openai/patcher.rb,
lib/braintrust/contrib/support/openai.rb,
lib/braintrust/contrib/ruby_llm/patcher.rb,
lib/braintrust/contrib/anthropic/patcher.rb,
lib/braintrust/contrib/openai/integration.rb,
lib/braintrust/contrib/rails/server/engine.rb,
lib/braintrust/contrib/ruby_openai/patcher.rb,
lib/braintrust/contrib/ruby_llm/integration.rb,
lib/braintrust/contrib/anthropic/integration.rb,
lib/braintrust/contrib/rails/server/generator.rb,
lib/braintrust/contrib/ruby_openai/integration.rb,
lib/braintrust/contrib/openai/instrumentation/chat.rb,
lib/braintrust/contrib/rails/server/eval_controller.rb,
lib/braintrust/contrib/rails/server/list_controller.rb,
lib/braintrust/contrib/openai/instrumentation/common.rb,
lib/braintrust/contrib/ruby_llm/instrumentation/chat.rb,
lib/braintrust/contrib/rails/server/health_controller.rb,
lib/braintrust/contrib/ruby_llm/instrumentation/common.rb,
lib/braintrust/contrib/anthropic/instrumentation/common.rb,
lib/braintrust/contrib/openai/instrumentation/responses.rb,
lib/braintrust/contrib/ruby_openai/instrumentation/chat.rb,
lib/braintrust/contrib/anthropic/instrumentation/messages.rb,
lib/braintrust/contrib/openai/instrumentation/moderations.rb,
lib/braintrust/contrib/ruby_openai/instrumentation/common.rb,
lib/braintrust/contrib/rails/server/application_controller.rb,
lib/braintrust/contrib/ruby_openai/instrumentation/responses.rb,
lib/braintrust/contrib/anthropic/instrumentation/beta_messages.rb,
lib/braintrust/contrib/ruby_openai/instrumentation/moderations.rb

Overview

Contrib framework for auto-instrumentation integrations. Provides a consistent interface for all integrations and enables reliable auto-instrumentation in later milestones.

Defined Under Namespace

Modules: Anthropic, Integration, OpenAI, Rails, RequireHook, RubyLLM, RubyOpenAI, Setup, Support Classes: Context, Patcher, Registry

Class Method Summary collapse

Class Method Details

.auto_instrument!(only: nil, except: nil) ⇒ Array<Symbol>

Auto-instrument available integrations. Discovers which integrations have their target libraries loaded and instruments them automatically.

Examples:

Instrument all available

Braintrust::Contrib.auto_instrument!

Only specific integrations

Braintrust::Contrib.auto_instrument!(only: [:openai, :anthropic])

Exclude specific integrations

Braintrust::Contrib.auto_instrument!(except: [:ruby_llm])

Parameters:

  • only (Array<Symbol>) (defaults to: nil) —

    whitelist - only instrument these

  • except (Array<Symbol>) (defaults to: nil) —

    blacklist - skip these

Returns:

  • (Array<Symbol>) —

    names of integrations that were instrumented



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/braintrust/contrib.rb', line 118

def auto_instrument!(only: nil, except: nil)
  if only || except
    Braintrust::Log.debug("auto_instrument! called (only: #{only.inspect}, except: #{except.inspect})")
  else
    Braintrust::Log.debug("auto_instrument! called")
  end

  targets = registry.available
  Braintrust::Log.debug("auto_instrument! available: #{targets.map(&:integration_name).inspect}")
  targets = targets.select { |i| only.include?(i.integration_name) } if only
  targets = targets.reject { |i| except.include?(i.integration_name) } if except

  results = targets.each_with_object([]) do |integration, instrumented|
    result = instrument!(integration.integration_name)
    # Note: false means skipped (not applicable) or failed (error logged at lower level)
    Braintrust::Log.debug("auto_instrument! :#{integration.integration_name} #{result ? "instrumented" : "skipped"}")
    instrumented << integration.integration_name if result
  end
  Braintrust::Log.debug("auto_instrument! complete: #{results.inspect}")
  results
end

.context_for(target) ⇒ Context?

Get the context for a target object.

Parameters:

  • target (Object) —

    The object to retrieve context from

Returns:

  • (Context, nil) —

    The context if found, nil otherwise



172
173
174
 
# File 'lib/braintrust/contrib.rb', line 172

def context_for(target)
  Context.from(target)
end

.default_tracer_provider ⇒ OpenTelemetry::Trace::TracerProvider

Get the default tracer provider, falling back to OpenTelemetry global.

Returns:

  • (OpenTelemetry::Trace::TracerProvider) 


165
166
167
 
# File 'lib/braintrust/contrib.rb', line 165

def default_tracer_provider
  @default_tracer_provider || ::OpenTelemetry.tracer_provider
end

.init(tracer_provider: nil) ⇒ void

This method returns an undefined value.

Initialize the contrib framework with optional configuration.

Parameters:

  • tracer_provider (OpenTelemetry::SDK::Trace::TracerProvider, nil) (defaults to: nil) —

    Optional tracer provider



98
99
100
 
# File 'lib/braintrust/contrib.rb', line 98

def init(tracer_provider: nil)
  @default_tracer_provider = tracer_provider
end

.instrument!(name, **options) ⇒ Boolean

Instrument a registered integration by name.

Examples:

Instrument all OpenAI clients

Braintrust::Contrib.instrument!(:openai)

Instrument specific OpenAI client instance

client = OpenAI::Client.new
Braintrust::Contrib.instrument!(:openai, target: client, tracer_provider: my_provider)

Parameters:

  • name (Symbol) —

    The integration name (e.g., :openai, :anthropic)

  • options (Hash) —

    Optional configuration

Options Hash (**options):

  • :target (Object) —

    Optional target instance to instrument specifically

  • :tracer_provider (OpenTelemetry::SDK::Trace::TracerProvider) —

    Optional tracer provider

Returns:

  • (Boolean) —

    true if instrumentation succeeded



154
155
156
157
158
159
160
161
 
# File 'lib/braintrust/contrib.rb', line 154

def instrument!(name, **options)
  if (integration = registry[name])
    integration.instrument!(**options)
  else
    Braintrust::Log.error("No integration for '#{name}' is defined!")
    false
  end
end

.registry ⇒ Registry

Get the global registry instance.

Returns:



91
92
93
 
# File 'lib/braintrust/contrib.rb', line 91

def registry
  Registry.instance
end

.tracer_for(target, name: "braintrust") ⇒ OpenTelemetry::Trace::Tracer

Get a tracer for a target, using its context’s tracer_provider if available.

Parameters:

  • target (Object) —

    The object to look up context from

  • name (String) (defaults to: "braintrust") —

    Tracer name

Returns:

  • (OpenTelemetry::Trace::Tracer) 


188
189
190
 
# File 'lib/braintrust/contrib.rb', line 188

def tracer_for(target, name: "braintrust")
  tracer_provider_for(target).tracer(name)
end

.tracer_provider_for(target) ⇒ OpenTelemetry::Trace::TracerProvider

Get the tracer provider for a target. Checks target’s context first, then falls back to contrib default.

Parameters:

  • target (Object) —

    The object to look up tracer provider for

Returns:

  • (OpenTelemetry::Trace::TracerProvider) 


180
181
182
 
# File 'lib/braintrust/contrib.rb', line 180

def tracer_provider_for(target)
  context_for(target)&.[](:tracer_provider) || default_tracer_provider
end