Class: ActiveAgent::Telemetry::Tracer

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

Overview

Manages trace creation and lifecycle.

The Tracer creates traces, manages the current trace context, and coordinates with the Reporter for async transmission.

Examples:

Basic usage

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.



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

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

Instance Attribute Details

#configuration ⇒ Configuration (readonly)

Returns Telemetry configuration.

Returns:



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

def configuration
  @configuration
end

#reporter ⇒ Reporter (readonly)

Returns The reporter for sending traces.

Returns:

  • (Reporter) —

    The reporter for sending traces



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

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



90
91
92
 
# File 'lib/active_agent/telemetry/tracer.rb', line 90

def current_span
  Thread.current[CURRENT_SPAN_KEY]
end

#flush ⇒ void

This method returns an undefined value.

Flushes buffered traces immediately.



97
98
99
 
# File 'lib/active_agent/telemetry/tracer.rb', line 97

def flush
  reporter.flush
end

#shutdown ⇒ void

This method returns an undefined value.

Shuts down the tracer and reporter.



104
105
106
 
# File 'lib/active_agent/telemetry/tracer.rb', line 104

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



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

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

  current = current_span
  if current
    current.add_span(name, **attributes)
  else
    Span.new(name, trace_id: generate_trace_id, **default_attributes.merge(attributes))
  end
end

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

Creates and executes a new trace.

Examples:

tracer.trace("WeatherAgent.forecast") do |span|
  span.set_attribute("location", "Seattle")
  result = do_llm_call
  span.set_tokens(input: 100, output: 50)
  result
end

Parameters:

  • name (String) —

    Trace name (typically “AgentClass.action”)

  • attributes (Hash) —

    Root span attributes

Yields:

  • (span) —

    Yields the root span for adding child spans

Returns:

  • (Object) —

    Result of the block



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

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

  trace_id = generate_trace_id
  root_span = Span.new(
    name,
    trace_id: trace_id,
    span_type: :root,
    **default_attributes.merge(attributes)
  )

  with_span(root_span) do
    result = yield(root_span)
    root_span.finish
    report_trace(root_span)
    result
  end
rescue StandardError => e
  root_span&.record_error(e)
  root_span&.finish
  report_trace(root_span) if root_span
  raise
end