Module: OpenTrace

Defined in:
lib/opentrace.rb,
lib/opentrace/rails.rb,
lib/opentrace/stats.rb,
lib/opentrace/client.rb,
lib/opentrace/config.rb,
lib/opentrace/logger.rb,
lib/opentrace/sampler.rb,
lib/opentrace/version.rb,
lib/opentrace/local_vars.rb,
lib/opentrace/middleware.rb,
lib/opentrace/breadcrumbs.rb,
lib/opentrace/http_tracker.rb,
lib/opentrace/pii_scrubber.rb,
lib/opentrace/pool_monitor.rb,
lib/opentrace/log_forwarder.rb,
lib/opentrace/queue_monitor.rb,
lib/opentrace/trace_context.rb,
lib/opentrace/source_context.rb,
lib/opentrace/sql_normalizer.rb,
lib/opentrace/circuit_breaker.rb,
lib/opentrace/payload_builder.rb,
lib/opentrace/runtime_monitor.rb,
lib/opentrace/trace_formatter.rb,
lib/opentrace/request_collector.rb

Defined Under Namespace

Modules: HttpTracker, LocalVars, PayloadBuilder, PiiScrubber, SourceContext, SqlNormalizer, TraceContext Classes: Breadcrumb, BreadcrumbBuffer, CircuitBreaker, Client, Config, LogForwarder, Logger, Middleware, NilClient, NilSpan, NilStats, PoolMonitor, QueueMonitor, Railtie, RequestCollector, RuntimeMonitor, Sampler, Span, Stats, TraceFormatter

Constant Summary collapse

LEVEL_VALUES = 
{ "DEBUG" => 0, "INFO" => 1, "WARN" => 2, "ERROR" => 3, "FATAL" => 4 }.freeze
NULL_CLIENT = 
NilClient.new.freeze
VERSION = 
"0.15.1"

Class Method Summary collapse

Class Method Details

.add_breadcrumb(category, message, data = nil, level: "info") ⇒ Object

Add a breadcrumb to the current request’s trail. Breadcrumbs are attached to error payloads for debugging.



274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/opentrace.rb', line 274

def add_breadcrumb(category, message, data = nil, level: "info")
  return unless enabled?
  buffer = Fiber[:opentrace_breadcrumbs] ||= BreadcrumbBuffer.new

  crumb = Breadcrumb.new(category: category, message: message, data: data, level: level)
  if config.before_breadcrumb
    crumb = config.before_breadcrumb.call(crumb) rescue crumb
    return unless crumb
  end

  buffer.add(crumb)
rescue StandardError
  # Never raise
end

.capture_binding(exception, binding_obj) ⇒ Object

Capture local variables from a rescue block’s binding and attach them to the exception for the next OpenTrace.error() call.

rescue => e
  OpenTrace.capture_binding(e, binding)
  OpenTrace.error(e)
  raise
end



302
303
304
305
306
307
308
309
310
311
 
# File 'lib/opentrace.rb', line 302

def capture_binding(exception, binding_obj)
  return unless enabled? && config.local_vars_capture

  vars = LocalVars.capture(binding_obj)
  if vars && !vars.empty?
    exception.instance_variable_set(:@__opentrace_local_vars__, vars)
  end
rescue StandardError
  # Never raise
end

.client_enqueue_raw(entry) ⇒ Object

Push a raw entry (e.g. :request array) directly to the client queue. Used by Rails subscribers to bypass OpenTrace.log overhead.



194
195
196
197
198
199
 
# File 'lib/opentrace.rb', line 194

def client_enqueue_raw(entry)
  return unless enabled?
  client.enqueue(entry)
rescue StandardError
  # Never raise to the host app
end

.config ⇒ Object 



58
59
60
 
# File 'lib/opentrace.rb', line 58

def config
  @config ||= Config.new
end

.configure {|config| ... } ⇒ Object

Yields:



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

def configure
  yield config
  config.finalize!
  reset_client!
end

.current_breadcrumbs ⇒ Object

Get the current request’s breadcrumbs (for testing/debugging)



290
291
292
 
# File 'lib/opentrace.rb', line 290

