job-workflow 0.1.3

data/lib/job_workflow/hook_registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class HookRegistry
+    #:  () -> void
+    def initialize
+      self.before_hooks = [] #: Array[Hook]
+      self.after_hooks = [] #: Array[Hook]
+      self.around_hooks = [] #: Array[Hook]
+      self.error_hooks = [] #: Array[ErrorHook]
+    end
+
+    #:  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def add_before_hook(task_names:, block:)
+      before_hooks << Hook.new(task_names:, block:)
+    end
+
+    #:  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def add_after_hook(task_names:, block:)
+      after_hooks << Hook.new(task_names:, block:)
+    end
+
+    #:  (task_names: Array[Symbol], block: ^(Context, ?TaskCallable) -> void) -> void
+    def add_around_hook(task_names:, block:)
+      around_hooks << Hook.new(task_names:, block:)
+    end
+
+    #:  (task_names: Array[Symbol], block: ^(Context, StandardError, Task) -> void) -> void
+    def add_error_hook(task_names:, block:)
+      error_hooks << ErrorHook.new(task_names:, block:)
+    end
+
+    #:  (Symbol) -> Array[Hook]
+    def before_hooks_for(task_name)
+      hooks_for(before_hooks, task_name)
+    end
+
+    #:  (Symbol) -> Array[Hook]
+    def after_hooks_for(task_name)
+      hooks_for(after_hooks, task_name)
+    end
+
+    #:  (Symbol) -> Array[Hook]
+    def around_hooks_for(task_name)
+      hooks_for(around_hooks, task_name)
+    end
+
+    #:  (Symbol) -> Array[ErrorHook]
+    def error_hooks_for(task_name)
+      hooks_for(error_hooks, task_name)
+    end
+
+    private
+
+    attr_accessor :before_hooks #: Array[Hook]
+    attr_accessor :after_hooks #: Array[Hook]
+    attr_accessor :around_hooks #: Array[Hook]
+    attr_accessor :error_hooks #: Array[ErrorHook]
+
+    #:  (Array[Hook], Symbol) -> Array[Hook]
+    #:  (Array[ErrorHook], Symbol) -> Array[ErrorHook]
+    def hooks_for(hooks, task_name)
+      hooks.filter { |hook| hook.applies_to?(task_name) }
+    end
+  end
+end

