Class: ActiveAgent::Telemetry::Configuration

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

Overview

Configuration for telemetry collection and reporting.

Stores settings for endpoint, authentication, sampling, and batching. Configuration can be set programmatically or loaded from YAML.

Examples:

Programmatic configuration

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

YAML configuration (config/activeagent.yml)

telemetry:
  enabled: true
  endpoint: https://api.activeagents.ai/v1/traces
  api_key: <%= ENV["ACTIVEAGENTS_API_KEY"] %>
  sample_rate: 1.0
  batch_size: 100
  flush_interval: 5

Constant Summary collapse

DEFAULT_ENDPOINT =

Default ActiveAgents.ai endpoint for hosted observability.

"https://api.activeagents.ai/v1/traces"
LOCAL_ENDPOINT_PATH =

Local dashboard endpoint path (relative to app root)

"/active_agent/api/traces"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/active_agent/telemetry/configuration.rb', line 76

def initialize
  @enabled = false
  @endpoint = DEFAULT_ENDPOINT
  @api_key = nil
  @sample_rate = 1.0
  @batch_size = 100
  @flush_interval = 5
  @timeout = 10
  @capture_bodies = false
  @redact_attributes = %w[password secret token key credential api_key]
  @service_name = nil
  @environment = Rails.env if defined?(Rails)
  @resource_attributes = {}
  @logger = nil
  @local_storage = false
end

Instance Attribute Details

#api_key ⇒ String

Returns API key for authentication.

Returns:

  • (String) —

    API key for authentication



35
36
37
 
# File 'lib/active_agent/telemetry/configuration.rb', line 35

def api_key
  @api_key
end

#batch_size ⇒ Integer

Returns Number of traces to batch before sending (default: 100).

Returns:

  • (Integer) —

    Number of traces to batch before sending (default: 100)



41
42
43
 
# File 'lib/active_agent/telemetry/configuration.rb', line 41

def batch_size
  @batch_size
end

#capture_bodies ⇒ Boolean

Returns Whether to capture request/response bodies (default: false).

Returns:

  • (Boolean) —

    Whether to capture request/response bodies (default: false)



50
51
52
 
# File 'lib/active_agent/telemetry/configuration.rb', line 50

def capture_bodies
  @capture_bodies
end

#enabled ⇒ Boolean

Returns Whether telemetry is enabled (default: false).

Returns:

  • (Boolean) —

    Whether telemetry is enabled (default: false)



29
30
31
 
# File 'lib/active_agent/telemetry/configuration.rb', line 29

def enabled
  @enabled
end

#endpoint ⇒ String

Returns The endpoint URL for sending traces.

Returns:

  • (String) —

    The endpoint URL for sending traces



32
33
34
 
# File 'lib/active_agent/telemetry/configuration.rb', line 32

def endpoint
  @endpoint
end

#environment ⇒ String

Returns Environment name (development, staging, production).

Returns:

  • (String) —

    Environment name (development, staging, production)



59
60
61
 
# File 'lib/active_agent/telemetry/configuration.rb', line 59

def environment
  @environment
end

#flush_interval ⇒ Integer

Returns Seconds between automatic flushes (default: 5).

Returns:

  • (Integer) —

    Seconds between automatic flushes (default: 5)



44
45
46
 
# File 'lib/active_agent/telemetry/configuration.rb', line 44

def flush_interval
  @flush_interval
end

#local_storage ⇒ Boolean

Returns Whether to store traces locally in the app’s database.

Returns:

  • (Boolean) —

    Whether to store traces locally in the app’s database



68
69
70
 
# File 'lib/active_agent/telemetry/configuration.rb', line 68

def local_storage
  @local_storage
end

#logger ⇒ Logger

Returns Logger for telemetry operations.

Returns:

  • (Logger) —

    Logger for telemetry operations



65
66
67
 
# File 'lib/active_agent/telemetry/configuration.rb', line 65

def logger
  @logger
end

#redact_attributes ⇒ Array<String>

Returns Attributes to redact from traces.

Returns:

  • (Array<String>) —

    Attributes to redact from traces



53
54
55
 
# File 'lib/active_agent/telemetry/configuration.rb', line 53

def redact_attributes
  @redact_attributes
end

#resource_attributes ⇒ Hash

Returns Additional resource attributes to include in all traces.

Returns:

  • (Hash) —

    Additional resource attributes to include in all traces



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

def resource_attributes
  @resource_attributes
end

#sample_rate ⇒ Float

Returns Sampling rate from 0.0 to 1.0 (default: 1.0).

Returns:

  • (Float) —

    Sampling rate from 0.0 to 1.0 (default: 1.0)



38
39
40
 
# File 'lib/active_agent/telemetry/configuration.rb', line 38