def current_breadcrumbs
  Fiber[:opentrace_breadcrumbs]&.to_a || []
end

.current_request_id ⇒ Object 



213
214
215
 
# File 'lib/opentrace.rb', line 213

def current_request_id
  Fiber[:opentrace_request_id]
end

.current_request_id=(id) ⇒ Object 



217
218
219
 
# File 'lib/opentrace.rb', line 217

def current_request_id=(id)
  Fiber[:opentrace_request_id] = id
end

.current_transaction_name ⇒ Object 



228
229
230
 
# File 'lib/opentrace.rb', line 228

def current_transaction_name
  Fiber[:opentrace_transaction_name]
end

.disable! ⇒ Object 



205
206
207
 
# File 'lib/opentrace.rb', line 205

def disable!
  config.enabled = false
end

.enable! ⇒ Object 



209
210
211
 
# File 'lib/opentrace.rb', line 209

def enable!
  config.enabled = true
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


201
202
203
 
# File 'lib/opentrace.rb', line 201

def enabled?
  config.enabled?
end

.error(exception, metadata = {}) ⇒ Object 



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
 
# File 'lib/opentrace.rb', line 110

def error(exception, metadata = {})
  return unless enabled?

  meta = metadata.is_a?(Hash) ? metadata.dup : {}
  meta[:exception_class]   = exception.class.name
  meta[:exception_message] = exception.message&.slice(0, 500)

  if exception.backtrace
    cleaned = clean_backtrace_for(exception)
    meta[:backtrace] = cleaned.first(15)
    meta[:error_fingerprint] = compute_error_fingerprint(exception.class.name, cleaned)
  end

  # Capture exception cause chain (max 5 deep)
  if exception.cause
    meta[:exception_causes] = build_cause_chain(exception.cause, depth: 0)
  end

  # Capture source code context for the error origin
  if exception.backtrace && config.source_context
    cleaned = meta[:backtrace] || clean_backtrace_for(exception)
    app_frame = cleaned&.first
    if app_frame
      source = SourceContext.extract(app_frame)
      meta[:source_context] = source if source
    end
  end

  # Attach current breadcrumbs to error
  buffer = Fiber[:opentrace_breadcrumbs]
  if buffer && !buffer.empty?
    meta[:breadcrumbs] = buffer.to_a
  end

  # Attach captured local variables (if capture_binding was called)
  if config.local_vars_capture && exception.instance_variable_defined?(:@__opentrace_local_vars__)
    meta[:local_variables] = exception.instance_variable_get(:@__opentrace_local_vars__)
  end

  # Fire on_error callback
  config.on_error&.call(exception, meta) rescue nil

  log("ERROR", exception.message.to_s, meta)
rescue StandardError
  # Never raise to the host app
end

.event(event_type, message, metadata = {}) ⇒ Object 



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/opentrace.rb', line 157

def event(event_type, message, metadata = {})
  return unless enabled?
  return if Fiber[:opentrace_logging]
  Fiber[:opentrace_logging] = true

  begin
    ctx = Fiber[:opentrace_cached_context]
    unless ctx
      ctx = resolve_context_raw
      if Fiber[:opentrace_request_id]
        ctx = (ctx.is_a?(Hash) ? ctx : {}).freeze
        Fiber[:opentrace_cached_context] = ctx
      end
    end

    client.enqueue([
      Process.clock_gettime(Process::CLOCK_REALTIME),
      "INFO",
      message,
      metadata,
      ctx,
      Fiber[:opentrace_request_id],
      Fiber[:opentrace_trace_id],
      Fiber[:opentrace_span_id],
      Fiber[:opentrace_parent_span_id],
      nil, # request_summary
      event_type # event_type
    ].freeze)
  ensure
    Fiber[:opentrace_logging] = nil
  end
rescue StandardError
  # Never raise to the host app
end

.healthy? ⇒ Boolean

Returns:

  • (Boolean) 


322
323
324
325
326
 
# File 'lib/opentrace.rb', line 322

def healthy?
  return false unless @client
  snapshot = @client.stats_snapshot
  snapshot[:circuit_state] == :closed && !snapshot[:auth_suspended]
