Class: ActiveAgent::Telemetry::Tracer

Inherits:
Object
  • Object
show all
Defined in:
lib/active_agent/telemetry/tracer.rb

Overview

Manages trace creation and lifecycle on the activeagents-telemetry core: builds an ActiveAgents::Telemetry::Trace per unit of work, tracks the current span in thread-local storage, and hands finished traces to the Reporter.

Examples:

tracer = Tracer.new(configuration)
tracer.trace("MyAgent.greet") do |span|
  span.set_attribute("user_id", 123)
  span.add_span("llm.generate", span_type: :llm)
end

Constant Summary collapse

CURRENT_SPAN_KEY =

Thread-local storage for current trace context

:active_agent_telemetry_current_span

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(configuration) ⇒ Tracer

Returns a new instance of Tracer.



26
27
28
29
 
# File 'lib/active_agent/telemetry/tracer.rb', line 26

def initialize(configuration)
  @configuration = configuration
  @reporter = Reporter.new(configuration)
end

Instance Attribute Details

#configuration ⇒ Configuration (readonly)

Returns Telemetry configuration.

Returns:



18
19
20
 
# File 'lib/active_agent/telemetry/tracer.rb', line 18

def configuration
  @configuration
end

#reporter ⇒ Reporter (readonly)

Returns The reporter for sending traces.

Returns:

  • (Reporter) —

    The reporter for sending traces



21
22
23
 
# File 'lib/active_agent/telemetry/tracer.rb', line 21

def reporter
  @reporter
end

Instance Method Details

#current_span ⇒ Span?

Returns the current span from thread-local storage.

Returns:

  • (Span, nil) —

    Current span or nil



93
94
95
 
# File 'lib/active_agent/telemetry/tracer.rb', line 93

def current_span
  Thread.current[CURRENT_SPAN_KEY]
end

#flush ⇒ void

This method returns an undefined value.

Flushes buffered traces and waits for delivery to complete, so callers (tests, rails runner, job shutdown) can rely on the traces having been delivered/stored when this returns.



102
103
104
 
# File 'lib/active_agent/telemetry/tracer.rb', line 102

def flush
  reporter.flush
end

#shutdown ⇒ void

This method returns an undefined value.

Shuts down the tracer and reporter.



109
110
111
 
# File 'lib/active_agent/telemetry/tracer.rb', line 109

def shutdown
  reporter.shutdown
end

#span(name, **attributes) ⇒ Span

Creates a standalone span (not within a trace block).

Parameters:

  • name (String) —

    Span name

  • attributes (Hash) —

    Span attributes

Returns:

  • (Span) —

    The created span



78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/active_agent/telemetry/tracer.rb', line 78

def span(name, **attributes)
  return Telemetry::NullSpan.new unless should_trace?

  span_type = attributes.delete(:span_type) || :root
  current = current_span
  if current
    current.add_span(name, span_type: span_type, **attributes)
  else
    Span.new(name, trace_id: SecureRandom.hex(16), span_type: span_type, **default_attributes.merge(attributes))
  end
end

#trace(name, **attributes) {|span| ... } ⇒ Object

Creates and executes a new trace.

Callers may supply the trace id (instrumentation passes the generation's prompt_options) so external records — e.g. solid_agent's persisted generations — can correlate with this trace; otherwise one is generated.

Parameters:

  • name (String) —

    Trace name (typically "AgentClass.action")

  • attributes (Hash) —

    Root span attributes; :trace_id and :span_type are extracted rather than recorded

Yields:

  • (span) —

    Yields the root span for adding child spans

Returns:

  • (Object) —

    Result of the block



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/active_agent/telemetry/tracer.rb', line 43

def trace(name, **attributes)
  return yield(Telemetry::NullSpan.new) unless should_trace?

  trace_id = attributes.delete(:trace_id) || SecureRandom.hex(16)
  span_type = attributes.delete(:span_type) || :root

  trace = build_trace(trace_id)
  root_span = Span.new(
    name,
    trace_id: trace_id,
    span_type: span_type,
    **default_attributes.merge(attributes)
  )
  trace.add_span(root_span)

  with_span(root_span) do
    result = yield(root_span)
    root_span.finish
    reporter.report(redact_trace!(trace))
    result
  end
rescue StandardError => e
  if root_span && !root_span.finished?
    root_span.record_error(e)
    root_span.finish
    reporter.report(redact_trace!(trace))
  end
  raise
end