Module: OpenTrace

Defined in:
lib/opentrace.rb,
lib/opentrace/ulid.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/pipeline.rb,
lib/opentrace/local_vars.rb,
lib/opentrace/middleware.rb,
lib/opentrace/serializer.rb,
lib/opentrace/breadcrumbs.rb,
lib/opentrace/buffer_pool.rb,
lib/opentrace/ring_buffer.rb,
lib/opentrace/http_tracker.rb,
lib/opentrace/memory_guard.rb,
lib/opentrace/pii_scrubber.rb,
lib/opentrace/pool_monitor.rb,
lib/opentrace/audit_tracker.rb,
lib/opentrace/capture_rules.rb,
lib/opentrace/log_forwarder.rb,
lib/opentrace/queue_monitor.rb,
lib/opentrace/trace_context.rb,
lib/opentrace/request_buffer.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/error_subscriber.rb,
lib/opentrace/request_collector.rb,
lib/opentrace/instrumentation_context.rb

Defined Under Namespace

Modules: AuditTracker, HttpTracker, LocalVars, PayloadBuilder, PiiScrubber, Serializer, SourceContext, SqlNormalizer, TraceContext, ULID Classes: Breadcrumb, BreadcrumbBuffer, BufferPool, CaptureRules, CircuitBreaker, Client, Config, ErrorSubscriber, InstrumentationContext, LogForwarder, Logger, MemoryGuard, Middleware, NilClient, NilSpan, NilStats, Pipeline, PipelineStats, PoolMonitor, QueueMonitor, Railtie, RequestBuffer, RequestCollector, RingBuffer, 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.17.3"

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.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/opentrace.rb', line 243

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 



262
263
264
265
266
267
268
269
270
271
 
# File 'lib/opentrace.rb', line 262

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(doc) ⇒ Object

Enqueue a raw request buffer document (from InstrumentationContext). Defers conversion to the background dispatch thread.



294
295
296
297
298
299
300
301
 
# File 'lib/opentrace.rb', line 294

def client_enqueue_raw(doc)
  return unless enabled?
  return unless doc.is_a?(Hash)

  client.enqueue([:raw_document, doc])
rescue StandardError
  # Never raise to the host app
end

.config ⇒ Object 



68
69
70
 
# File 'lib/opentrace.rb', line 68

def config
  @config ||= Config.new
end

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

Yields:



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

def configure
  yield config
  config.finalize!
  InstrumentationContext.configure!(config)
  reset_client!
end

.current_breadcrumbs ⇒ Object 



258
259
260
 
# File 'lib/opentrace.rb', line 258

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

.current_request_id ⇒ Object 



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

def current_request_id
  Fiber[:opentrace_request_id]
end

.current_request_id=(id) ⇒ Object 



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

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

.current_transaction_name ⇒ Object 



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

def current_transaction_name
  Fiber[:opentrace_transaction_name]
end

.disable! ⇒ Object 



186
187
188
 
# File 'lib/opentrace.rb', line 186

def disable!
  config.enabled = false
end

.enable! ⇒ Object 



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

def enable!
  config.enabled = true
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


182
183
184
 
# File 'lib/opentrace.rb', line 182

def enabled?
  config.enabled?
end

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



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

def error(exception, metadata = {})
  return unless enabled?
  return if Fiber[:opentrace_logging]
  Fiber[:opentrace_logging] = true

  begin
    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)
    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
    crumbs = Fiber[:opentrace_breadcrumbs]
    if crumbs && !crumbs.empty?
      meta[:breadcrumbs] = crumbs.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

    buffer = Fiber[:opentrace_buffer]
    if buffer
      # Inside a request -- record to buffer
      buffer.record_log(level: "ERROR", message: exception.message.to_s, metadata: meta)
      buffer.record_timeline(type: :error, name: "#{exception.class.name}: #{exception.message.to_s[0, 60]}")
    else
      doc = build_standalone_doc("ERROR", exception.message.to_s, meta, event_type: "error")
      client.enqueue(doc)
    end
  ensure
    Fiber[:opentrace_logging] = nil
  end
rescue StandardError
  # Never raise to the host app
end

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



160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/opentrace.rb', line 160

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

  begin
    buffer = Fiber[:opentrace_buffer]
    if buffer
      # Inside a request -- record to buffer
      buffer.record_log(level: "INFO", message: message.to_s, metadata: metadata.merge(_event_type: event_type))
      buffer.record_timeline(type: :event, name: "#{event_type}: #{message.to_s[0, 60]}")
    else
      doc = build_standalone_doc("INFO", message.to_s, metadata, event_type: event_type.to_s)
      client.enqueue(doc)
    end
  ensure
    Fiber[:opentrace_logging] = nil
  end
rescue StandardError
  # Never raise to the host app
end

.healthy? ⇒ Boolean

Returns:

  • (Boolean) 


282
283
284
285
286
 
# File 'lib/opentrace.rb', line 282

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

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



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/opentrace.rb', line 76

def log(level, message, metadata = {})
  return unless enabled?
  return unless config.level_allowed?(level)
  return if Fiber[:opentrace_logging]
  Fiber[:opentrace_logging] = true

  begin
    buffer = Fiber[:opentrace_buffer]
    if buffer
      # Inside a request -- append to buffer
      buffer.record_log(level: level.to_s.upcase, message: message.to_s, metadata: metadata)
      buffer.record_timeline(type: :log, name: message.to_s[0, 80])
    else
      # Standalone log -- build lightweight document and enqueue
      doc = build_standalone_doc(level, message.to_s, metadata)
      client.enqueue(doc)
    end
  ensure
    Fiber[:opentrace_logging] = nil
  end
rescue StandardError
  # Never raise to the host app
end

.reset! ⇒ Object 



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

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

.reset_stats! ⇒ Object 



278
279
280
 
# File 'lib/opentrace.rb', line 278

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

.sampler ⇒ Object 



72
73
74
 
# File 'lib/opentrace.rb', line 72

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

.set_transaction_name(name) ⇒ Object

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



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

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

.shutdown(timeout: 5) ⇒ Object 



288
289
290
 
# File 'lib/opentrace.rb', line 288

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

.stats ⇒ Object 



273
274
275
276
 
# File 'lib/opentrace.rb', line 273

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.



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/opentrace.rb', line 214

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
    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