conductor_ruby 0.1.0

data/lib/conductor/worker/telemetry/metrics_collector.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'logger'
+require_relative '../events/listeners'
+require_relative '../events/global_dispatcher'
+
+module Conductor
+  module Worker
+    module Telemetry
+      # MetricsCollector - Canonical SDK worker metrics from the
+      # harmonization spec (sdk-metrics-harmonization.md).
+      #
+      # Uses camelCase domain labels (taskType, workflowType) and includes
+      # status labels on time histograms.
+      class MetricsCollector
+        include Events::TaskRunnerEventsListener
+        include Events::WorkflowEventsListener
+        include Events::HttpEventsListener
+
+        STATUS_SUCCESS = 'SUCCESS'
+        STATUS_FAILURE = 'FAILURE'
+
+        # @param backend [Symbol, Object] :null, :prometheus, or a custom backend
+        # @param subscribe_global_http [Boolean] Auto-subscribe to GlobalDispatcher
+        #   for HttpApiRequest events from the HTTP layer (default true).
+        # @param measure_payload_size [Boolean] Record workflow_input_size_bytes
+        #   (requires JSON serialization; default true). Set false to skip
+        #   serialization overhead for large payloads.
+        # @param logger [Logger, nil] Optional logger for diagnostic output in rescue blocks
+        # @return [MetricsCollector]
+        def self.create(backend: :null, subscribe_global_http: true, measure_payload_size: true, logger: nil)
+          new(backend: backend, subscribe_global_http: subscribe_global_http,
+              measure_payload_size: measure_payload_size, logger: logger)
+        end
+
+        def initialize(backend: :null, subscribe_global_http: true, measure_payload_size: true, logger: nil)
+          @backend = load_backend(backend)
+          @logger = logger || Logger.new(File::NULL)
+          @measure_payload_size = measure_payload_size
+          @http_listener = nil
+          subscribe_to_global_http_events if subscribe_global_http
+        end
+
+        attr_reader :backend, :measure_payload_size
+
+        def stop
+          return unless @http_listener
+
+          Events::GlobalDispatcher.instance.unregister(Events::HttpApiRequest, @http_listener)
+          @http_listener = nil
+        rescue StandardError => e
+          @logger.debug { "Telemetry error (non-fatal): #{e.class}: #{e.message}" }
+        end
+
+        # --- Task Runner Event Handlers ---
+
+        def on_poll_started(event)
+          @backend.increment('task_poll_total', labels: { taskType: event.task_type })
+        end
+
+        def on_poll_completed(event)
+          observe_time('task_poll_time_seconds', event.duration_ms,
+                       { taskType: event.task_type, status: STATUS_SUCCESS })
+        end
+
+        def on_poll_failure(event)
+          @backend.increment('task_poll_error_total',
+                             labels: { taskType: event.task_type, exception: event.cause.class.name })
+          observe_time('task_poll_time_seconds', event.duration_ms,
+                       { taskType: event.task_type, status: STATUS_FAILURE })
+        end
+
+        def on_task_execution_started(event)
+          @backend.increment('task_execution_started_total', labels: { taskType: event.task_type })
+        end
+
+        def on_task_execution_completed(event)
+          observe_time('task_execute_time_seconds', event.duration_ms,
+                       { taskType: event.task_type, status: STATUS_SUCCESS })
+
+          return unless event.output_size_bytes
+
+          @backend.observe('task_result_size_bytes', event.output_size_bytes,
+                           labels: { taskType: event.task_type })
+        end
+
+        def on_task_execution_failure(event)
+          @backend.increment('task_execute_error_total',
+                             labels: { taskType: event.task_type, exception: event.cause.class.name })
+          observe_time('task_execute_time_seconds', event.duration_ms,
+                       { taskType: event.task_type, status: STATUS_FAILURE })
+        end
+
+        def on_task_update_completed(event)
+          observe_time('task_update_time_seconds', event.duration_ms,
+                       { taskType: event.task_type, status: STATUS_SUCCESS })
+        end
+
+        def on_task_update_failure(event)
+          @backend.increment('task_update_error_total',
+                             labels: { taskType: event.task_type, exception: event.cause.class.name })
+
+          return unless event.respond_to?(:duration_ms) && event.duration_ms
+
+          observe_time('task_update_time_seconds', event.duration_ms,
+                       { taskType: event.task_type, status: STATUS_FAILURE })
+        end
+
+        def on_task_paused(event)
+          @backend.increment('task_paused_total', labels: { taskType: event.task_type })
+        end
+
+        def on_thread_uncaught_exception(event)
+          @backend.increment('thread_uncaught_exceptions_total',
+                             labels: { exception: event.cause.class.name })
+        end
+
+        def on_active_workers_changed(event)
+          @backend.set('active_workers', event.count, labels: { taskType: event.task_type })
+        end
+
+        # --- Workflow Event Handlers ---
+
+        def on_workflow_start_error(event)
+          @backend.increment('workflow_start_error_total',
+                             labels: { workflowType: event.workflow_type,
+                                       exception: event.cause.class.name })
+        end
+
+        def on_workflow_input_size(event)
+          return unless @measure_payload_size
+
+          @backend.observe('workflow_input_size_bytes', event.size_bytes,
+                           labels: { workflowType: event.workflow_type,
+                                     version: (event.version || '').to_s })
+        end
+
+        # --- HTTP Event Handlers ---
+
+        def on_http_api_request(event)
+          observe_time('http_api_client_request_seconds', event.duration_ms,
+                       { method: event.method, uri: event.uri, status: event.status })
+        end
+
+        private
+
+        def observe_time(name, duration_ms, labels)
+          @backend.observe(name, duration_ms / 1000.0, labels: labels)
+        end
+
+        def subscribe_to_global_http_events
+          @http_listener = ->(event) { on_http_api_request(event) }
+          Events::GlobalDispatcher.instance.register(Events::HttpApiRequest, @http_listener)
+        rescue StandardError => e
+          @logger.debug { "Telemetry error (non-fatal): #{e.class}: #{e.message}" }
+        end
+
+        def load_backend(backend)
+          case backend
+          when :null, nil
+            NullBackend.new
+          when :prometheus
+            load_prometheus_backend
+          else
+            backend
+          end
+        end
+
+        def load_prometheus_backend
+          require_relative 'prometheus_backend'
+          PrometheusBackend.new
+        rescue LoadError
+          raise ConfigurationError,
+                "The 'prometheus-client' gem is required for Prometheus metrics. " \
+                "Add `gem 'prometheus-client'` to your Gemfile."
+        end
+      end
+
+      # NullBackend - No-op backend for metrics
+      # Used when metrics are disabled or not configured
+      class NullBackend
+        def increment(name, labels: {})
+          # No-op
+        end
+
+        def observe(name, value, labels: {})
+          # No-op
+        end
+
+        def set(name, value, labels: {})
+          # No-op
+        end
+      end
+    end
+  end
+end

