Module: ActiveAgent::Telemetry

Extended by:
ActiveSupport::Autoload
Defined in:
lib/active_agent/telemetry.rb,
lib/active_agent/telemetry/span.rb,
lib/active_agent/telemetry/tracer.rb,
lib/active_agent/telemetry/reporter.rb,
lib/active_agent/telemetry/configuration.rb,
lib/active_agent/telemetry/instrumentation.rb

Overview

Telemetry module for collecting and reporting agent traces.

Provides optional observability by capturing agent generation traces, tool calls, token usage, and errors. Reports to a configured endpoint (self-hosted or ActiveAgents.ai hosted service).

Features

  • **Trace Collection**: Captures full generation lifecycle with spans

  • **Token Tracking**: Records input/output/thinking tokens per generation

  • **Tool Call Tracing**: Captures tool invocations with arguments and results

  • **Error Tracking**: Records errors with backtraces

  • **Async Reporting**: Non-blocking HTTP reporting with background thread

Configuration

Configure in your Rails initializer or activeagent.yml:

Examples:

Basic configuration

ActiveAgent::Telemetry.configure do |config|
  config.enabled = true
  config.endpoint = "https://api.activeagents.ai/v1/traces"
  config.api_key = Rails.application.credentials.dig(:activeagents, :api_key)
end

YAML configuration (config/activeagent.yml)

telemetry:
  enabled: true
  endpoint: https://api.activeagents.ai/v1/traces
  api_key: <%= Rails.application.credentials.dig(:activeagents, :api_key) %>
  sample_rate: 1.0
  batch_size: 100
  flush_interval: 5

Self-hosted endpoint

ActiveAgent::Telemetry.configure do |config|
  config.endpoint = "https://observability.mycompany.com/v1/traces"
  config.api_key = ENV["TELEMETRY_API_KEY"]
end

See Also:

Defined Under Namespace

Modules: Instrumentation Classes: Configuration, NullSpan, Reporter, Span, Tracer

Class Method Summary collapse

Class Method Details

.configuration ⇒ Configuration

Returns the telemetry configuration instance.

Returns:



63
64
65
 
# File 'lib/active_agent/telemetry.rb', line 63

def configuration
  @configuration ||= Configuration.new
end

.configure {|config| ... } ⇒ Configuration

Configures telemetry with a block.

Examples:

ActiveAgent::Telemetry.configure do |config|
  config.enabled = true
  config.endpoint = "https://api.activeagents.ai/v1/traces"
  config.api_key = "your-api-key"
end

Yields:

  • (config) —

    Yields the configuration instance

Yield Parameters:

Returns:



79
80
81
82
 
# File 'lib/active_agent/telemetry.rb', line 79

def configure
  yield configuration if block_given?
  configuration
end

.enabled? ⇒ Boolean

Returns whether telemetry is enabled and configured.

Returns:

  • (Boolean) —

    True if telemetry should collect and report



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

def enabled?
  configuration.enabled? && configuration.configured?
end

.flush ⇒ void

This method returns an undefined value.

Flushes any buffered traces immediately.



137
138
139
 
# File 'lib/active_agent/telemetry.rb', line 137

def flush
  tracer.flush if enabled?
end

.reset_configuration! ⇒ Configuration

Resets the configuration to defaults.

Returns:



87
88
89
 
# File 'lib/active_agent/telemetry.rb', line 87

def reset_configuration!
  @configuration = Configuration.new
end

.shutdown ⇒ void

This method returns an undefined value.

Shuts down telemetry, flushing remaining traces.



144
145
146
 
# File 'lib/active_agent/telemetry.rb', line 144

def shutdown
  tracer.shutdown if @tracer
end

.span(name, **attributes) ⇒ Span

Records a standalone span (outside of a trace context).

Parameters:

  • name (String) —

    Span name

  • attributes (Hash) —

    Span attributes

Returns:

  • (Span) —

    The created span



128
129
130
131
132
 
# File 'lib/active_agent/telemetry.rb', line 128

def span(name, **attributes)
  return NullSpan.new unless enabled?

  tracer.span(name, **attributes)
end

.trace(name, **attributes) {|trace| ... } ⇒ Span

Starts a new trace for an agent generation.

Examples:

ActiveAgent::Telemetry.trace("WeatherAgent.forecast") do |trace|
  trace.add_span("llm.generate", provider: "anthropic")
  trace.set_tokens(input: 100, output: 50)
end

Parameters:

  • name (String) —

    Name of the trace (typically agent.action)

  • attributes (Hash) —

    Additional trace attributes

Yields:

  • (trace) —

    Yields the trace for adding spans

Returns:

  • (Span) —

    The root span of the trace



117
118
119
120
121
 
# File 'lib/active_agent/telemetry.rb', line 117

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

  tracer.trace(name, **attributes, &block)
end

.tracer ⇒ Tracer

Returns the global tracer instance.

Returns:

  • (Tracer) —

    The tracer instance



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

def tracer
  @tracer ||= Tracer.new(configuration)
end