end

.log(level, message, metadata = {}, request_summary: nil) ⇒ Object

Push a deferred log entry as a frozen Array. All heavy work (Hash building, timestamp formatting, context merge) is deferred to the background dispatch thread via PayloadBuilder.



69
70
71
72
73
74
75
76
77
78
79
80
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
 
# File 'lib/opentrace.rb', line 69

def log(level, message, metadata = {}, request_summary: nil)
  return unless enabled?
  return unless config.level_allowed?(level)

  # Re-entrance guard: prevent recursive logging if the context proc
  # or any subscriber triggers another log call (e.g. via ActiveRecord)
  return if Fiber[:opentrace_logging]
  Fiber[:opentrace_logging] = true

  begin
    # Read cached context (set by middleware) or resolve fresh
    ctx = Fiber[:opentrace_cached_context]
    unless ctx
      ctx = resolve_context_raw
      # Cache if inside a request (middleware sets request_id)
      if Fiber[:opentrace_request_id]
        ctx = (ctx.is_a?(Hash) ? ctx : {}).freeze
        Fiber[:opentrace_cached_context] = ctx
      end
    end

    client.enqueue([
      Process.clock_gettime(Process::CLOCK_REALTIME), # float timestamp
      level,
      message,
      metadata,
      ctx,
      Fiber[:opentrace_request_id],
      Fiber[:opentrace_trace_id],
      Fiber[:opentrace_span_id],
      Fiber[:opentrace_parent_span_id],
      request_summary,
      nil # event_type
    ].freeze)
  ensure
    Fiber[:opentrace_logging] = nil
  end
rescue StandardError
  # Never raise to the host app
end

.reset! ⇒ Object 



332
333
334
335
336
337
338
339
 
# File 'lib/opentrace.rb', line 332

def reset!
  shutdown(timeout: 1)
  @config = nil
  @client = nil
  @static_context = nil
  @sampler = nil
  @at_exit_registered = nil
end

.reset_stats! ⇒ Object 



318
319
320
 
# File 'lib/opentrace.rb', line 318

def reset_stats!
  @client&.stats&.reset!
end

.sampler ⇒ Object 



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

def sampler
  @sampler ||= Sampler.new(config)
end

.set_transaction_name(name) ⇒ Object

Override the auto-detected transaction name for the current request.



222
223
224
225
226
 
# File 'lib/opentrace.rb', line 222

def set_transaction_name(name)
  Fiber[:opentrace_transaction_name] = name.to_s
rescue StandardError
  # Never raise
end

.shutdown(timeout: 5) ⇒ Object 



328
329
330
 
# File 'lib/opentrace.rb', line 328

def shutdown(timeout: 5)
  @client&.shutdown(timeout: timeout)
end

.stats ⇒ Object 



313
314
315
316
 
# File 'lib/opentrace.rb', line 313

def stats
  return {} unless @client
  @client.stats_snapshot
end

.trace(operation_name, resource: nil, tags: {}) ⇒ Object

Trace a block of code, recording its duration as a span.

OpenTrace.trace("stripe.charge") do
  Stripe::Charge.create(amount: 2000, currency: "usd")
end

OpenTrace.trace("pdf.generate", resource: "Invoice") do |span|
  span.set_tag(:pages, 42)
  generate_invoice_pdf(order)
end



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/opentrace.rb', line 243

def trace(operation_name, resource: nil, tags: {})
  return yield(NilSpan::INSTANCE) unless enabled?

  begin
    span = Span.new(
      operation: operation_name,
      resource: resource,
      parent_span_id: Fiber[:opentrace_span_id],
      trace_id: Fiber[:opentrace_trace_id]
    )
    previous_span_id = Fiber[:opentrace_span_id]
    Fiber[:opentrace_span_id] = span.span_id
  rescue StandardError
    # OpenTrace setup failed — run block without tracing
    return yield(NilSpan::INSTANCE)
  end

  begin
    result = yield(span)
    span.finish(tags: tags)
    result
  rescue => e
    span.finish(error: e, tags: tags)
    raise
  ensure
    Fiber[:opentrace_span_id] = previous_span_id
  end
end