Module: Tracebook::Adapters::RubyLLM

Extended by:
RubyLLM
Included in:
RubyLLM
Defined in:
lib/tracebook/adapters/ruby_llm.rb

Overview

Adapter for capturing LLM interactions via ActiveSupport::Notifications.

This adapter subscribes to instrumentation events (default: "ruby_llm.request") and automatically records interactions in TraceBook.

Examples:

Basic setup

# config/initializers/tracebook_adapters.rb
TraceBook::Adapters::RubyLLM.enable!

Custom event name

TraceBook::Adapters::RubyLLM.enable!(instrumentation: "my_llm.complete")

Emitting events from your LLM client

ActiveSupport::Notifications.instrument("ruby_llm.request", {
  provider: "openai",
  request: { model: "gpt-4o", messages: messages },
  response: response,
  meta: {
    project: "support",
    user: current_user,
    session_id: session.id,
    latency_ms: 150,
    status: :success,
    tags: ["production", "triage"]
  }
})

See Also:

Constant Summary collapse

DEFAULT_EVENT =

Default ActiveSupport::Notifications event name

"ruby_llm.request".freeze

Instance Method Summary collapse

Instance Method Details

#disable!(instrumentation: DEFAULT_EVENT) ⇒ void

This method returns an undefined value.

Disables the adapter and unsubscribes from events.

Examples:

TraceBook::Adapters::RubyLLM.disable!

Parameters:

  • instrumentation (String) (defaults to: DEFAULT_EVENT) —

    Event name to unsubscribe from



69
70
71
72
 
# File 'lib/tracebook/adapters/ruby_llm.rb', line 69

def disable!(instrumentation: DEFAULT_EVENT)
  token = subscribers.delete(instrumentation)
  ActiveSupport::Notifications.unsubscribe(token) if token
end

#enable!(instrumentation: DEFAULT_EVENT) ⇒ void

This method returns an undefined value.

Enables the adapter to start capturing events.

Subscribes to the specified instrumentation event and routes payloads through Mappers to Tracebook.record!.

Examples:

TraceBook::Adapters::RubyLLM.enable!
TraceBook::Adapters::RubyLLM.enable!(instrumentation: "custom.llm")

Parameters:

  • instrumentation (String) (defaults to: DEFAULT_EVENT) —

    Event name to subscribe to



53
54
55
56
57
58
59
60
 
# File 'lib/tracebook/adapters/ruby_llm.rb', line 53

def enable!(instrumentation: DEFAULT_EVENT)
  return if subscribers.key?(instrumentation)

  subscribers[instrumentation] = ActiveSupport::Notifications.subscribe(instrumentation) do |*args|
    event = ActiveSupport::Notifications::Event.new(*args)
    handle_payload(event.payload.with_indifferent_access)
  end
end

#handle_payload(payload) ⇒ Object (private) 



76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/tracebook/adapters/ruby_llm.rb', line 76

def handle_payload(payload)
  provider = payload[:provider].to_s.presence || "ruby_llm"
  normalized = Mappers.normalize(
    provider,
    raw_request: payload[:request],
    raw_response: payload[:response],
    meta: payload[:meta] || {}
  )

  TraceBook.record!(**normalized.to_h)
rescue KeyError => error
  Rails.logger.error("TraceBook RubyLLM adapter error: #{error.message}") if defined?(Rails)
end

#subscribers ⇒ Object (private) 



90
91
92
 
# File 'lib/tracebook/adapters/ruby_llm.rb', line 90

def subscribers
  @subscribers ||= {}
end