Class: Phronomy::Tracing::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/tracing/base.rb

Overview

Abstract tracer.

To integrate a tracing backend (OpenTelemetry, Langfuse, etc.), subclass this and override #start_span and #finish_span. Then assign your tracer in the Phronomy configuration:

Phronomy.configure do |c| c.tracer = MyTracer.new end

The tracer is then automatically used by Chain and Agent components via the #trace helper.

Direct Known Subclasses

LangfuseTracer, NullTracer, OpenTelemetryTracer

Instance Method Summary collapse

Instance Method Details

#finish_span(span, output: nil, usage: nil, error: nil) ⇒ Object

Finish a span after execution completes.

Parameters:

  • span (Object) —

    the span returned by #start_span

  • output (Object, nil) (defaults to: nil) —

    successful output value

  • usage (Phronomy::TokenUsage, nil) (defaults to: nil) —

    token usage for this span

  • error (Exception, nil) (defaults to: nil) —

    exception if the block raised

Raises:

  • (NotImplementedError) 


53
54
55
 
# File 'lib/phronomy/tracing/base.rb', line 53

def finish_span(span, output: nil, usage: nil, error: nil)
  raise NotImplementedError, "#{self.class}#finish_span is not implemented"
end

#start_span(name, **attributes) ⇒ Object

Start a new span. Must return an object that will be passed to #finish_span.

Parameters:

  • name (String)
  • attributes (Hash)

Returns:

  • (Object) —

    an opaque span handle

Raises:

  • (NotImplementedError) 


43
44
45
 
# File 'lib/phronomy/tracing/base.rb', line 43

def start_span(name, **attributes)
  raise NotImplementedError, "#{self.class}#start_span is not implemented"
end

#trace(name, input: nil, **meta) {|span| ... } ⇒ Object

Wraps a block in a span. Yields the span to the block. Calls #finish_span with the output on success or with the error on failure.

Parameters:

  • name (String) —

    span / trace name

  • input (Object) (defaults to: nil) —

    the input being processed

  • meta (Hash) —

    additional metadata attached to the span

Yields:

  • (span) —

    the active span object

Returns:

  • (Object) —

    the block's return value



28
29
30
31
32
33
34
35
36
 
# File 'lib/phronomy/tracing/base.rb', line 28

def trace(name, input: nil, **meta)
  span = start_span(name, input: input, **meta)
  result, usage = yield span
  finish_span(span, output: result, usage: usage)
  result
rescue => e
  finish_span(span, error: e)
  raise
end