activejob-temporal 0.1.0

data/lib/activejob/temporal/observability/opentelemetry.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../observability"
+require_relative "../version"
+
+module ActiveJob
+  module Temporal
+    module Observability
+      class OpenTelemetry < Adapter
+        SPAN_EVENTS = %i[enqueue perform retry].freeze
+
+        attr_writer :tracer, :propagation
+
+        def initialize(tracer: nil, propagation: nil)
+          super(:opentelemetry)
+          @tracer = tracer
+          @propagation = propagation
+        end
+
+        def trace_context_for_enqueue(_payload)
+          carrier = {}
+          propagation.inject(carrier)
+          carrier
+        end
+
+        def record(event_name, payload)
+          return unless event_name == :enqueue
+
+          trace(:enqueue, payload) { nil }
+        end
+
+        def instrument(event_name, payload, &block)
+          return block.call unless SPAN_EVENTS.include?(event_name)
+
+          trace(event_name, payload, &block)
+        end
+
+        def validate_dependencies!
+          require_dependency("opentelemetry-sdk", "opentelemetry/sdk", "OpenTelemetry")
+          self
+        end
+
+        private
+
+        def trace(event_name, payload, &)
+          context = extracted_context(payload)
+          if context
+            ::OpenTelemetry::Context.with_current(context) do
+              trace_span(event_name, payload, &)
+            end
+          else
+            trace_span(event_name, payload, &)
+          end
+        end
+
+        def trace_span(event_name, payload)
+          tracer.in_span(span_name(event_name), attributes: span_attributes(payload)) do |span|
+            yield
+          rescue StandardError => e
+            span.record_exception(e) if span.respond_to?(:record_exception)
+            raise
+          end
+        end
+
+        def extracted_context(payload)
+          carrier = Observability.trace_context_from_payload(payload).fetch("opentelemetry", nil)
+          return if carrier.nil? || carrier.empty?
+
+          propagation.extract(carrier)
+        end
+
+        def tracer
+          @tracer ||= ::OpenTelemetry.tracer_provider.tracer(
+            "activejob-temporal",
+            ActiveJob::Temporal::VERSION
+          )
+        end
+
+        def propagation
+          @propagation ||= ::OpenTelemetry.propagation
+        end
+
+        def span_name(event_name)
+          "activejob_temporal.#{event_name}"
+        end
+
+        def span_attributes(payload)
+          {
+            "activejob_temporal.job_class" => payload[:job_class],
+            "activejob_temporal.job_id" => payload[:job_id],
+            "activejob_temporal.queue" => payload[:queue],
+            "activejob_temporal.workflow_id" => payload[:workflow_id],
+            "activejob_temporal.run_id" => payload[:run_id],
+            "activejob_temporal.namespace" => payload[:namespace],
+            "activejob_temporal.task_queue" => payload[:task_queue],
+            "activejob_temporal.attempt" => payload[:attempt]
+          }.compact
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Temporal::Observability.register_adapter(
+  :opentelemetry,
+  ActiveJob::Temporal::Observability::OpenTelemetry
+)