data/lib/conductor/worker/telemetry/prometheus_backend.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Conductor
+  module Worker
+    module Telemetry
+      # PrometheusBackend - Prometheus backend for the canonical SDK metric catalog.
+      #
+      # Pre-registers every metric from the harmonization spec with its canonical
+      # label set and bucket configuration. Uses camelCase domain labels (taskType,
+      # workflowType) per the canonical convention.
+      class PrometheusBackend
+        TIME_BUCKETS = [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10].freeze
+        SIZE_BUCKETS = [100, 1000, 10_000, 100_000, 1_000_000, 10_000_000].freeze
+
+        COUNTER_LABELS = {
+          'task_poll_total' => %i[taskType],
+          'task_execution_started_total' => %i[taskType],
+          'task_poll_error_total' => %i[taskType exception],
+          'task_execute_error_total' => %i[taskType exception],
+          'task_update_error_total' => %i[taskType exception],
+          'task_paused_total' => %i[taskType],
+          'thread_uncaught_exceptions_total' => %i[exception],
+          'workflow_start_error_total' => %i[workflowType exception]
+        }.freeze
+
+        HISTOGRAM_LABELS = {
+          'task_poll_time_seconds' => %i[taskType status],
+          'task_execute_time_seconds' => %i[taskType status],
+          'task_update_time_seconds' => %i[taskType status],
+          'http_api_client_request_seconds' => %i[method uri status],
+          'task_result_size_bytes' => %i[taskType],
+          'workflow_input_size_bytes' => %i[workflowType version]
+        }.freeze
+
+        GAUGE_LABELS = {
+          'active_workers' => %i[taskType]
+        }.freeze
+
+        HISTOGRAM_BUCKETS = {
+          'task_result_size_bytes' => SIZE_BUCKETS,
+          'workflow_input_size_bytes' => SIZE_BUCKETS
+        }.freeze
+
+        def initialize(registry: nil)
+          load_prometheus_client
+          @registry = registry || Prometheus::Client.registry
+          @counters = {}
+          @histograms = {}
+          @gauges = {}
+          setup_metrics
+        end
+
+        def increment(name, labels: {}, value: 1)
+          metric = get_or_create_counter(name)
+          metric.increment(labels: normalize_labels(name, labels, COUNTER_LABELS), by: value)
+        end
+
+        def observe(name, value, labels: {})
+          metric = get_or_create_histogram(name)
+          metric.observe(value, labels: normalize_labels(name, labels, HISTOGRAM_LABELS))
+        end
+
+        def set(name, value, labels: {})
+          metric = get_or_create_gauge(name)
+          metric.set(value, labels: normalize_labels(name, labels, GAUGE_LABELS))
+        end
+
+        attr_reader :registry
+
+        private
+
+        def load_prometheus_client
+          require 'prometheus/client'
+        rescue LoadError
+          raise ConfigurationError,
+                "The 'prometheus-client' gem is required for Prometheus metrics. " \
+                "Add `gem 'prometheus-client'` to your Gemfile."
+        end
+
+        def setup_metrics
+          COUNTER_LABELS.each do |name, _|
+            register_counter(name, "Counter for #{name}")
+          end
+
+          HISTOGRAM_LABELS.each do |name, _|
+            register_histogram(name, "Histogram for #{name}")
+          end
+
+          GAUGE_LABELS.each do |name, _|
+            register_gauge(name, "Gauge for #{name}")
+          end
+        end
+
+        def register_counter(name, docstring)
+          metric_name = name.to_sym
+          labels = COUNTER_LABELS.fetch(name, %i[taskType])
+          @counters[name] = register_or_reuse(metric_name) do
+            Prometheus::Client::Counter.new(metric_name, docstring: docstring, labels: labels)
+          end
+        end
+
+        def register_histogram(name, docstring)
+          metric_name = name.to_sym
+          labels = HISTOGRAM_LABELS.fetch(name, %i[taskType])
+          buckets = HISTOGRAM_BUCKETS[name] || TIME_BUCKETS
+          @histograms[name] = register_or_reuse(metric_name) do
+            Prometheus::Client::Histogram.new(metric_name, docstring: docstring,
+                                                           labels: labels, buckets: buckets)
+          end
+        end
+
+        def register_gauge(name, docstring)
+          metric_name = name.to_sym
+          labels = GAUGE_LABELS.fetch(name, %i[taskType])
+          @gauges[name] = register_or_reuse(metric_name) do
+            Prometheus::Client::Gauge.new(metric_name, docstring: docstring, labels: labels)
+          end
+        end
+
+        def register_or_reuse(metric_name)
+          if @registry.exist?(metric_name)
+            @registry.get(metric_name)
+          else
+            metric = yield
+            @registry.register(metric)
+            metric
+          end
+        end
+
+        def get_or_create_counter(name)
+          @counters[name] ||= register_or_reuse(name.to_sym) do
+            labels = COUNTER_LABELS.fetch(name, %i[taskType])
+            Prometheus::Client::Counter.new(name.to_sym, docstring: "Counter for #{name}", labels: labels)
+          end
+        end
+
+        def get_or_create_histogram(name)
+          @histograms[name] ||= register_or_reuse(name.to_sym) do
+            labels = HISTOGRAM_LABELS.fetch(name, %i[taskType])
+            buckets = HISTOGRAM_BUCKETS[name] || TIME_BUCKETS
+            Prometheus::Client::Histogram.new(name.to_sym, docstring: "Histogram for #{name}",
+                                                           labels: labels, buckets: buckets)
+          end
+        end
+
+        def get_or_create_gauge(name)
+          @gauges[name] ||= register_or_reuse(name.to_sym) do
+            labels = GAUGE_LABELS.fetch(name, %i[taskType])
+            Prometheus::Client::Gauge.new(name.to_sym, docstring: "Gauge for #{name}", labels: labels)
+          end
+        end
+
+        # Align provided labels to the declared label set for the metric.
+        # Missing keys get empty-string defaults; unknown keys are dropped.
+        def normalize_labels(name, labels, schema)
+          symbolized = {}
+          labels.each do |key, value|
+            next if value.nil?
+
+            symbolized[key.to_sym] = value.to_s
+          end
+
+          declared = schema[name]
+          return symbolized unless declared
+
+          declared.each_with_object({}) do |key, acc|
+            acc[key] = symbolized.key?(key) ? symbolized[key] : ''
+          end
+        end
+      end
+
+      # MetricsServer - HTTP server for exposing Prometheus metrics
+      # Serves metrics at /metrics endpoint
+      class MetricsServer
+        DEFAULT_PORT = 9090
+
+        # @param port [Integer] Port to listen on (default: 9090)
+        # @param registry [Prometheus::Client::Registry] Prometheus registry
+        def initialize(port: DEFAULT_PORT, registry: nil)
+          require 'prometheus/client'
+          require 'prometheus/client/formats/text'
+          require 'webrick'
+
+          @port = port
+          @registry = registry || Prometheus::Client.registry
+          @server = nil
+        end
+
+        # Start the metrics server in a background thread
+        # @return [Thread] Server thread
+        def start
+          @server = WEBrick::HTTPServer.new(
+            Port: @port,
+            Logger: WEBrick::Log.new('/dev/null'),
+            AccessLog: []
+          )
+
+          @server.mount_proc '/metrics' do |_req, res|
+            res.content_type = 'text/plain; version=0.0.4'
+            res.body = Prometheus::Client::Formats::Text.marshal(@registry)
+          end
+
+          @server.mount_proc '/health' do |_req, res|
+            res.content_type = 'application/json'
+            res.body = '{"status":"healthy"}'
+          end
+
+          @thread = Thread.new { @server.start }
+          @thread.name = 'prometheus-metrics-server'
+          @thread
+        end
+
+        # Stop the metrics server
+        def stop
+          @server&.shutdown
+          @thread&.join(5)
+        end
+
+        # @return [Integer] Server port
+        attr_reader :port
+      end
+    end
+  end
+end