def sample_rate
  @sample_rate
end

#service_name ⇒ String

Returns Service name for trace attribution.

Returns:

  • (String) —

    Service name for trace attribution



56
57
58
 
# File 'lib/active_agent/telemetry/configuration.rb', line 56

def service_name
  @service_name
end

#timeout ⇒ Integer

Returns HTTP timeout in seconds (default: 10).

Returns:

  • (Integer) —

    HTTP timeout in seconds (default: 10)



47
48
49
 
# File 'lib/active_agent/telemetry/configuration.rb', line 47

def timeout
  @timeout
end

Instance Method Details

#configured? ⇒ Boolean

Returns whether telemetry is properly configured.

Checks that endpoint and api_key are present, or local_storage is enabled.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/active_agent/telemetry/configuration.rb', line 105

def configured?
  local_storage? || (endpoint.present? && api_key.present?)
end

#enabled? ⇒ Boolean

Returns whether telemetry collection is enabled.

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/active_agent/telemetry/configuration.rb', line 96

def enabled?
  @enabled == true
end

#load_from_hash(hash) ⇒ self

Loads configuration from a hash (typically from YAML).

Parameters:

  • hash (Hash) —

    Configuration hash

Returns:

  • (self) 


163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/active_agent/telemetry/configuration.rb', line 163

def load_from_hash(hash)
  hash = hash.with_indifferent_access if hash.respond_to?(:with_indifferent_access)

  @enabled = hash[:enabled] if hash.key?(:enabled)
  @endpoint = hash[:endpoint] if hash.key?(:endpoint)
  @api_key = hash[:api_key] if hash.key?(:api_key)
  @sample_rate = hash[:sample_rate].to_f if hash.key?(:sample_rate)
  @batch_size = hash[:batch_size].to_i if hash.key?(:batch_size)
  @flush_interval = hash[:flush_interval].to_i if hash.key?(:flush_interval)
  @timeout = hash[:timeout].to_i if hash.key?(:timeout)
  @capture_bodies = hash[:capture_bodies] if hash.key?(:capture_bodies)
  @redact_attributes = hash[:redact_attributes] if hash.key?(:redact_attributes)
  @service_name = hash[:service_name] if hash.key?(:service_name)
  @environment = hash[:environment] if hash.key?(:environment)
  @resource_attributes = hash[:resource_attributes] if hash.key?(:resource_attributes)
  @local_storage = hash[:local_storage] if hash.key?(:local_storage)

  self
end

#local_storage? ⇒ Boolean

Returns whether local storage mode is enabled.

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/active_agent/telemetry/configuration.rb', line 112

def local_storage?
  @local_storage == true
end

#resolved_endpoint ⇒ String

Returns the resolved endpoint for trace reporting.

Uses local endpoint when local_storage is enabled.

Returns:

  • (String) 


121
122
123
124
125
126
127
 
# File 'lib/active_agent/telemetry/configuration.rb', line 121

def resolved_endpoint
  if local_storage?
    LOCAL_ENDPOINT_PATH
  else
    endpoint
  end
end

#resolved_logger ⇒ Logger

Returns the logger for telemetry operations.

Falls back to Rails.logger or a null logger.

Returns:

  • (Logger) 


155
156
157
 
# File 'lib/active_agent/telemetry/configuration.rb', line 155

def resolved_logger
  @logger || (defined?(Rails) && Rails.logger) || Logger.new(File::NULL)
end

#resolved_service_name ⇒ String

Resolves the service name for traces.

Falls back to Rails application name or “activeagent”.

Returns:

  • (String) 


146
147
148
 
# File 'lib/active_agent/telemetry/configuration.rb', line 146

def resolved_service_name
  @service_name || rails_app_name || "activeagent"
end

#should_sample? ⇒ Boolean

Returns whether a trace should be sampled.

Uses sample_rate to determine if trace should be collected.

Returns:

  • (Boolean) 


134
135
136
137
138
139
 
# File 'lib/active_agent/telemetry/configuration.rb', line 134

def should_sample?
  return true if sample_rate >= 1.0
  return false if sample_rate <= 0.0

  rand < sample_rate
end

#to_h ⇒ Hash

Returns configuration as a hash for serialization.

Returns:

  • (Hash) 


186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/active_agent/telemetry/configuration.rb', line 186

def to_h
  {
    enabled: enabled,
    endpoint: endpoint,
    api_key: api_key ? "[REDACTED]" : nil,
    sample_rate: sample_rate,
    batch_size: batch_size,
    flush_interval: flush_interval,
    timeout: timeout,
    capture_bodies: capture_bodies,
    service_name: resolved_service_name,
    environment: environment,
    local_storage: local_storage
  }
end