data/lib/activejob/temporal/observability/prometheus.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require_relative "../metrics_server"
+require_relative "../observability"
+
+module ActiveJob
+  module Temporal
+    module Observability
+      class MetricsServerConfiguration
+        attr_accessor :port, :bind, :allow_public_bind
+
+        def initialize
+          @port = nil
+          @bind = MetricsServer::DEFAULT_BIND_ADDRESS
+          @allow_public_bind = false
+        end
+      end
+
+      module PrometheusErrorLabels
+        LABEL_CLASSES = [
+          ActiveJob::DeserializationError,
+          ActiveJob::SerializationError,
+          NoMethodError,
+          NameError,
+          ArgumentError,
+          TypeError,
+          LoadError,
+          SystemCallError,
+          IOError,
+          RuntimeError,
+          StandardError,
+          ScriptError,
+          Exception
+        ].freeze
+
+        module_function
+
+        def for(error)
+          error_class = error_class_for(error)
+          label_class = LABEL_CLASSES.find { |klass| error_class <= klass }
+
+          (label_class&.name || "Unknown").to_s
+        end
+
+        def error_class_for(error)
+          return error if error.is_a?(Class)
+          return error.class if error.is_a?(Exception)
+
+          LABEL_CLASSES.find { |klass| klass.name == error.to_s } || StandardError
+        end
+      end
+
+      # rubocop:disable Metrics/ClassLength
+      class Prometheus < Adapter
+        DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120].freeze
+        PAYLOAD_SIZE_BUCKETS = [512, 1024, 2_048, 4_096, 8_192, 16_384, 32_768, 65_536, 131_072, 262_144,
+                                524_288, 1_048_576].freeze
+
+        attr_reader :registry, :metrics_server
+
+        def initialize(registry: nil, monotonic_clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          super(:prometheus)
+          @registry = registry
+          @monotonic_clock = monotonic_clock
+          @metrics_server = MetricsServerConfiguration.new
+          @server = nil
+          @registered = false
+        end
+
+        def start!
+          super
+          ensure_metrics_registered
+          self
+        end
+
+        def stop!
+          stop_metrics_server
+          super
+        end
+
+        def record(event_name, payload)
+          ensure_metrics_registered
+
+          case event_name
+          when :enqueue then record_enqueue(payload)
+          when :payload_serialize then observe_payload_size(payload)
+          when :retry then record_retry(payload)
+          when :worker_start then record_worker_started
+          when :worker_stop then record_worker_stopped
+          when :active_tasks then record_active_tasks(payload[:count])
+          end
+        end
+
+        def instrument(event_name, payload)
+          return yield unless event_name == :perform
+
+          ensure_metrics_registered
+          started_at = monotonic_time
+
+          result = yield
+          @jobs_completed.increment(labels: { class: label(payload[:job_class]), queue: label(payload[:queue]) })
+          result
+        rescue StandardError => e
+          @jobs_failed.increment(labels: {
+                                   class: label(payload[:job_class]),
+                                   queue: label(payload[:queue]),
+                                   error: PrometheusErrorLabels.for(e)
+                                 })
+          raise
+        ensure
+          if started_at
+            @job_duration.observe(monotonic_time - started_at, labels: { class: label(payload[:job_class]) })
+          end
+        end
+
+        def render
+          ensure_metrics_registered
+          ::Prometheus::Client::Formats::Text.marshal(registry)
+        end
+
+        def start_metrics_server(port: metrics_server.port,
+                                 bind_address: metrics_server.bind,
+                                 allow_public_bind: metrics_server.allow_public_bind)
+          raise ArgumentError, "Prometheus metrics server port is required" unless port
+
+          @server = MetricsServer.new(
+            port: port,
+            bind_address: bind_address,
+            allow_public_bind: allow_public_bind,
+            provider: self
+          ).start
+        end
+
+        def stop_metrics_server
+          @server&.stop
+          @server = nil
+        end
+
+        def validate_dependencies!
+          require_dependency("prometheus-client", "prometheus/client", "Prometheus")
+          require_dependency("prometheus-client", "prometheus/client/formats/text", "Prometheus")
+          @registry ||= ::Prometheus::Client::Registry.new
+          self
+        end
+
+        private
+
+        def record_enqueue(payload)
+          return if payload[:duplicate]
+
+          @jobs_enqueued.increment(labels: { class: label(payload[:job_class]), queue: label(payload[:queue]) })
+        end
+
+        def observe_payload_size(payload)
+          @payload_size.observe(payload[:bytes], labels: { class: label(payload[:job_class]) })
+        end
+
+        def record_retry(payload)
+          @retries.increment(labels: {
+                               class: label(payload[:job_class]),
+                               error: PrometheusErrorLabels.for(payload[:error])
+                             })
+        end
+
+        def record_worker_started
+          @active_workers.set(1)
+        end
+
+        def record_worker_stopped
+          @active_workers.set(0)
+          record_active_tasks(0)
+        end
+
+        def record_active_tasks(count)
+          @active_tasks.set(count.to_i)
+        end
+
+        def ensure_metrics_registered
+          validate_dependencies!
+          return if @registered
+
+          register_metrics
+          @registered = true
+        end
+
+        def register_metrics
+          register_counters
+          register_histograms
+          register_gauges
+        end
+
+        def register_counters
+          @jobs_enqueued = register_counter(
+            :activejob_temporal_jobs_enqueued_total,
+            "ActiveJob jobs successfully enqueued as Temporal workflows.",
+            labels: %i[class queue]
+          )
+          @jobs_completed = register_counter(
+            :activejob_temporal_jobs_completed_total,
+            "ActiveJob jobs completed by Temporal activities.",
+            labels: %i[class queue]
+          )
+          @jobs_failed = register_counter(
+            :activejob_temporal_jobs_failed_total,
+            "ActiveJob jobs failed during Temporal activity execution.",
+            labels: %i[class queue error]
+          )
+          @retries = register_counter(
+            :activejob_temporal_retries_total,
+            "ActiveJob Temporal retry attempts that failed.",
+            labels: %i[class error]
+          )
+        end
+
+        def register_histograms
+          @job_duration = register_histogram(
+            :activejob_temporal_job_duration_seconds,
+            "ActiveJob Temporal activity runner duration in seconds.",
+            labels: %i[class],
+            buckets: DURATION_BUCKETS
+          )
+          @payload_size = register_histogram(
+            :activejob_temporal_payload_size_bytes,
+            "Serialized ActiveJob payload size in bytes.",
+            labels: %i[class],
+            buckets: PAYLOAD_SIZE_BUCKETS
+          )
+        end
+
+        def register_gauges
+          @active_workers = register_gauge(
+            :activejob_temporal_active_workers,
+            "Active Temporal worker process state for this scrape target."
+          )
+          @active_tasks = register_gauge(
+            :activejob_temporal_active_tasks,
+            "Active Temporal activity tasks in this worker process."
+          )
+        end
+
+        def register_counter(name, docstring, labels: [])
+          registry.register(::Prometheus::Client::Counter.new(name, docstring: docstring, labels: labels))
+        end
+
+        def register_histogram(name, docstring, labels:, buckets:)
+          registry.register(
+            ::Prometheus::Client::Histogram.new(name, docstring: docstring, labels: labels, buckets: buckets)
+          )
+        end
+
+        def register_gauge(name, docstring)
+          registry.register(::Prometheus::Client::Gauge.new(name, docstring: docstring))
+        end
+
+        def monotonic_time
+          @monotonic_clock.call
+        end
+
+        def label(value)
+          (value || "unknown").to_s
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end
+
+ActiveJob::Temporal::Observability.register_adapter(
+  :prometheus,
+  ActiveJob::Temporal::Observability::Prometheus
+)

data/lib/activejob/temporal/observability.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module ActiveJob
+  module Temporal
+    class Error < StandardError; end unless const_defined?(:Error, false)
+
+    module Observability
+      EVENT_NAMESPACE = "activejob_temporal"
+      TRACE_CONTEXT_KEY = :observability
+
+      class Error < ActiveJob::Temporal::Error; end
+      class MissingDependency < Error; end
+      class UnknownAdapter < Error; end
+
+      class << self
+        def register_adapter(name, adapter_class)
+          adapter_registry[name.to_sym] = adapter_class
+        end
+
+        def adapter_class(name)
+          adapter_registry.fetch(name.to_sym) do
+            raise UnknownAdapter, "Unknown observability adapter: #{name.inspect}"
+          end
+        end
+
+        def emit(name, payload = {})
+          event_payload = normalize_payload(payload)
+          ActiveSupport::Notifications.instrument(event_name(name), event_payload)
+          active_adapters.each { |adapter| adapter.record(name.to_sym, event_payload) }
+          nil
+        end
+
+        def instrument(name, payload = {}, &)
+          event_payload = normalize_payload(payload)
+
+          ActiveSupport::Notifications.instrument(event_name(name), event_payload) do
+            instrument_adapters(name.to_sym, event_payload, &)
+          end
+        end
+
+        def trace_context_for_enqueue(payload = {})
+          active_adapters.each_with_object({}) do |adapter, context|
+            next unless adapter.respond_to?(:trace_context_for_enqueue)
+
+            adapter_context = adapter.trace_context_for_enqueue(payload)
+            context[adapter.name.to_s] = adapter_context if adapter_context && !adapter_context.empty?
+          end
+        end
+
+        def inject_trace_context(payload, attributes = {})
+          trace_context = trace_context_for_enqueue(attributes)
+          return payload if trace_context.empty?
+
+          observability = payload[:observability] || payload["observability"] || {}
+          observability = observability.merge("trace_context" => trace_context)
+          payload[:observability] = observability
+          payload
+        end
+
+        def trace_context_from_payload(payload)
+          observability = payload[:observability] || payload["observability"] || {}
+          observability[:trace_context] || observability["trace_context"] || {}
+        end
+
+        def attributes_from_job(job, **attributes)
+          normalize_payload(
+            {
+              job_class: job.class.name,
+              job_id: job.job_id,
+              queue: job.queue_name
+            }.merge(attributes)
+          )
+        end
+
+        def attributes_from_payload(payload, **attributes)
+          normalize_payload(
+            {
+              job_class: payload_value(payload, :job_class),
+              job_id: payload_value(payload, :job_id),
+              queue: payload_value(payload, :queue_name) || payload_value(payload, :queue),
+              task_queue: payload_value(payload, :activity_task_queue)
+            }.merge(activity_context_attributes).merge(attributes)
+          )
+        end
+
+        def retry_attempt?
+          attempt = activity_context_attributes[:attempt]
+          attempt && attempt.to_i > 1
+        end
+
+        def reset!
+          configuration.reset!
+        end
+
+        def configuration
+          ActiveJob::Temporal.config.observability
+        end
+
+        def event_name(name)
+          event = name.to_s
+          return event if event.end_with?(".#{EVENT_NAMESPACE}")
+
+          "#{event}.#{EVENT_NAMESPACE}"
+        end
+
+        private
+
+        def adapter_registry
+          @adapter_registry ||= {}
+        end
+
+        def active_adapters
+          return [] unless ActiveJob::Temporal.respond_to?(:config)
+
+          configuration.adapters
+        rescue StandardError
+          []
+        end
+
+        def instrument_adapters(name, payload, &block)
+          active_adapters.reverse.reduce(block) do |inner, adapter|
+            proc { adapter.instrument(name, payload, &inner) }
+          end.call
+        end
+
+        def normalize_payload(payload)
+          payload.each_with_object({}) do |(key, value), normalized|
+            normalized[key.to_sym] = value unless value.nil?
+          end
+        end
+
+        def payload_value(payload, key)
+          payload[key] || payload[key.to_s]
+        end
+
+        def activity_context_attributes
+          return {} unless defined?(Temporalio::Activity::Context)
+          return {} unless Temporalio::Activity::Context.exist?
+
+          info = Temporalio::Activity::Context.current.info
+          normalize_payload(
+            workflow_id: context_value(info, :workflow_id),
+            run_id: context_value(info, :workflow_run_id, :run_id),
+            namespace: context_value(info, :workflow_namespace),
+            attempt: context_value(info, :attempt)
+          )
+        rescue StandardError
+          {}
+        end
+
+        def context_value(object, *methods)
+          methods.each do |method_name|
+            return object.public_send(method_name) if object.respond_to?(method_name)
+          end
+
+          nil
+        end
+      end
+
+      class Configuration
+        attr_reader :adapters
+
+        def initialize
+          @adapters = []
+        end
+
+        def use(name, **)
+          adapter = Observability.adapter_class(name).new(**)
+          yield adapter if block_given?
+          adapter.start!
+          replace_adapter(adapter)
+          adapter
+        end
+
+        def adapter(name)
+          adapters.find { |registered_adapter| registered_adapter.name == name.to_sym }
+        end
+
+        def enabled?(name = nil)
+          return adapters.any? unless name
+
+          !adapter(name).nil?
+        end
+
+        def reset!
+          adapters.each(&:stop!)
+          adapters.clear
+        end
+
+        def validate!
+          adapters.each(&:validate!)
+        end
+
+        private
+
+        def replace_adapter(adapter)
+          previous_adapter = self.adapter(adapter.name)
+          previous_adapter&.stop!
+          adapters.delete(previous_adapter)
+          adapters << adapter
+        end
+      end
+
+      class Adapter
+        attr_reader :name
+
+        def initialize(name)
+          @name = name.to_sym
+          @started = false
+        end
+
+        def start!
+          validate!
+          @started = true
+          self
+        end
+
+        def stop!
+          @started = false
+          self
+        end
+
+        def started?
+          @started
+        end
+
+        def validate!
+          validate_dependencies!
+          self
+        end
+
+        def validate_dependencies!
+          self
+        end
+
+        def record(_event_name, _payload)
+          nil
+        end
+
+        def instrument(_event_name, _payload)
+          yield
+        end
+
+        private
+
+        def require_dependency(gem_name, require_path, adapter_name)
+          require require_path
+        rescue LoadError => e
+          raise unless e.path == require_path || e.message.include?(require_path)
+
+          raise MissingDependency,
+                "#{adapter_name} observability requires the `#{gem_name}` gem. " \
+                "Add `gem \"#{gem_name}\"` and require the adapter before enabling it."
+        end
+      end
+    end
+  end
+end