Class: Rage::Telemetry::Handler

Inherits:
Object
  • Object
show all
Defined in:
lib/rage/telemetry/handler.rb

Overview

The class allows developers to define telemetry handlers that observe and react to specific span executions.

Handlers are defined by subclassing Rage::Telemetry::Handler and using the handle class method to specify which spans to observe and which methods to invoke when those spans are executed.

See Spans for a list of available spans and arguments passed to the handler methods.

Each handler method is expected to call yield to pass control to the next handler in the stack or the framework’s core logic. The call to yield returns an instance of SpanResult which contains information about the span execution.

Examples:

class MyTelemetryHandler < Rage::Telemetry::Handler
  handle "controller.action.process", with: :create_span

  def create_span(name:)
    MyObservabilitySDK.in_span(name) do
      yield
    end
  end
end

Class Method Summary collapse

Class Method Details

.handle(*span_ids, with:, except: nil) ⇒ Object

Defines which spans the handler will observe and which method to invoke for those spans.

Examples:

Observe a specific span

class MyTelemetryHandler < Rage::Telemetry::Handler
  handle "controller.action.process", with: :my_handler_method

  def my_handler_method
    # ...
  end
end

Observe multiple spans with wildcards

class MyTelemetryHandler < Rage::Telemetry::Handler
  handle "cable.*", with: :my_handler_method

  def my_handler_method
    # ...
  end
end

Observe all spans except specific ones

class MyTelemetryHandler < Rage::Telemetry::Handler
  handle "*", except: "core.fiber.dispatch", with: :my_handler_method

  def my_handler_method
    # ...
  end
end

Parameters:

  • span_ids (Array<String>) —

    one or more span IDs to observe; supports wildcards (*) to match multiple spans

  • with (Symbol) —

    the method name to invoke when the specified spans are executed

  • except (String, Array<String>, nil) (defaults to: nil) —

    optional list of span IDs to exclude from observation; supports wildcards (*) to match multiple spans

Raises:

  • (ArgumentError) —

    if any specified span ID is unknown or if no spans match a wildcard ID



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/rage/telemetry/handler.rb', line 64

def handle(*span_ids, with:, except: nil)
  resolved_span_ids = resolve_span_ids(span_ids)

  if except
    resolved_span_ids -= resolve_span_ids(Array(except))
  end

  if @handlers_map.nil?
    @handlers_map = {}
  elsif @handlers_map.frozen?
    @handlers_map = @handlers_map.transform_values(&:dup)
  end

  resolved_span_ids.each do |span_id|
    @handlers_map[span_id] ||= Set.new
    @handlers_map[span_id] << with
  end
end