class LittleGhost::Tracing::OpenTelemetry

OpenTelemetry turns LittleGhost lifecycle notifications into GenAI spans and events. It brings agents, model calls, tools, workflows, and token usage into the same traces as the rest of an application.

LittleGhost.configure do |config|
  config.instrument LittleGhost::Tracing::OpenTelemetry.new
end

LittleGhost depends only on opentelemetry-api. Install and configure the desired SDK, processors, and exporters before registering this subscriber.

`Content` and trust

Prompts, responses, messages, tool arguments, and exception content are omitted by default. They appear only when Instrumentation has an explicit, scrubbed Support::ContentCapture policy.

Public Class Methods

new (tracer: nil)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 75
def initialize(tracer: nil)
  @tracer = tracer
  @entries = {}
  @mutex = Mutex.new
end

Uses tracer or the global tracer provider.

Public Instance Methods

emit (name, attributes)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 92
def emit(name, attributes)
  add_event(name.to_sym, prepare_attributes(:emit, name.to_sym, attributes))
end

Adds a structured event to the correlated active span.

finish (name, attributes)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 87
def finish(name, attributes)
  finish_span(name.to_sym, prepare_attributes(:finish, name.to_sym, attributes))
end

Finishes the span correlated by operation ID.

flush (timeout: nil)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 129
def flush(timeout: nil)
  provider = ::OpenTelemetry.tracer_provider
  provider.force_flush(timeout:) if provider.respond_to?(:force_flush)
end

Flushes through the configured tracer provider when supported.

shutdown (timeout: nil)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 135
def shutdown(timeout: nil)
  spans = @mutex.synchronize do
    current = @entries.values.map { |entry| entry.fetch(:span) }.uniq
    @entries = {}
    current
  end
  spans.each(&:finish)
end

Finishes spans still owned by this subscriber.

start (name, attributes)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 82
def start(name, attributes)
  start_span(name.to_sym, prepare_attributes(:start, name.to_sym, attributes))
end

Starts a span for a lifecycle operation.

trace_context (operation_id: nil, **)

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 97
def trace_context(operation_id: nil, **)
  span = @mutex.synchronize { @entries.dig(operation_id, :span) }
  context = span&.context
  return {} unless context&.valid?

  carrier = {}
  trace_context_propagator.inject(
    carrier,
    context: ::OpenTelemetry::Trace.context_with_span(span)
  )
  carrier.slice("traceparent", "tracestate").merge(trace_id: context.hex_trace_id)
rescue
  context&.valid? ? {trace_id: context.hex_trace_id} : {}
end

Supplies W3C propagation fields for an active operation when known.

with_span (name, attributes:, parent_operation_id: nil) { |span| ... }

Source

# File lib/little_ghost/tracing/open_telemetry.rb, line 114
def with_span(name, attributes:, parent_operation_id: nil)
  parent = @mutex.synchronize { @entries[parent_operation_id] }
  parent_context = parent && ::OpenTelemetry::Trace.context_with_span(parent.fetch(:span))
  options = {kind: :internal, attributes:}
  options[:with_parent] = parent_context if parent_context
  span = tracer.start_span(name, **options)
  yield span
rescue => error
  span.status = ::OpenTelemetry::Trace::Status.error(error.class.name) if span
  raise
ensure
  span&.finish
end

Wraps a block in a standalone internal span. Prefer lifecycle Instrumentation methods for normal framework operations.

class LittleGhost::Tracing::OpenTelemetry

Content and trust

`Content` and trust