rage-rb 1.19.1 → 1.20.0

data/lib/rage/telemetry/handler.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+##
+# 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 {Rage::Telemetry::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 {Rage::Telemetry::SpanResult} which contains information about the span execution.
+#
+# @example
+#   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 Rage::Telemetry::Handler
+  class << self
+    # @private
+    attr_accessor :handlers_map
+
+    # Defines which spans the handler will observe and which method to invoke for those spans.
+    #
+    # @param span_ids [Array<String>] one or more span IDs to observe; supports wildcards (`*`) to match multiple spans
+    # @param with [Symbol] the method name to invoke when the specified spans are executed
+    # @param except [String, Array<String>, nil] optional list of span IDs to exclude from observation; supports wildcards (`*`) to match multiple spans
+    # @raise [ArgumentError] if any specified span ID is unknown or if no spans match a wildcard ID
+    #
+    # @example Observe a specific span
+    #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #     handle "controller.action.process", with: :my_handler_method
+    #
+    #     def my_handler_method
+    #       # ...
+    #     end
+    #   end
+    #
+    # @example Observe multiple spans with wildcards
+    #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #     handle "cable.*", with: :my_handler_method
+    #
+    #     def my_handler_method
+    #       # ...
+    #     end
+    #   end
+    #
+    # @example 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
+    #
+    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
+
+    # @private
+    def inherited(klass)
+      klass.handlers_map = @handlers_map.freeze
+    end
+
+    private
+
+    def resolve_span_ids(span_ids)
+      all_span_ids = Rage::Telemetry.__registry.keys
+      return all_span_ids if span_ids.include?("*")
+
+      exact_span_ids, wildcard_span_ids = [], []
+
+      # separate span IDs based on whether they contain wildcards
+      span_ids.each do |span_id|
+        if span_id.include?("*")
+          wildcard_span_ids << span_id
+        else
+          exact_span_ids << span_id
+        end
+      end
+
+      # validate exact span IDs
+      resolved_span_ids = []
+
+      exact_span_ids.each do |span_id|
+        unless all_span_ids.include?(span_id)
+          raise ArgumentError, "Unknown span ID '#{span_id}'"
+        end
+
+        resolved_span_ids << span_id
+      end
+
+      # validate and resolve wildcard span IDs
+      wildcard_span_ids.each do |span_id|
+        matcher = Regexp.new(span_id.gsub("*", "\\w+").gsub(".", "\\."))
+        matched_span_ids = all_span_ids.select { |id| id.match?(matcher) }
+
+        unless matched_span_ids.any?
+          raise ArgumentError, "No spans match the wildcard ID '#{span_id}'"
+        end
+
+        resolved_span_ids += matched_span_ids
+      end
+
+      resolved_span_ids
+    end
+  end
+end

