Class: OpenTrace::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/opentrace/config.rb

Constant Summary collapse

REQUIRED_FIELDS = 
%i[endpoint api_key service].freeze
LEVELS = 
{ debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }.freeze
LEVEL_INTS = 
{ "DEBUG" => 0, "INFO" => 1, "WARN" => 2, "ERROR" => 3, "FATAL" => 4 }.freeze
LEVEL_TO_LOGGER_SEVERITY =

Maps OpenTrace min_level to Ruby Logger severity constant. Used by LogForwarder to set its level so BroadcastLogger doesn’t downgrade the effective log level for the entire app.

{
  debug: 0, # ::Logger::DEBUG
  info:  1, # ::Logger::INFO
  warn:  2, # ::Logger::WARN
  error: 3, # ::Logger::ERROR
  fatal: 4  # ::Logger::FATAL
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Config

Returns a new instance of Config.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/opentrace/config.rb', line 81

def initialize
  @endpoint    = nil
  @api_key     = nil
  @service     = nil
  @environment = nil
  @timeout     = 1.0
  @enabled     = true
  @context     = nil    # nil | Hash | Proc
  @min_level   = :info
  @allowed_levels = nil  # nil = use min_level threshold (backward compatible)
  @hostname       = nil
  @pid            = nil
  @git_sha        = nil
  @batch_size     = 50
  @flush_interval = 5.0
  @max_retries    = 2
  @retry_base_delay = 0.1
  @retry_max_delay  = 2.0
  @circuit_breaker_threshold = 5
  @circuit_breaker_timeout   = 30
  @rate_limit_backoff = 5.0
  @on_drop        = nil # ->(count, reason) { ... }
  @compression    = true
  @compression_threshold = 1024 # only compress payloads > 1KB
  @sql_logging    = false
  @sql_duration_threshold_ms = 0.0
  @ignore_paths   = %w[/up /health /healthz /ping /ready /livez /readyz]
  @pool_monitoring = false
  @pool_monitoring_interval = 30
  @queue_monitoring = false
  @queue_monitoring_interval = 60
  @request_summary = true
  @timeline = false
  @timeline_max_events = 200
  @memory_tracking = false
  @http_tracking = false
  @max_payload_bytes = 262_144 # 256 KB
  @trace_propagation = true
  @log_forwarding = false
  @view_tracking = false
  @cache_tracking = false
  @deprecation_tracking = false
  @detailed_request_log = false
  @sample_rate = 1.0     # Float 0.0-1.0, default 1.0 (all requests)
  @sampler     = nil     # Proc(env) -> Float, for per-endpoint rates
  @before_send = nil     # Proc(payload) -> payload|nil, filter/drop
  @sql_normalization = true   # Normalize SQL queries (replace literals with ?)
  @log_trace_injection = false # Inject trace_id/request_id into Rails logger
  @source_context = false      # Capture source code context around errors
  @before_breadcrumb = nil     # Proc(Breadcrumb) -> Breadcrumb|nil
  @pii_scrubbing = false       # Scrub PII from metadata before sending
  @pii_patterns = nil          # Array of additional Regexp patterns
  @pii_disabled_patterns = nil # Array of Symbol pattern names to skip
  @session_tracking = false    # Extract session ID from cookies
  @on_error = nil              # Proc(exception, metadata) — called on error capture
  @after_send = nil            # Proc(batch_size, bytes) — called after successful delivery
  @transport = :http              # :http | :unix_socket
  @socket_path = "/tmp/opentrace.sock" # Unix socket path
  @local_vars_capture = false     # Capture local variables via explicit binding
  @explain_slow_queries = false   # Run EXPLAIN on slow SQL queries
  @explain_threshold_ms = 100.0   # Threshold for EXPLAIN capture
  @runtime_metrics = false        # Collect GC/runtime metrics
  @runtime_metrics_interval = 30  # Interval in seconds
  # Deep capture
  @capture_depth = :standard
  @capture_rules_block = nil
  # Per-domain overrides (nil = follow capture_depth)
  @email_capture = nil
  @sql_capture = nil
  @http_capture = nil
  @audit_capture = nil
  @request_capture = nil
  # Buffering & safety
  @max_buffer_bytes = 1_048_576        # 1MB per request
  @max_total_buffer_bytes = 52_428_800 # 50MB global
  @max_queue_bytes = 10_485_760        # 10MB
  # Audit trail
  @audit_tracking = false
  @audit_max_events_per_request = 50
  @audit_exclude_models = []
  @audit_exclude_fields = %w[updated_at created_at password_digest]
  @audit_actor = nil
  # Body capture
  @max_request_body_bytes = 262_144    # 256KB
  # Serialization format
  @serialization_format = :json
  @level_cache = nil
  @enabled_cache = nil
end

Instance Attribute Details

#after_send ⇒ Object

Returns the value of attribute after_send.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def after_send
  @after_send
end

#allowed_levels ⇒ Object

Custom writers that invalidate caches



52
53
54
 
# File 'lib/opentrace/config.rb', line 52

def allowed_levels
  @allowed_levels
end

#api_key ⇒ Object

Returns the value of attribute api_key.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def api_key
  @api_key
end

#audit_actor ⇒ Object

Returns the value of attribute audit_actor.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def audit_actor
  @audit_actor
end

#audit_capture ⇒ Object

Returns the value of attribute audit_capture.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def audit_capture
  @audit_capture
end

#audit_exclude_fields ⇒ Object

Returns the value of attribute audit_exclude_fields.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def audit_exclude_fields
  @audit_exclude_fields
end

#audit_exclude_models ⇒ Object

Returns the value of attribute audit_exclude_models.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def audit_exclude_models
  @audit_exclude_models
end

#audit_max_events_per_request ⇒ Object

Returns the value of attribute audit_max_events_per_request.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def audit_max_events_per_request
  @audit_max_events_per_request
end

#audit_tracking ⇒ Object

Returns the value of attribute audit_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def audit_tracking
  @audit_tracking
end

#batch_size ⇒ Object

Returns the value of attribute batch_size.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def batch_size
  @batch_size
end

#before_breadcrumb ⇒ Object

Returns the value of attribute before_breadcrumb.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def before_breadcrumb
  @before_breadcrumb
end

#before_send ⇒ Object

Returns the value of attribute before_send.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def before_send
  @before_send
end

#cache_tracking ⇒ Object

Returns the value of attribute cache_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def cache_tracking
  @cache_tracking
end

#capture_depth ⇒ Object

Returns the value of attribute capture_depth.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def capture_depth
  @capture_depth
end

#capture_rules_block ⇒ Object

Returns the value of attribute capture_rules_block.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def capture_rules_block
  @capture_rules_block
end

#circuit_breaker_threshold ⇒ Object

Returns the value of attribute circuit_breaker_threshold.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def circuit_breaker_threshold
  @circuit_breaker_threshold
end

#circuit_breaker_timeout ⇒ Object

Returns the value of attribute circuit_breaker_timeout.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def circuit_breaker_timeout
  @circuit_breaker_timeout
end

#compression ⇒ Object

Returns the value of attribute compression.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def compression
  @compression
end

#compression_threshold ⇒ Object

Returns the value of attribute compression_threshold.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def compression_threshold
  @compression_threshold
end

#context ⇒ Object

Returns the value of attribute context.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def context
  @context
end

#deprecation_tracking ⇒ Object

Returns the value of attribute deprecation_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def deprecation_tracking
  @deprecation_tracking
end

#detailed_request_log ⇒ Object

Returns the value of attribute detailed_request_log.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def detailed_request_log
  @detailed_request_log
end

#email_capture ⇒ Object

Returns the value of attribute email_capture.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def email_capture
  @email_capture
end

#enabled ⇒ Object

Custom writers that invalidate caches



52
53
54
 
# File 'lib/opentrace/config.rb', line 52

def enabled
  @enabled
end

#endpoint ⇒ Object

Returns the value of attribute endpoint.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def endpoint
  @endpoint
end

#environment ⇒ Object

Returns the value of attribute environment.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def environment
  @environment
end

#explain_slow_queries ⇒ Object

Returns the value of attribute explain_slow_queries.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def explain_slow_queries
  @explain_slow_queries
end

#explain_threshold_ms ⇒ Object

Returns the value of attribute explain_threshold_ms.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def explain_threshold_ms
  @explain_threshold_ms
end

#flush_interval ⇒ Object

Returns the value of attribute flush_interval.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def flush_interval
  @flush_interval
end

#git_sha ⇒ Object

Returns the value of attribute git_sha.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def git_sha
  @git_sha
end

#hostname ⇒ Object

Returns the value of attribute hostname.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def hostname
  @hostname
end

#http_capture ⇒ Object

Returns the value of attribute http_capture.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def http_capture
  @http_capture
end

#http_tracking ⇒ Object

Returns the value of attribute http_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def http_tracking
  @http_tracking
end

#ignore_paths ⇒ Object

Custom writers that invalidate caches



52
53
54
 
# File 'lib/opentrace/config.rb', line 52

def ignore_paths
  @ignore_paths
end

#local_vars_capture ⇒ Object

Returns the value of attribute local_vars_capture.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def local_vars_capture
  @local_vars_capture
end

#log_forwarding ⇒ Object

Returns the value of attribute log_forwarding.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def log_forwarding
  @log_forwarding
end

#log_trace_injection ⇒ Object

Returns the value of attribute log_trace_injection.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def log_trace_injection
  @log_trace_injection
end

#max_buffer_bytes ⇒ Object

Returns the value of attribute max_buffer_bytes.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def max_buffer_bytes
  @max_buffer_bytes
end

#max_payload_bytes ⇒ Object

Returns the value of attribute max_payload_bytes.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def max_payload_bytes
  @max_payload_bytes
end

#max_queue_bytes ⇒ Object

Returns the value of attribute max_queue_bytes.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def max_queue_bytes
  @max_queue_bytes
end

#max_request_body_bytes ⇒ Object

Returns the value of attribute max_request_body_bytes.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def max_request_body_bytes
  @max_request_body_bytes
end

#max_retries ⇒ Object

Returns the value of attribute max_retries.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def max_retries
  @max_retries
end

#max_total_buffer_bytes ⇒ Object

Returns the value of attribute max_total_buffer_bytes.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def max_total_buffer_bytes
  @max_total_buffer_bytes
end

#memory_tracking ⇒ Object

Returns the value of attribute memory_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def memory_tracking
  @memory_tracking
end

#min_level ⇒ Object

Custom writers that invalidate caches



52
53
54
 
# File 'lib/opentrace/config.rb', line 52

def min_level
  @min_level
end

#on_drop ⇒ Object

Returns the value of attribute on_drop.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def on_drop
  @on_drop
end

#on_error ⇒ Object

Returns the value of attribute on_error.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def on_error
  @on_error
end

#pid ⇒ Object

Returns the value of attribute pid.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def pid
  @pid
end

#pii_disabled_patterns ⇒ Object

Returns the value of attribute pii_disabled_patterns.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def pii_disabled_patterns
  @pii_disabled_patterns
end

#pii_patterns ⇒ Object

Returns the value of attribute pii_patterns.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def pii_patterns
  @pii_patterns
end

#pii_scrubbing ⇒ Object

Returns the value of attribute pii_scrubbing.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def pii_scrubbing
  @pii_scrubbing
end

#pool_monitoring ⇒ Object

Returns the value of attribute pool_monitoring.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def pool_monitoring
  @pool_monitoring
end

#pool_monitoring_interval ⇒ Object

Returns the value of attribute pool_monitoring_interval.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def pool_monitoring_interval
  @pool_monitoring_interval
end

#queue_monitoring ⇒ Object

Returns the value of attribute queue_monitoring.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def queue_monitoring
  @queue_monitoring
end

#queue_monitoring_interval ⇒ Object

Returns the value of attribute queue_monitoring_interval.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def queue_monitoring_interval
  @queue_monitoring_interval
end

#rate_limit_backoff ⇒ Object

Returns the value of attribute rate_limit_backoff.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def rate_limit_backoff
  @rate_limit_backoff
end

#request_capture ⇒ Object

Returns the value of attribute request_capture.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def request_capture
  @request_capture
end

#request_summary ⇒ Object

Returns the value of attribute request_summary.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def request_summary
  @request_summary
end

#retry_base_delay ⇒ Object

Returns the value of attribute retry_base_delay.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def retry_base_delay
  @retry_base_delay
end

#retry_max_delay ⇒ Object

Returns the value of attribute retry_max_delay.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def retry_max_delay
  @retry_max_delay
end

#runtime_metrics ⇒ Object

Returns the value of attribute runtime_metrics.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def runtime_metrics
  @runtime_metrics
end

#runtime_metrics_interval ⇒ Object

Returns the value of attribute runtime_metrics_interval.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def runtime_metrics_interval
  @runtime_metrics_interval
end

#sample_rate ⇒ Object

Custom writers that invalidate caches



52
53
54
 
# File 'lib/opentrace/config.rb', line 52

def sample_rate
  @sample_rate
end

#sampler ⇒ Object

Returns the value of attribute sampler.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def sampler
  @sampler
end

#serialization_format ⇒ Object

Returns the value of attribute serialization_format.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def serialization_format
  @serialization_format
end

#service ⇒ Object

Returns the value of attribute service.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def service
  @service
end

#session_tracking ⇒ Object

Returns the value of attribute session_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def session_tracking
  @session_tracking
end

#socket_path ⇒ Object

Returns the value of attribute socket_path.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def socket_path
  @socket_path
end

#source_context ⇒ Object

Returns the value of attribute source_context.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def source_context
  @source_context
end

#sql_capture ⇒ Object

Returns the value of attribute sql_capture.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def sql_capture
  @sql_capture
end

#sql_duration_threshold_ms ⇒ Object

Returns the value of attribute sql_duration_threshold_ms.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def sql_duration_threshold_ms
  @sql_duration_threshold_ms
end

#sql_logging ⇒ Object

Returns the value of attribute sql_logging.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def sql_logging
  @sql_logging
end

#sql_normalization ⇒ Object

Returns the value of attribute sql_normalization.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def sql_normalization
  @sql_normalization
end

#timeline ⇒ Object

Returns the value of attribute timeline.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def timeline
  @timeline
end

#timeline_max_events ⇒ Object

Returns the value of attribute timeline_max_events.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def timeline_max_events
  @timeline_max_events
end

#timeout ⇒ Object

Returns the value of attribute timeout.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def timeout
  @timeout
end

#trace_propagation ⇒ Object

Returns the value of attribute trace_propagation.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def trace_propagation
  @trace_propagation
end

#transport ⇒ Object

Returns the value of attribute transport.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def transport
  @transport
end

#view_tracking ⇒ Object

Returns the value of attribute view_tracking.



9
10
11
 
# File 'lib/opentrace/config.rb', line 9

def view_tracking
  @view_tracking
end

Instance Method Details

#capture_rules(&block) ⇒ Object 



260
261
262
 
# File 'lib/opentrace/config.rb', line 260

def capture_rules(&block)
  @capture_rules_block = block
end

#enabled? ⇒ Boolean

Returns:

  • (Boolean) 


175
176
177
178
179
180
181
182
 
# File 'lib/opentrace/config.rb', line 175

def enabled?
  # Cache the enabled+valid result to avoid recomputing valid? on every call.
  # Invalidated by finalize! (called at end of configure block) and enabled= setter.
  if @enabled_cache.nil?
    @enabled_cache = @enabled && valid?
  end
  @enabled_cache
end

#finalize! ⇒ Object

Pre-compute the level cache. Called at end of configure block and lazily when settings change afterward.



210
211
212
213
214
 
# File 'lib/opentrace/config.rb', line 210

def finalize!
  @enabled_cache = nil
  resolve_environment!
  build_level_cache!
end

#level_allowed?(level) ⇒ Boolean

Hot path: single hash lookup, zero allocations for known levels. Cache is built lazily on first call and invalidated when min_level or allowed_levels change.

Returns:

  • (Boolean) 


191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/opentrace/config.rb', line 191

def level_allowed?(level)
  cache = @level_cache
  unless cache
    build_level_cache!
    cache = @level_cache
  end
  # Avoid allocating a new String when the level is already uppercase.
  # On the hot path (called per SQL query, per log line), this saves
  # one String allocation per call.
  key = level.is_a?(String) && level == level.upcase ? level : level.to_s.upcase
  result = cache[key]
  return result unless result.nil?
  # Unknown level (e.g. "UNKNOWN"): treat as severity 0
  return false if allowed_levels # not in the allowed list
  0 >= (LEVELS[min_level.to_s.downcase.to_sym] || 0)
end

#logger_severity ⇒ Object 



256
257
258
 
# File 'lib/opentrace/config.rb', line 256

def logger_severity
  LEVEL_TO_LOGGER_SEVERITY[min_level.to_s.downcase.to_sym] || 0
end

#min_level_value ⇒ Object 



184
185
186
 
# File 'lib/opentrace/config.rb', line 184

def min_level_value
  LEVELS[min_level.to_s.downcase.to_sym] || 0
end

#resolve_environment! ⇒ Object

Resolve environment from env vars if the caller didn’t set it explicitly. Fallback order:

1. explicit config (c.environment = "...")
2. ENV["OPENTRACE_ENV"]            — canonical opentrace variable
3. Rails.env                        — Rails apps, no extra config needed
4. ENV["RACK_ENV"]                  — Rack apps without Rails
5. ENV["RAILS_ENV"]                 — edge case: RAILS_ENV set but Rails not loaded

The first non-empty value wins. Callers who want “no env” can explicitly clear it after finalize!, but there’s rarely a reason to.



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/opentrace/config.rb', line 225

def resolve_environment!
  return if @environment && !@environment.to_s.empty?

  if (v = ENV["OPENTRACE_ENV"]) && !v.empty?
    @environment = v
    return
  end
  if defined?(Rails) && Rails.respond_to?(:env) && (v = Rails.env.to_s) && !v.empty?
    @environment = v
    return
  end
  if (v = ENV["RACK_ENV"]) && !v.empty?
    @environment = v
    return
  end
  if (v = ENV["RAILS_ENV"]) && !v.empty?
    @environment = v
  end
end

#valid? ⇒ Boolean

Returns:

  • (Boolean) 


171
172
173
 
# File 'lib/opentrace/config.rb', line 171

def valid?
  REQUIRED_FIELDS.all? { |f| value = send(f); value.is_a?(String) && !value.empty? }
end