Class: Tasker::Telemetry::TraceBackend

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/tasker/telemetry/trace_backend.rb

Overview

TraceBackend provides thread-safe trace event collection and routing

This class implements Tasker's core tracing system with thread-safe operations, automatic EventRouter integration, and support for distributed tracing backends like Jaeger, Zipkin, or OpenTelemetry.

The backend follows the same singleton pattern as MetricsBackend for consistency and provides structured trace data collection with span hierarchy support.

Examples:

Basic usage

backend = TraceBackend.instance
backend.start_span('task.execution', { task_id: '123' })
backend.finish_span('task.execution', { status: 'success' })

EventRouter integration

# Automatic trace collection based on event routing
backend.handle_event('task.started', { task_id: '123', context: { user_id: 456 } })

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ TraceBackend

Returns a new instance of TraceBackend.



38
39
40
41
42
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 38

def initialize
  @traces = Concurrent::Hash.new
  @created_at = Time.current
  @instance_id = Socket.gethostname
end

Instance Attribute Details

#created_at ⇒ Time (readonly)

Backend creation timestamp for monitoring

Returns:

  • (Time) —

    When this backend was initialized



36
37
38
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 36

def created_at
  @created_at
end

#traces ⇒ Concurrent::Hash (readonly)

Core trace storage for active spans Using ConcurrentHash for thread-safe operations without locks

Returns:

  • (Concurrent::Hash) —

    Thread-safe trace storage



32
33
34
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 32

def traces
  @traces
end

Instance Method Details

#export ⇒ Hash

Export all collected trace data

Returns:

  • (Hash) —

    All trace data with metadata



93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 93

def export
  {
    traces: @traces.transform_values(&:dup),
    metadata: {
      backend: 'trace',
      instance_id: @instance_id,
      created_at: @created_at.iso8601,
      exported_at: Time.current.iso8601,
      trace_count: @traces.size
    }
  }
end

#handle_event(event_name, payload = {}) ⇒ Boolean

Handle an event from EventRouter and collect appropriate trace data

This method is called by EventRouter when an event should be routed to the trace backend. It automatically creates trace spans based on event type and payload.

Examples:

Automatic usage via EventRouter

# EventRouter calls this automatically:
backend.handle_event('task.started', {
  task_id: '123',
  operation: 'process_payment',
  context: { user_id: 456, session_id: 'abc' }
})

Parameters:

  • event_name (String) —

    The lifecycle event name

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

    Event payload with trace data

Returns:

  • (Boolean) —

    True if trace data was collected successfully



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 62

def handle_event(event_name, payload = {})
  return false unless payload.is_a?(Hash)

  trace_data = {
    event_name: event_name,
    timestamp: Time.current.iso8601,
    payload: payload,
    instance_id: @instance_id
  }

  case event_name
  when /\.started$/
    handle_start_event(trace_data)
  when /\.completed$/, /\.failed$/
    handle_finish_event(trace_data)
  when /\.before_/, /\.after_/
    handle_span_event(trace_data)
  else
    handle_generic_event(trace_data)
  end

  true
rescue StandardError => e
  # Log error but don't raise to prevent breaking the event flow
  Rails.logger&.error("TraceBackend error handling #{event_name}: #{e.message}")
  false
end

#reset! ⇒ void

This method returns an undefined value.

Clear all trace data (primarily for testing)



109
110
111
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 109

def reset!
  @traces.clear
end

#stats ⇒ Hash

Get trace statistics

Returns:

  • (Hash) —

    Statistics about collected traces



116
117
118
119
120
121
122
 
# File 'lib/tasker/telemetry/trace_backend.rb', line 116

def stats
  {
    active_traces: @traces.size,
    backend_uptime: Time.current - @created_at,
    instance_id: @instance_id
  }
end