data/lib/rage/telemetry/spans/await_fiber.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **core.fiber.await** span wraps the processing of the {Fiber.await} call.
+#
+# This span is started when a fiber begins awaiting other fibers, and ends when all awaited fibers have completed.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::AwaitFiber
+  class << self
+    # @private
+    def id
+      "core.fiber.await"
+    end
+
+    # @private
+    def span_parameters
+      %w[fibers:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Fiber.await"',
+        fibers: "Array(fibers)"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["core.fiber.await"] ID of the span
+    #   # @param name ["Fiber.await"] human-readable name of the operation
+    #   # @param fibers [Array<Fiber>] the fibers the current fiber is awaiting
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "core.fiber.await", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, fibers:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, fibers:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/broadcast_cable_stream.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **cable.stream.broadcast** span wraps the process of broadcasting a message to a `Rage::Cable` stream.
+#
+# This span is started when {Rage::Cable.broadcast Rage::Cable.broadcast} is called, and ends when the broadcast operation is complete.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::BroadcastCableStream
+  class << self
+    # @private
+    def id
+      "cable.stream.broadcast"
+    end
+
+    # @private
+    def span_parameters
+      %w[stream:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Rage::Cable.broadcast"',
+        stream: "stream"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["cable.stream.broadcast"] ID of the span
+    #   # @param name ["Rage::Cable.broadcast"] human-readable name of the operation
+    #   # @param stream [String] the name of the stream to which the message is being broadcasted
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "cable.stream.broadcast", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, stream:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, stream:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/create_websocket_connection.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **cable.websocket.handshake** span wraps the WebSocket connection handshake process.
+#
+# This span is started when a WebSocket connection is being established and is finished once the handshake is complete.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::CreateWebsocketConnection
+  class << self
+    # @private
+    def id
+      "cable.websocket.handshake"
+    end
+
+    # @private
+    def span_parameters
+      %w[env:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"WebSocket.handshake"',
+        env: "env"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["cable.websocket.handshake"] ID of the span
+    #   # @param name ["WebSocket.handshake"] human-readable name of the operation
+    #   # @param env [Hash] Rack environment hash that will be attached to the underlying WebSocket connection, allowing you to associate arbitrary data with the connection
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "cable.websocket.handshake", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, env:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, env:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/dispatch_fiber.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+##
+# The **core.fiber.dispatch** span tracks the scheduling and processing of system-level fibers created by the framework to process requests and deferred tasks.
+#
+# This span is started when a system fiber begins processing and ends when the fiber has completed processing.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::DispatchFiber
+  class << self
+    # @private
+    def id
+      "core.fiber.dispatch"
+    end
+
+    # @private
+    def span_parameters
+      []
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Fiber.dispatch"'
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["core.fiber.dispatch"] ID of the span
+    #   # @param name ["Fiber.dispatch"] human-readable name of the operation
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "core.fiber.dispatch", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/enqueue_deferred_task.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+##
+# The **deferred.task.enqueue** span tracks the enqueuing of a deferred task.
+#
+# This span is triggered when a deferred task is enqueued.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::EnqueueDeferredTask
+  class << self
+    # @private
+    def id
+      "deferred.task.enqueue"
+    end
+
+    # @private
+    def span_parameters
+      %w[task_class: context:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"#{task_class}#enqueue"',
+        task_class: "task_class",
+        task_context: "Rage::Deferred::Context.get_or_create_user_context(context)"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["deferred.task.enqueue"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `SendConfirmationEmail#enqueue`)
+    #   # @param task_class [Class] the deferred task being enqueued
+    #   # @param task_context [Hash] the context is serialized together with the deferred task and allows passing data between telemetry handlers or deferred middleware without exposing it to the task itself
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "deferred.task.enqueue", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, task_class:, task_context:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, task_class:, task_context:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/process_cable_action.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+##
+# The **cable.action.process** span wraps the processing of a single {Rage::Cable Rage::Cable} channel action.
+#
+# This span is started just before the action method is invoked on the channel, and is ended immediately after the action method returns.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::ProcessCableAction
+  class << self
+    # @private
+    def id
+      "cable.action.process"
+    end
+
+    # @private
+    def span_parameters
+      %w[channel: data: action:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"#{channel.class}##{action}"',
+        channel: "channel",
+        action: "action",
+        data: "data",
+        env: "channel.__connection.env"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["cable.action.process"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `ChatChannel#receive`)
+    #   # @param channel [Rage::Cable::Channel] the channel instance processing the action
+    #   # @param action [Symbol] the name of the action method being invoked
+    #   # @param data [Hash, nil] the data payload sent with the action
+    #   # @param env [Hash] the Rack environment associated with the WebSocket connection
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "cable.action.process", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, channel:, action:, data:, env:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, channel:, action:, data:, env:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/process_cable_connection.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+##
+# The **cable.connection.process** span wraps the processing of a connection action in {Rage::Cable Rage::Cable}.
+#
+# This span is started just before the action method is invoked on the channel, and is ended immediately after the action method returns.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::ProcessCableConnection
+  class << self
+    # @private
+    def id
+      "cable.connection.process"
+    end
+
+    # @private
+    def span_parameters
+      %w[connection: env: action:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"#{connection.class}##{action}"',
+        connection: "connection",
+        request: "connection.request",
+        action: "action",
+        env: "env"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["cable.connection.process"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `RageCable::Connection#connect`)
+    #   # @param connection [Rage::Cable::Connection] the connection being processed
+    #   # @param request [Rage::Request] the request object associated with the WebSocket connection
+    #   # @param action [:connect, :disconnect] the action being performed on the connection
+    #   # @param env [Hash] the Rack environment associated with the WebSocket connection
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "cable.connection.process", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, connection:, request:, action:, env:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, connection:, request:, action:, env:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/process_controller_action.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+##
+# The **controller.action.process** span wraps the processing of a controller action.
+#
+# This span is emitted for every controller action that is executed.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::ProcessControllerAction
+  class << self
+    # @private
+    def id
+      "controller.action.process"
+    end
+
+    # @private
+    def span_parameters
+      %w[controller: params:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"#{controller.class}##{params[:action]}"',
+        controller: "controller",
+        request: "controller.request",
+        response: "controller.response",
+        env: "controller.__env"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["controller.action.process"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `"UsersController#index"`)
+    #   # @param controller [RageController::API] the controller instance being executed
+    #   # @param request [Rage::Request] the request object associated with the action
+    #   # @param response [Rage::Response] the response object associated with the action
+    #   # @param env [Hash] the Rack environment
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "controller.action.process", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, controller:, request:, response:, env:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, controller:, request:, response:, env:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/process_deferred_task.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+##
+# The **deferred.task.process** span tracks the processing of a deferred task.
+#
+# This span is started when a deferred task begins processing and ends when the task has completed processing.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::ProcessDeferredTask
+  class << self
+    # @private
+    def id
+      "deferred.task.process"
+    end
+
+    # @private
+    def span_parameters
+      %w[task: context:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"#{task.class}#perform"',
+        task: "task",
+        task_class: "task.class",
+        task_context: "Rage::Deferred::Context.get_or_create_user_context(context)"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["deferred.task.process"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `SendConfirmationEmail#perform`)
+    #   # @param task [Rage::Deferred::Task] the deferred task being processed
+    #   # @param task_class [Class] the class of the deferred task being processed
+    #   # @param task_context [Hash] the context is serialized together with the deferred task and allows passing data between telemetry handlers or deferred middleware without exposing it to the task itself
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "deferred.task.process", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, task:, task_class:, task_context:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, task:, task_class:, task_context:)
+    #   end
+  end
+end

data/lib/rage/telemetry/spans/process_event_subscriber.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+##
+# The **events.subscriber.process** span tracks the processing of an event by a subscriber.
+#
+# This span is started when an event begins processing by a subscriber and ends when the processing has completed.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::ProcessEventSubscriber
+  class << self
+    # @private
+    def id
+      "events.subscriber.process"
+    end
+
+    # @private
+    def span_parameters
+      %w[event: context: subscriber:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"#{subscriber.class}#call"',
+        subscriber: "subscriber",
+        event: "event",
+        context: "context"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["events.subscriber.process"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `UpdateRecommendations#call`)
+    #   # @param subscriber [Rage::Events::Subscriber] the subscriber instance processing the event
+    #   # @param event [Object] the event being processed
+    #   # @param context [Object, nil] the additional context passed along with the event
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "events.subscriber.process", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, subscriber:, event:, context:)
+    #   #       yield
+    #   #     end
+    #   #   end
+    #   # @note Rage automatically detects which parameters your handler method accepts and only passes those parameters.
+    #   #   You can omit any of the parameters described here.
+    #   def handle(id:, name:, subscriber:, event:, context:)
+    #   end
+  end
+end