Class: DSPy::Observability::AsyncSpanProcessor

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

Overview

AsyncSpanProcessor provides truly non-blocking span export using Async gem. Spans are queued and exported using async tasks with fiber-based concurrency. 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

Returns a new instance of AsyncSpanProcessor.



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

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

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

  start_export_task
end

Instance Method Details

#force_flush(timeout: nil) ⇒ Object 



100
101
102
103
104
 
# File 'lib/dspy/observability/async_span_processor.rb', line 100

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

  export_remaining_spans
end

#on_finish(span) ⇒ Object 



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
80
 
# File 'lib/dspy/observability/async_span_processor.rb', line 50

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 



46
47
48
 
# File 'lib/dspy/observability/async_span_processor.rb', line 46

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

#shutdown(timeout: nil) ⇒ Object 



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/dspy/observability/async_span_processor.rb', line 82

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

  begin
    # Export any remaining spans
    export_remaining_spans

    # Shutdown exporter
    @exporter.shutdown(timeout: timeout)

    OpenTelemetry::SDK::Trace::Export::SUCCESS
  rescue => e
    DSPy.log('observability.shutdown_error', error: e.message, class: e.class.name)
    OpenTelemetry::SDK::Trace::Export::FAILURE
  end
end