Class: DSPy::Observability::AsyncSpanProcessor

Inherits:
Object
  • Object
show all
Defined in:
lib/dspy/o11y/async_span_processor.rb

Overview

AsyncSpanProcessor provides non-blocking span export using concurrent-ruby. Spans are queued and exported on a dedicated single-thread executor to avoid blocking clients. Implements the same interface as OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor

Constant Summary collapse

DEFAULT_QUEUE_SIZE =

Default configuration values

1000
DEFAULT_EXPORT_INTERVAL =

seconds

60.0
DEFAULT_EXPORT_BATCH_SIZE = 
100
DEFAULT_SHUTDOWN_TIMEOUT =

seconds

10.0
DEFAULT_MAX_RETRIES = 
3

Instance Method Summary collapse

Constructor Details

#initialize(exporter, queue_size: DEFAULT_QUEUE_SIZE, export_interval: DEFAULT_EXPORT_INTERVAL, export_batch_size: DEFAULT_EXPORT_BATCH_SIZE, shutdown_timeout: DEFAULT_SHUTDOWN_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES) ⇒ AsyncSpanProcessor 



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/dspy/o11y/async_span_processor.rb', line 21

def initialize(
  exporter,
  queue_size: DEFAULT_QUEUE_SIZE,
  export_interval: DEFAULT_EXPORT_INTERVAL,
  export_batch_size: DEFAULT_EXPORT_BATCH_SIZE,
  shutdown_timeout: DEFAULT_SHUTDOWN_TIMEOUT,
  max_retries: DEFAULT_MAX_RETRIES
)
  @exporter = exporter
  @queue_size = queue_size
  @export_interval = export_interval
  @export_batch_size = export_batch_size
  @shutdown_timeout = shutdown_timeout
  @max_retries = max_retries
  @export_executor = Concurrent::SingleThreadExecutor.new

  # Use thread-safe queue for cross-fiber communication
  @queue = Thread::Queue.new
  @shutdown_requested = false
  @timer_thread = nil

  start_export_task
end

Instance Method Details

#force_flush(timeout: nil) ⇒ Object 



112
113
114
115
116
 
# File 'lib/dspy/o11y/async_span_processor.rb', line 112

def force_flush(timeout: nil)
  return OpenTelemetry::SDK::Trace::Export::SUCCESS if @queue.empty?

  export_remaining_spans(timeout: timeout, export_all: true)
end

#on_finish(span) ⇒ Object 



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/dspy/o11y/async_span_processor.rb', line 49

def on_finish(span)
  # Only process sampled spans to match BatchSpanProcessor behavior
  return unless span.context.trace_flags.sampled?

  # Non-blocking enqueue with overflow protection
  # Note: on_finish is only called for already ended spans
  begin
    # Check queue size (non-blocking)
    if @queue.size >= @queue_size
      # Drop oldest span
      begin
        dropped_span = @queue.pop(true) # non-blocking pop
        DSPy.log('observability.span_dropped',
                 reason: 'queue_full',
                 queue_size: @queue_size)
      rescue ThreadError
        # Queue was empty, continue
      end
    end

    @queue.push(span)
    
    # Log span queuing activity
    DSPy.log('observability.span_queued', queue_size: @queue.size)

    # Trigger immediate export if batch size reached
    trigger_export_if_batch_full
  rescue => e
    DSPy.log('observability.enqueue_error', error: e.message)
  end
end

#on_start(span, parent_context) ⇒ Object 



45
46
47
 
# File 'lib/dspy/o11y/async_span_processor.rb', line 45

def on_start(span, parent_context)
  # Non-blocking - no operation needed on span start
end

#shutdown(timeout: nil) ⇒ Object 



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/dspy/o11y/async_span_processor.rb', line 81

def shutdown(timeout: nil)
  timeout ||= @shutdown_timeout
  @shutdown_requested = true

  begin
    # Export any remaining spans
    result = export_remaining_spans(timeout: timeout, export_all: true)

    future = Concurrent::Promises.future_on(@export_executor) do
      @exporter.shutdown(timeout: timeout)
    end
    future.value!(timeout)

    result
  rescue => e
    DSPy.log('observability.shutdown_error', error: e.message, class: e.class.name)
    OpenTelemetry::SDK::Trace::Export::FAILURE
  ensure
    begin
      @timer_thread&.join(timeout)
      @timer_thread&.kill if @timer_thread&.alive?
    rescue StandardError
      # ignore timer shutdown issues
    end
    @export_executor.shutdown
    unless @export_executor.wait_for_termination(timeout)
      @export_executor.kill
    end
  end
end