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:



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

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:



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

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



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

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

.flush ⇒ void

This method returns an undefined value.

Flushes any buffered traces immediately.



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

def flush
  tracer.flush if enabled?
end

.reset_configuration! ⇒ Configuration

Resets the configuration to defaults.

Returns:



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

def reset_configuration!
  @configuration = Configuration.new
end

.shutdown ⇒ void

This method returns an undefined value.

Shuts down telemetry, flushing remaining traces.



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

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



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

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



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

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



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

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