Module: Traces

Defined in:
lib/traces.rb,
lib/traces/config.rb,
lib/traces/backend.rb,
lib/traces/context.rb,
lib/traces/version.rb,
lib/traces/provider.rb,
lib/traces/backend/test.rb,
lib/traces/backend/capture.rb,
lib/traces/backend/console.rb

Overview

Released under the MIT License. Copyright, 2021-2025, by Samuel Williams.

Defined Under Namespace

Modules: Backend, Provider Classes: Config, Context

Constant Summary collapse

VERSION = 
"0.18.2"

Class Method Summary collapse

Class Method Details

.active? ⇒ Boolean

Whether there is an active trace context.

This is a default implementation, which can be replaced by the backend.

Returns:

  • (Boolean) 


30
31
32
 
# File 'lib/traces/backend.rb', line 30

def self.active?
  !!self.trace_context
end

.current_context ⇒ Object

Capture the current trace context for local propagation between execution contexts.

This method returns the current trace context that can be safely passed between threads, fibers, or other execution contexts within the same process.

The returned object is opaque, in other words, you should not make assumptions about its structure.

This is a default implementation, which can be replaced by the backend.



43
44
45
 
# File 'lib/traces/backend.rb', line 43

def self.current_context
  trace_context
end

.enabled? ⇒ Boolean

Returns:

  • (Boolean) 


10
11
12
 
# File 'lib/traces/provider.rb', line 10

def self.enabled?
  Backend.const_defined?(:Interface)
end

.extract(headers) ⇒ Object

Extract trace context from headers for distributed propagation.

The returned object is opaque, in other words, you should not make assumptions about its structure.

This is a default implementation, which can be replaced by the backend.



102
103
104
 
# File 'lib/traces/backend.rb', line 102

def self.extract(headers)
  Context.extract(headers)
end

.inject(headers = nil, context = nil) ⇒ Object

Inject trace context into a headers hash for distributed propagation.

This method adds W3C Trace Context headers (traceparent, tracestate) and W3C Baggage headers to the provided headers hash, enabling distributed tracing across service boundaries. The headers hash is mutated in place.

This is a default implementation, which can be replaced by the backend.



81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/traces/backend.rb', line 81

def self.inject(headers = nil, context = nil)
  context ||= self.trace_context
  
  if context
    headers ||= Hash.new
    context.inject(headers)
  else
    headers = nil
  end
  
  return headers
end

.Provider(klass, &block) ⇒ Object

Extend the specified class in order to emit traces.



30
31
32
33
34
35
36
37
38
 
# File 'lib/traces/provider.rb', line 30

def self.Provider(klass, &block)
  klass.extend(Singleton)
  provider = klass.traces_provider
  klass.prepend(provider)
  
  provider.module_exec(&block) if block_given?
  
  return provider
end

.trace_context ⇒ Object

Capture the current trace context for remote propagation.

This is a default implementation, which can be replaced by the backend.

You should prefer to use the new ‘Traces.current_context` family of methods.



21
22
23
 
# File 'lib/traces/backend.rb', line 21

def self.trace_context
  nil
end

.with_context(context) ⇒ Object

Execute a block within a specific trace context for local execution.

This method is designed for propagating trace context between execution contexts within the same process (threads, fibers, etc.). It temporarily switches to the specified trace context for the duration of the block execution, then restores the previous context.

When called without a block, permanently switches to the specified context. This enables manual context management for scenarios where automatic restoration isn’t desired.

This is a default implementation, which can be replaced by the backend.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/traces/backend.rb', line 57

def self.with_context(context)
  if block_given?
    # This implementation is not ideal but the best we can do with the current interface.
    previous_context = self.trace_context
    begin
      self.trace_context = context
      yield
    ensure
      self.trace_context = previous_context
    end
  else
    self.trace_context = context
  end
end