Class: Fractor::ExecutionTracer

Inherits:
Object
  • Object
show all
Defined in:
lib/fractor/execution_tracer.rb

Overview

Traces work item flow through the Fractor system for debugging. When enabled via FRACTOR_TRACE=1, captures the complete lifecycle of each work item.

Examples:

Instance-based usage (recommended)

tracer = ExecutionTracer.new(enabled: true)
tracer.trace(:created, work, worker_name: "MyWorker")

Class-based usage (for backward compatibility)

ExecutionTracer.enabled = true
ExecutionTracer.trace(:created, work, worker_name: "MyWorker")

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(enabled: nil, trace_stream: nil, check_env: true) ⇒ ExecutionTracer

Initialize a new execution tracer instance.

Parameters:

  • enabled (Boolean) (defaults to: nil) —

    Whether tracing is enabled

  • trace_stream (IO) (defaults to: nil) —

    Output stream for trace messages

  • check_env (Boolean) (defaults to: true) —

    Whether to check FRACTOR_TRACE env var



22
23
24
25
26
 
# File 'lib/fractor/execution_tracer.rb', line 22

def initialize(enabled: nil, trace_stream: nil, check_env: true)
  @enabled = enabled || (check_env && ENV["FRACTOR_TRACE"] == "1")
  @trace_stream = trace_stream || $stderr
  @check_env = check_env
end

Instance Attribute Details

#enabled ⇒ Object (readonly)

Returns the value of attribute enabled.



15
16
17
 
# File 'lib/fractor/execution_tracer.rb', line 15

def enabled
  @enabled
end

#trace_stream ⇒ Object

Returns the value of attribute trace_stream.



15
16
17
 
# File 'lib/fractor/execution_tracer.rb', line 15

def trace_stream
  @trace_stream
end

Class Method Details

.enabled=(value) ⇒ Object

Enable or disable tracing (global).

Parameters:

  • value (Boolean) —

    Whether to enable tracing



82
83
84
 
# File 'lib/fractor/execution_tracer.rb', line 82

def enabled=(value)
  instance.enabled = value
end

.enabled? ⇒ Boolean

Check if global tracing is enabled.

Returns:

  • (Boolean) —

    true if tracing is enabled



89
90
91
 
# File 'lib/fractor/execution_tracer.rb', line 89

def enabled?
  instance.enabled?
end

.instance ⇒ ExecutionTracer

Get the singleton tracer instance.

Returns:



124
125
126
 
# File 'lib/fractor/execution_tracer.rb', line 124

def instance
  @instance ||= new
end

.reset! ⇒ Object

Reset all global state (useful for testing and isolation).



117
118
119
 
# File 'lib/fractor/execution_tracer.rb', line 117

def reset!
  instance.reset!
end

.trace(event, work = nil, context = {}) ⇒ Object

Trace an event using the global tracer instance.

Parameters:

  • event (Symbol) —

    The event type

  • work (Work) (defaults to: nil) —

    The work item

  • context (Hash) (defaults to: {}) —

    Additional context



98
99
100
 
# File 'lib/fractor/execution_tracer.rb', line 98

def trace(event, work = nil, context = {})
  instance.trace(event, work, context)
end

.trace_stream ⇒ IO

Get the global trace stream.

Returns:

  • (IO) —

    The output stream



105
106
107
 
# File 'lib/fractor/execution_tracer.rb', line 105

def trace_stream
  instance.trace_stream
end

.trace_stream=(io) ⇒ Object

Set a custom global trace stream.

Parameters:

  • io (IO) —

    The output stream



112
113
114
 
# File 'lib/fractor/execution_tracer.rb', line 112

def trace_stream=(io)
  instance.trace_stream = io
end

Instance Method Details

#disable! ⇒ Object

Disable tracing.



59
60
61
 
# File 'lib/fractor/execution_tracer.rb', line 59

def disable!
  @enabled = false
end

#enable! ⇒ Object

Enable tracing.



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

def enable!
  @enabled = true
end

#enabled? ⇒ Boolean

Check if tracing is enabled.

Returns:

  • (Boolean) —

    true if tracing is enabled



66
67
68
 
# File 'lib/fractor/execution_tracer.rb', line 66

def enabled?
  @enabled || (@check_env && ENV["FRACTOR_TRACE"] == "1")
end

#reset! ⇒ Object

Reset tracer state.



71
72
73
74
 
# File 'lib/fractor/execution_tracer.rb', line 71

def reset!
  @enabled = nil
  @trace_stream = $stderr
end

#trace(event, work = nil, context = {}) ⇒ Object

Trace an event in the work item lifecycle.

Parameters:

  • event (Symbol) —

    The event type (:created, :queued, :assigned, :processing, :completed, :failed)

  • work (Work) (defaults to: nil) —

    The work item

  • context (Hash) (defaults to: {}) —

    Additional context (worker_name, timestamp, etc.)



33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/fractor/execution_tracer.rb', line 33

def trace(event, work = nil, context = {})
  return unless enabled?

  timestamp = Time.now.strftime("%Y-%m-%d %H:%M:%S.%3N")
  thread_id = Thread.current.object_id

  # Build trace line
  trace_line = build_trace_line(timestamp, event, work, context, thread_id)

  # Output to trace stream
  trace_stream.puts(trace_line)
end