rage-rb 1.19.2 → 1.20.0

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

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+##
+# The **events.event.publish** span tracks the publishing of an event.
+#
+# This span is triggered whenever an event is published via {Rage::Events.publish Rage::Events.publish}.
+# See {handle handle} for the list of arguments passed to handler methods.
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+#
+class Rage::Telemetry::Spans::PublishEvent
+  class << self
+    # @private
+    def id
+      "events.event.publish"
+    end
+
+    # @private
+    def span_parameters
+      %w[event: context:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Events.publish(#{event.class})"',
+        event: "event",
+        context: "context",
+        subscriber_classes: "Rage::Events.__get_subscribers(event.class)"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["events.event.publish"] ID of the span
+    #   # @param name [String] human-readable name of the operation (e.g., `Events.publish(UpdateRecommendations)`)
+    #   # @param event [Object] the event being published
+    #   # @param context [Object, nil] the additional context passed along with the event
+    #   # @param subscriber_classes [Array<Rage::Events::Subscriber>] the list of subscriber classes that will receive the event
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "events.event.publish", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, event:, context:, subscriber_classes:)
+    #   #       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:, event:, context:, subscriber_classes:)
+    #   end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+##
+# The **core.fiber.spawn** span tracks the scheduling and processing of application-level fibers created via {Fiber.schedule}.
+#
+# This span is started when a 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::SpawnFiber
+  class << self
+    # @private
+    def id
+      "core.fiber.spawn"
+    end
+
+    # @private
+    def span_parameters
+      %w[parent:]
+    end
+
+    # @private
+    def handler_arguments
+      {
+        name: '"Fiber.schedule"',
+        parent: "parent"
+      }
+    end
+
+    # @!parse [ruby]
+    #   # @param id ["core.fiber.spawn"] ID of the span
+    #   # @param name ["Fiber.schedule"] human-readable name of the operation
+    #   # @param parent [Fiber] the parent fiber that the current fiber was scheduled from
+    #   # @yieldreturn [Rage::Telemetry::SpanResult]
+    #   #
+    #   # @example
+    #   #   class MyTelemetryHandler < Rage::Telemetry::Handler
+    #   #     handle "core.fiber.spawn", with: :my_handler
+    #   #
+    #   #     def my_handler(id:, name:, parent:)
+    #   #       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:, parent:)
+    #   end
+  end
+end

data/lib/rage/telemetry/telemetry.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+##
+# The `Rage::Telemetry` component provides an interface to monitor various operations and events within the Rage framework.
+#
+# To start using telemetry, define and register custom handlers that will process the telemetry data.
+#
+# 1. **Define Handlers**: Create custom telemetry handlers by subclassing {Rage::Telemetry::Handler Rage::Telemetry::Handler} and implementing the desired logic for processing telemetry data.
+#
+#     ```ruby
+#     class MyTelemetryHandler < Rage::Telemetry::Handler
+#       handle "controller.action.process", with: :log_action
+#
+#       def log_action(controller:)
+#         puts "Processing action: #{controller.action_name}"
+#         yield
+#       end
+#     end
+#     ```
+#
+# 2. **Register Handlers**: Register your custom handlers in the Rage configuration.
+#
+#     ```ruby
+#     Rage.configure do
+#       config.telemetry.use MyTelemetryHandler.new
+#     end
+#     ```
+#
+# @see Rage::Telemetry::Handler Rage::Telemetry::Handler
+# @see Rage::Telemetry::Spans Rage::Telemetry::Spans
+#
+module Rage::Telemetry
+  # Returns the list of all available telemetry spans.
+  # @return [Array<String>] the list of available telemetry spans
+  def self.available_spans
+    __registry.keys
+  end
+
+  # @private
+  def self.__registry
+    @__registry ||= Spans.constants.each_with_object({}) do |const, memo|
+      span = Spans.const_get(const)
+      memo[span.id] = span
+    end
+  end
+
+  # @private
+  def self.tracer
+    @tracer ||= Tracer.new(__registry, Rage.config.telemetry.handlers_map)
+  end
+
+  # @private
+  def self.__setup
+    tracer.setup
+  end
+
+  ##
+  # The namespace contains all telemetry span definitions.
+  # Each span represents a specific operation or event within the framework that can be monitored and traced.
+  #
+  # Spans always pass two standard keyword arguments to their handlers:
+  #
+  # * `:id` - The unique identifier of the span.
+  # * `:name` - The human-readable name of the operation.
+  #
+  # Handlers can also receive additional context-specific keyword arguments as defined by each span.
+  #
+  # # Available Spans
+  #
+  # | ID | Reference | Description |
+  # | --- | --- |
+  # | `core.fiber.dispatch` | {DispatchFiber} | Wraps the scheduling and processing of system-level fibers created by the framework to process requests and deferred tasks |
+  # | `core.fiber.spawn` | {SpawnFiber} | Wraps the scheduling and processing of application-level fibers created via {Fiber.schedule} |
+  # | `core.fiber.await` | {AwaitFiber} | Wraps the processing of the {Fiber.await} calls |
+  # | `controller.action.process` | {ProcessControllerAction} | Wraps the processing of controller actions |
+  # | `cable.websocket.handshake` | {CreateWebsocketConnection} | Wraps the WebSocket connection handshake process |
+  # | `cable.connection.process` | {ProcessCableConnection} | Wraps the processing of connect actions in {Rage::Cable Rage::Cable} |
+  # | `cable.action.process` | {ProcessCableAction} | Wraps the processing of {Rage::Cable Rage::Cable} channel actions |
+  # | `cable.stream.broadcast` | {BroadcastCableStream} | Wraps the broadcasting of messages to {Rage::Cable Rage::Cable} streams |
+  # | `deferred.task.enqueue` | {EnqueueDeferredTask} | Wraps the enqueuing of deferred tasks |
+  # | `deferred.task.process` | {ProcessDeferredTask} | Wraps the processing of deferred tasks |
+  # | `events.event.publish` | {PublishEvent} | Wraps the publishing of events via {Rage::Events Rage::Events} |
+  # | `events.subscriber.process` | {ProcessEventSubscriber} | Wraps the processing of events by subscribers |
+  #
+  module Spans
+  end
+
+  # @private
+  HandlerRef = Data.define(:instance, :method_name)
+
+  # Contains the result of a span execution.
+  # @!attribute [r] exception
+  #   @return [Exception, nil] The exception raised during the span execution, if any.
+  # @example
+  #   class MyTelemetryHandler < Rage::Telemetry::Handler
+  #     handle "controller.action.process", with: :monitor_500
+  #
+  #     def monitor_500
+  #       result = yield
+  #
+  #       if result.error?
+  #         MyObservabilitySDK.notify("500 Error Detected", result.exception)
+  #       end
+  #     end
+  #   end
+  SpanResult = Struct.new(:exception) do
+    # Returns `true` if the span resulted in an error.
+    def error?
+      !!exception
+    end
+
+    # Returns `true` if the span executed successfully.
+    def success?
+      !error?
+    end
+  end
+end
+
+require_relative "tracer"
+require_relative "handler"
+Dir["#{__dir__}/spans/*.rb"].each { |span| require_relative span }