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.13.0"

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.



270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/opentrace.rb', line 270

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



298
299
300
301
302
303
304
305
306
307
 
# File 'lib/opentrace.rb', line 298

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.



190
191
192
193
194
195
 
# File 'lib/opentrace.rb', line 190

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

.config ⇒ Object 



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

def config
  @config ||= Config.new
end

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

Yields:



48
49
50
51
52
 
# File 'lib/opentrace.rb', line 48

def configure
  yield config
  config.finalize!
  reset_client!
end

.current_breadcrumbs ⇒ Object

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



286
287
288
 
# File 'lib/opentrace.rb', line 286

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

.current_request_id ⇒ Object 



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

def current_request_id
  Fiber[:opentrace_request_id]
end

.current_request_id=(id) ⇒ Object 



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

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

.current_transaction_name ⇒ Object 



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

def current_transaction_name
  Fiber[:opentrace_transaction_name]
end

.disable! ⇒ Object 



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

def disable!
  config.enabled = false
end

.enable! ⇒ Object 



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

def enable!
  config.enabled = true
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


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

def enabled?
  config.enabled?
end

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



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

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 



153
154
155
156
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
 
# File 'lib/opentrace.rb', line 153

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) 


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

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.



65
66
67
68
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
 
# File 'lib/opentrace.rb', line 65

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 



328
329
330
331
332
333
334
335
 
# File 'lib/opentrace.rb', line 328

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

.reset_stats! ⇒ Object 



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

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

.sampler ⇒ Object 



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

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

.set_transaction_name(name) ⇒ Object

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



218
219
220
221
222
 
# File 'lib/opentrace.rb', line 218

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

.shutdown(timeout: 5) ⇒ Object 



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

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

.stats ⇒ Object 



309
310
311
312
 
# File 'lib/opentrace.rb', line 309

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



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

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