data/lib/job_workflow/instrumentation/log_subscriber.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Instrumentation
+    # LogSubscriber handles JobWorkflow instrumentation events and produces structured JSON logs.
+    # It subscribes to ActiveSupport::Notifications events and formats them for logging.
+    #
+    # @example Enable log subscriber
+    #   ```ruby
+    #   JobWorkflow::Instrumentation::LogSubscriber.attach_to(:job_workflow)
+    #   ```
+    class LogSubscriber < ActiveSupport::LogSubscriber
+      class << self
+        #:  () -> void
+        def attach!
+          attach_to(NAMESPACE.to_sym)
+        end
+      end
+
+      # @rbs!
+      #   type log_level = :debug | :info | :warn | :error
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def workflow(event)
+        # Tracing only - no log output (start/complete events handle logging)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def workflow_start(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def workflow_complete(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task(event)
+        # Tracing only - no log output (start/complete events handle logging)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task_start(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task_complete(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task_error(event)
+        log_event(event, :error)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task_skip(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task_enqueue(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def task_retry(event)
+        log_event(event, :warn)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def throttle_acquire(event)
+        # Tracing only - no log output (start/complete events handle logging)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def throttle_acquire_start(event)
+        log_event(event, :debug)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def throttle_acquire_complete(event)
+        log_event(event, :debug)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def throttle_release(event)
+        log_event(event, :debug)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def dependent_wait(event)
+        # Tracing only - no log output (start/complete events handle logging)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def dependent_wait_start(event)
+        log_event(event, :debug)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def dependent_wait_complete(event)
+        log_event(event, :debug)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def queue_pause(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def queue_resume(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def dry_run(event)
+        # Tracing only - no log output (skip/execute events handle logging)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def dry_run_skip(event)
+        log_event(event, :info)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> void
+      def dry_run_execute(event)
+        log_event(event, :debug)
+      end
+
+      private
+
+      #:  (ActiveSupport::Notifications::Event, log_level) -> void
+      def log_event(event, level)
+        payload_hash = build_log_payload(event)
+        send_log(level, payload_hash)
+      end
+
+      #:  (ActiveSupport::Notifications::Event) -> Hash[Symbol, untyped]
+      def build_log_payload(event)
+        base = { event: event.name, duration_ms: event.duration&.round(3) }
+        base.merge(extract_loggable_attributes(event.payload))
+      end
+
+      #:  (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def extract_loggable_attributes(payload)
+        payload_keys = %i[
+          job_id
+          job_name
+          task_name
+          each_index
+          retry_count
+          reason
+          sub_job_count
+          attempt
+          max_attempts
+          delay_seconds
+          concurrency_key
+          concurrency_limit
+          dependent_task_name
+          queue_name
+          dry_run_name
+          dry_run_index
+          dry_run
+        ]
+        result = payload.slice(*payload_keys)
+        add_error_attributes(result, payload)
+        result
+      end
+
+      #:  (Hash[Symbol, untyped], Hash[Symbol, untyped]) -> void
+      def add_error_attributes(result, payload)
+        return unless payload.key?(:error)
+
+        error = payload[:error]
+        result.merge!(
+          error_class: payload[:error_class] || error.class.name,
+          error_message: payload[:error_message] || error.message
+        )
+      end
+
+      #:  (log_level, Hash[Symbol, untyped]) -> void
+      def send_log(level, payload)
+        return JobWorkflow.logger.debug(payload) if level == :debug
+        return JobWorkflow.logger.warn(payload) if level == :warn
+        return JobWorkflow.logger.error(payload) if level == :error
+
+        JobWorkflow.logger.info(payload)
+      end
+    end
+  end
+end

data/lib/job_workflow/instrumentation/opentelemetry_subscriber.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Instrumentation
+    # OpenTelemetrySubscriber provides OpenTelemetry tracing integration for JobWorkflow events.
+    # It subscribes to ActiveSupport::Notifications and creates OpenTelemetry spans.
+    #
+    # @example Enable OpenTelemetry integration
+    #   ```ruby
+    #   # Ensure OpenTelemetry is configured first
+    #   OpenTelemetry::SDK.configure do |c|
+    #     c.service_name = "my-app"
+    #   end
+    #
+    #   # Then subscribe JobWorkflow events
+    #   JobWorkflow::Instrumentation::OpenTelemetrySubscriber.subscribe!
+    #   ```
+    #
+    # @note This subscriber requires the opentelemetry-api gem to be installed.
+    #   If not available, subscription will be silently skipped.
+    class OpenTelemetrySubscriber # rubocop:disable Metrics/ClassLength
+      module Attributes
+        JOB_NAME = "#{NAMESPACE}.job.name".freeze #: String
+        JOB_ID = "#{NAMESPACE}.job.id".freeze #: String
+        TASK_NAME = "#{NAMESPACE}.task.name".freeze #: String
+        TASK_EACH_INDEX = "#{NAMESPACE}.task.each_index".freeze #: String
+        TASK_RETRY_COUNT = "#{NAMESPACE}.task.retry_count".freeze #: String
+        WORKFLOW_NAME = "#{NAMESPACE}.workflow.name".freeze #: String
+        ERROR_CLASS = "#{NAMESPACE}.error.class".freeze #: String
+        ERROR_MESSAGE = "#{NAMESPACE}.error.message".freeze #: String
+        CONCURRENCY_KEY = "#{NAMESPACE}.concurrency.key".freeze #: String
+        CONCURRENCY_LIMIT = "#{NAMESPACE}.concurrency.limit".freeze #: String
+      end
+
+      SUBSCRIBED_EVENTS = [
+        Events::WORKFLOW,
+        Events::TASK,
+        Events::TASK_SKIP,
+        Events::TASK_ENQUEUE,
+        Events::TASK_RETRY,
+        Events::THROTTLE_ACQUIRE,
+        Events::DEPENDENT_WAIT
+      ].freeze
+
+      # @rbs!
+      #   def self.subscriptions: () -> Array[untyped]
+      #   def self.subscriptions=: (Array[untyped]) -> void
+      cattr_accessor :subscriptions, instance_accessor: false, default: []
+
+      class << self
+        #:  () -> Array[untyped]?
+        def subscribe!
+          return unless opentelemetry_available?
+          return subscriptions unless subscriptions.empty?
+
+          self.subscriptions = SUBSCRIBED_EVENTS.map { |event| ActiveSupport::Notifications.subscribe(event, new) }
+        end
+
+        #:  () -> void
+        def unsubscribe!
+          return if subscriptions.empty?
+
+          subscriptions.each { |sub| ActiveSupport::Notifications.unsubscribe(sub) }
+          self.subscriptions = []
+        end
+
+        #:  () -> void
+        def reset!
+          unsubscribe!
+        end
+
+        #:  () -> bool
+        def opentelemetry_available?
+          !!defined?(::OpenTelemetry::Trace)
+        end
+      end
+
+      #:  (String, String, Hash[Symbol, untyped]) -> void
+      def start(name, _id, payload)
+        return unless self.class.opentelemetry_available?
+
+        span = start_span(name, payload)
+        token = attach_span_context(span)
+        store_span_info(payload, span, token)
+      rescue StandardError => e
+        handle_error(e)
+      end
+
+      #:  (String, String, Hash[Symbol, untyped]) -> void
+      def finish(_name, _id, payload)
+        return unless self.class.opentelemetry_available?
+
+        span, token = extract_otel_info(payload)
+        return if span.nil? || token.nil?
+
+        handle_exception(payload, span)
+      rescue StandardError => e
+        handle_error(e)
+      ensure
+        finish_span(span, token) if span || token
+      end
+
+      private
+
+      #:  (Hash[Symbol, untyped]) -> Array[untyped?]
+      def extract_otel_info(payload)
+        otel = payload.delete(:__otel)
+        span = otel&.fetch(:span)
+        token = otel&.fetch(:ctx_token)
+        [span, token]
+      end
+
+      def start_span(name, payload)
+        span_name = build_span_name(name, payload)
+        attributes = build_attributes(payload)
+        kind = determine_span_kind(name)
+
+        tracer.start_span(span_name, kind:, attributes:)
+      end
+
+      #:  (untyped) -> untyped
+      def attach_span_context(span)
+        OpenTelemetry::Context.attach(OpenTelemetry::Trace.context_with_span(span))
+      end
+
+      #:  (Hash[Symbol, untyped], untyped, untyped) -> void
+      def store_span_info(payload, span, token)
+        payload[:__otel] = { span: span, ctx_token: token }
+      end
+
+      #:  (Hash[Symbol, untyped], untyped) -> void
+      def handle_exception(payload, span)
+        error = payload[:error] || payload[:exception_object]
+        return unless error
+
+        span.record_exception(error)
+        span.status = OpenTelemetry::Trace::Status.error("Unhandled exception: #{error.class}")
+      end
+
+      #:  (untyped, untyped) -> void
+      def finish_span(span, token)
+        finish_span_safe(span)
+        detach_context_safe(token)
+      end
+
+      #:  (untyped) -> void
+      def finish_span_safe(span)
+        return unless span&.recording?
+
+        span.status = OpenTelemetry::Trace::Status.ok if span.status.code == OpenTelemetry::Trace::Status::UNSET
+        span.finish
+      rescue StandardError => e
+        handle_error(e)
+      end
+
+      #:  (untyped) -> void
+      def detach_context_safe(token)
+        OpenTelemetry::Context.detach(token) if token
+      rescue StandardError => e
+        handle_error(e)
+      end
+
+      #:  (String, Hash[Symbol, untyped]) -> String
+      def build_span_name(event_name, payload)
+        base_name = event_name.delete_suffix(".#{Instrumentation::NAMESPACE}")
+
+        return "#{payload[:job_name]}.#{payload[:task_name]} #{base_name}" if payload[:task_name]
+        return "#{payload[:job_name]} #{base_name}" if payload[:job_name]
+
+        "JobWorkflow #{base_name}"
+      end
+
+      #:  (Hash[Symbol, untyped]) -> Hash[String, untyped]
+      def build_attributes(payload)
+        attrs = {
+          Attributes::JOB_NAME => payload[:job_name],
+          Attributes::JOB_ID => payload[:job_id],
+          Attributes::TASK_NAME => payload[:task_name],
+          Attributes::TASK_EACH_INDEX => payload[:each_index],
+          Attributes::TASK_RETRY_COUNT => payload[:retry_count],
+          Attributes::CONCURRENCY_KEY => payload[:concurrency_key],
+          Attributes::CONCURRENCY_LIMIT => payload[:concurrency_limit]
+        }.compact
+        add_error_attributes(attrs, payload)
+        attrs
+      end
+
+      #:  (Hash[String, untyped], Hash[Symbol, untyped]) -> void
+      def add_error_attributes(attrs, payload)
+        return unless payload[:error]
+
+        attrs.merge!(
+          Attributes::ERROR_CLASS => payload[:error_class] || payload[:error].class.name,
+          Attributes::ERROR_MESSAGE => payload[:error_message] || payload[:error].message
+        )
+      end
+
+      #:  (String) -> Symbol
+      def determine_span_kind(event_name)
+        case event_name
+        when Events::TASK_ENQUEUE
+          :producer
+        else
+          :internal
+        end
+      end
+
+      #:  () -> untyped
+      def tracer
+        OpenTelemetry.tracer_provider.tracer(NAMESPACE, JobWorkflow::VERSION)
+      end
+
+      #:  (StandardError) -> void
+      def handle_error(error)
+        return unless defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:handle_error)
+
+        OpenTelemetry.handle_error(exception: error, message: "JobWorkflow OpenTelemetry subscriber error")
+      end
+    end
+  end
+end