pgbus 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9e7369bd90c71a1c25bc9fdafe8905d8cdca99e5ae1deffb9c7b304aecc881d
-  data.tar.gz: 44d3fb5bf94742541ba5f9474c06cc602b2a7490decb7daee846c4b8f5ce1bbe
+  metadata.gz: 97572298add12c78b7d9f3ebb6a50af36a9803380d42202a66031ce7f1018d4c
+  data.tar.gz: b5498b051a4c1d134c2944d1b0c556124fef49a7276ee32cbe0172fac12f6c8d
 SHA512:
-  metadata.gz: be5efa4a81ec3244475bdbbda0dd90aad02076f422ffc0f6def444e5a0553a875a414a3f98049dff7a3471700515168ac7cab1e4394d379d8a316cea4d1981e4
-  data.tar.gz: 515bf628c80f44252579432eb34d27c3f14fb830a7be0e479ca98b5d5651823c5dfb044276d44e9624e122accfab1faf93479827fcf92a5cacc75ef300a534f7
+  metadata.gz: ec8b0af9bac7c6156b12effa0ce3d3ecf9a29f06c091f5117c5567114c00f44c6dea26666306ff9b084c0b616aa3e47b5080d986c1159fcedf64e5fbfe1f909a
+  data.tar.gz: 0227ab4f57df35bd89c4dac8a022df20a16d8c30eaaff0cbc75c8a49e8debf9dba62e1fb54b1ac26c327aab6199398ac2fe1575db9b1ad1062fb0d6b21083ffc

data/app/controllers/pgbus/api/metrics_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Api
+    class MetricsController < ApplicationController
+      PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+      def show
+        return head(:not_found) unless Pgbus.configuration.metrics_enabled
+
+        body = Web::MetricsSerializer.new(data_source).serialize
+        render plain: body, content_type: PROMETHEUS_CONTENT_TYPE
+      end
+    end
+  end
+end

data/app/models/pgbus/job_stat.rb

@@ -30,21 +30,34 @@ module Pgbus
     # Memoized — intentionally never invalidated at runtime. If the
     # pgbus_job_stats migration runs while the app is already running,
     # a restart is required for stat recording to begin.
+    #
+    # We only memoize a *successful* probe. A transient error (PG
+    # hiccup during boot, connection refused during a failover) is
+    # treated as "don't know yet" — the next call retries. Caching
+    # false on the first hiccup would permanently disable job stats
+    # for the process lifetime, which is a worse failure mode than
+    # a few retries. See issue #98 / PR #91 (StreamStat fix).
     def self.table_exists?
       return @table_exists if defined?(@table_exists)
 
       @table_exists = connection.table_exists?(table_name)
-    rescue StandardError
-      @table_exists = false
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus] Failed to check job stat table: #{e.message}" }
+      false
     end
 
     # Memoized — checks if the latency migration has been applied.
+    # Same transient-error handling as `table_exists?`: a failed
+    # probe is not cached, so a later successful probe can still
+    # enable latency recording.
     def self.latency_columns?
       return @latency_columns if defined?(@latency_columns)
+      return false unless table_exists?
 
-      @latency_columns = table_exists? && column_names.include?("enqueue_latency_ms")
-    rescue StandardError
-      @latency_columns = false
+      @latency_columns = column_names.include?("enqueue_latency_ms")
+    rescue StandardError => e
+      Pgbus.logger.debug { "[Pgbus] Failed to check job stat latency columns: #{e.message}" }
+      false
     end
 
     # Throughput: jobs per minute bucketed by minute for the last N minutes

data/config/routes.rb

@@ -82,6 +82,7 @@ Pgbus::Engine.routes.draw do
   namespace :api do
     get :stats, to: "stats#show"
     get :insights, to: "insights#show"
+    get :metrics, to: "metrics#show"
   end
 
   scope :frontend, controller: :frontends, defaults: { version: Pgbus::VERSION.tr(".", "-") } do

data/lib/pgbus/active_job/executor.rb

@@ -161,6 +161,36 @@ module Pgbus
           error: error,
           retry_count: [message.read_ct.to_i - 1, 0].max
         )
+
+        apply_retry_backoff(message, queue_name, payload)
+      end
+
+      # Extend the message's visibility timeout with exponential backoff
+      # so retries aren't all bunched at the default flat VT interval.
+      # Skipped on the first read (read_ct=1) — that's the initial
+      # attempt, not a retry.
+      def apply_retry_backoff(message, queue_name, payload)
+        attempt = message.read_ct.to_i - 1
+        return if attempt < 1
+
+        job_class = resolve_job_class(payload)
+        delay = if job_class
+                  RetryBackoff.compute_delay_for_job(job_class, attempt: attempt)
+                else
+                  RetryBackoff.compute_delay(attempt: attempt)
+                end
+
+        client.set_visibility_timeout(queue_name, message.msg_id.to_i, vt: delay)
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] Retry backoff VT update failed: #{e.message}" }
+      end
+
+      def resolve_job_class(payload)
+        return unless payload.is_a?(Hash) && payload["job_class"]
+
+        payload["job_class"].constantize
+      rescue NameError
+        nil
       end
 
       def instrument(event_name, payload = {})

data/lib/pgbus/client/read_after.rb

@@ -24,6 +24,10 @@ module Pgbus
         end
 
         rows.map { |row| build_envelope(row) }
+      rescue StandardError => e
+        raise unless missing_stream_queue?(e, sanitized)
+
+        []
       end
 
       def stream_current_msg_id(stream_name)
@@ -34,6 +38,10 @@ module Pgbus
             conn.exec(sql).first.fetch("max").to_i
           end
         end
+      rescue StandardError => e
+        raise unless missing_stream_queue?(e, sanitized)
+
+        0
       end
 
       def stream_oldest_msg_id(stream_name)
@@ -50,10 +58,53 @@ module Pgbus
             value&.to_i
           end
         end
+      rescue StandardError => e
+        raise unless missing_stream_queue?(e, sanitized)
+
+        nil
       end
 
       private
 
+      # True if +error+ is a PG::UndefinedTable (or an
+      # ActiveRecord::StatementInvalid wrapping one) complaining about
+      # the stream's own PGMQ queue table (pgmq.q_<sanitized> or
+      # pgmq.a_<sanitized>).
+      #
+      # The stream-watermark and replay SQL above run on every page render
+      # for streams like `pgbus_stream_from Current.user`, but the queue
+      # table is only created on the FIRST broadcast via
+      # `ensure_stream_queue`. On a fresh database the very first page
+      # render therefore reads from a table that doesn't exist yet —
+      # semantically, "no queue" means "no messages" and must translate
+      # to a 0 watermark / empty replay rather than an exception. Any
+      # OTHER UndefinedTable (wrong schema, typo, operator error) still
+      # propagates so real bugs don't get swallowed.
+      #
+      # See issues #101 and #104. The comparison is case-insensitive because
+      # Postgres downcases unquoted identifiers in its error output, while
+      # `sanitized` can contain uppercase characters for GlobalID-keyed streams
+      # (e.g. `pgbus_stream_Z2lkOi8vY29zbW9zL1VzZXIvMQ` from
+      # `pgbus_stream_from Current.user`). A case-sensitive substring match
+      # would miss the downcased relation name and let the exception escape.
+      #
+      # The regex uses `\b` word boundaries so `pgmq.q_<needle>` doesn't
+      # accidentally match longer related identifiers like
+      # `pgmq.q_<needle>_archive` — a PGMQ internal object we'd want to
+      # propagate as a real error rather than silently swallow.
+      def missing_stream_queue?(error, sanitized)
+        pg_error = pg_undefined_table?(error) ? error : error.cause
+        return false unless pg_undefined_table?(pg_error)
+
+        message = pg_error.message.to_s.downcase
+        needle = Regexp.escape(sanitized.downcase)
+        message.match?(/\bpgmq\.(?:q|a)_#{needle}\b/)
+      end
+
+      def pg_undefined_table?(error)
+        defined?(::PG::UndefinedTable) && error.is_a?(::PG::UndefinedTable)
+      end
+
       # Builds the union of live and archive tables. The outer ORDER BY + LIMIT
       # ensures we never return more than `limit` rows total even if both
       # subqueries hit it. The 'live'/'archive' constants are how the streamer

data/lib/pgbus/configuration.rb

@@ -37,6 +37,10 @@ module Pgbus
     # Dead letter queue
     attr_accessor :max_retries
 
+    # Retry backoff for the VT-based retry path (unhandled exceptions).
+    # Jobs can override these per-class via Pgbus::RetryBackoff::JobMixin.
+    attr_accessor :retry_backoff, :retry_backoff_max, :retry_backoff_jitter
+
     # Priority queues
     attr_accessor :priority_levels, :default_priority
 
@@ -82,7 +86,8 @@ module Pgbus
 
     # Web dashboard
     attr_accessor :web_auth, :web_refresh_interval, :web_per_page, :web_live_updates, :web_data_source,
-                  :insights_default_minutes, :base_controller_class, :return_to_app_url
+                  :insights_default_minutes, :base_controller_class, :return_to_app_url,
+                  :metrics_enabled
 
     # Streams (turbo-rails replacement, SSE-based)
     attr_accessor :streams_enabled, :streams_queue_prefix, :streams_signed_name_secret,
@@ -116,6 +121,9 @@ module Pgbus
       @circuit_breaker_enabled = true
 
       @max_retries = 5
+      @retry_backoff = 5          # seconds — first VT-retry delay
+      @retry_backoff_max = 300    # 5 minutes cap
+      @retry_backoff_jitter = 0.15
 
       @priority_levels = nil
       @default_priority = 1
@@ -157,6 +165,7 @@ module Pgbus
       @insights_default_minutes = 30 * 24 * 60 # 30 days
       @base_controller_class = "::ActionController::Base"
       @return_to_app_url = nil
+      @metrics_enabled = true
 
       @streams_enabled = true
       @streams_queue_prefix = "pgbus_stream"
@@ -189,8 +198,7 @@ module Pgbus
 
     def queue_name(name)
       full = "#{queue_prefix}_#{name}"
-      QueueNameValidator.validate!(full)
-      full
+      QueueNameValidator.normalize(full)
     end
 
     def dead_letter_queue_name(name)
@@ -227,6 +235,11 @@ module Pgbus
       raise ArgumentError, "polling_interval must be > 0" unless polling_interval.is_a?(Numeric) && polling_interval.positive?
       raise ArgumentError, "visibility_timeout must be > 0" unless visibility_timeout.is_a?(Numeric) && visibility_timeout.positive?
       raise ArgumentError, "max_retries must be >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
+      raise ArgumentError, "retry_backoff must be > 0" unless retry_backoff.is_a?(Numeric) && retry_backoff.positive?
+      raise ArgumentError, "retry_backoff_max must be > 0" unless retry_backoff_max.is_a?(Numeric) && retry_backoff_max.positive?
+      unless retry_backoff_jitter.is_a?(Numeric) && retry_backoff_jitter >= 0 && retry_backoff_jitter <= 1
+        raise ArgumentError, "retry_backoff_jitter must be between 0 and 1"
+      end
 
       Array(workers).each do |w|
         threads = w[:threads] || w["threads"] || 5

data/lib/pgbus/process/worker.rb

@@ -87,6 +87,11 @@ module Pgbus
 
       WILDCARD_REFRESH_INTERVAL = 30 # seconds
 
+      # Matches the physical queue name inside a "relation \"pgmq.q_foo\" does
+      # not exist" error. Frozen module constant to avoid recompiling the
+      # regex on every queue-missing error in hot fetch/read paths.
+      MISSING_QUEUE_REGEX = /pgmq\.q_(\w+)/
+
       private
 
       def claim_and_execute
@@ -255,8 +260,8 @@ module Pgbus
       # Extract the queue name from the error and remove it from the active list.
       def evict_missing_queues(error)
         prefix = "#{config.queue_prefix}_"
-        if error.message =~ /pgmq\.q_(\w+)/
-          physical_name = Regexp.last_match(1)
+        if (match = MISSING_QUEUE_REGEX.match(error.message))
+          physical_name = match[1]
           logical_name = physical_name.delete_prefix(prefix)
           if @queues.delete(logical_name)
             Pgbus.logger.warn { "[Pgbus] Evicted deleted queue '#{logical_name}' (#{physical_name}) from worker" }

data/lib/pgbus/queue_name_validator.rb

@@ -34,6 +34,23 @@ module Pgbus
       name
     end
 
+    # Normalizes a queue name by replacing common separators (hyphens, dots)
+    # with underscores, stripping remaining invalid characters, and collapsing
+    # consecutive underscores. Use this for names from external sources
+    # (e.g., Turbo stream names like "hotwire-livereload") where the intent
+    # is to derive a valid PGMQ queue name that preserves readability.
+    def normalize(name)
+      name = name.to_s
+      return validate!(name) if VALID_QUEUE_NAME_PATTERN.match?(name)
+
+      normalized = name.gsub(/[-.]/, "_")           # hyphens/dots → underscores
+                       .gsub(/[^a-zA-Z0-9_]/, "")   # strip remaining invalid chars
+                       .gsub(/_+/, "_")              # collapse consecutive underscores
+                       .gsub(/\A_|_\z/, "")          # strip leading/trailing underscores
+      validate!(normalized)
+      normalized
+    end
+
     # Sanitizes a queue name by removing invalid characters, then validates.
     # Use this for names from untrusted sources (e.g., URL params).
     def sanitize!(name)

data/lib/pgbus/retry_backoff.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Computes exponential backoff delays for the VT-based retry path
+  # (unhandled exceptions that fall through ActiveJob's retry_on).
+  #
+  # The formula mirrors the CircuitBreaker pattern already used
+  # elsewhere in pgbus: base * 2^(attempt-1), capped at max,
+  # with optional jitter to prevent thundering-herd retries.
+  #
+  # Jobs can override the global config via the pgbus_retry_backoff
+  # class-level DSL (see JobMixin below).
+  module RetryBackoff
+    # Mixin for ActiveJob classes to declare per-job backoff config.
+    #
+    #   class ImportJob < ApplicationJob
+    #     include Pgbus::RetryBackoff::JobMixin
+    #     pgbus_retry_backoff base: 15, max: 120, jitter: 0.2
+    #   end
+    module JobMixin
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def pgbus_retry_backoff(base: nil, max: nil, jitter: nil)
+          raise ArgumentError, "retry_backoff base must be > 0" if !base.nil? && (!base.is_a?(Numeric) || base <= 0)
+          raise ArgumentError, "retry_backoff max must be > 0" if !max.nil? && (!max.is_a?(Numeric) || max <= 0)
+          if !jitter.nil? && (!jitter.is_a?(Numeric) || jitter.negative? || jitter > 1)
+            raise ArgumentError, "retry_backoff jitter must be between 0 and 1"
+          end
+
+          @pgbus_retry_backoff = {
+            base: base,
+            max: max,
+            jitter: jitter
+          }.compact.freeze
+        end
+
+        def pgbus_retry_backoff_config
+          @pgbus_retry_backoff
+        end
+      end
+    end
+
+    class << self
+      # Compute delay for a specific job class, falling back to global
+      # config for any options not overridden at the job level.
+      def compute_delay_for_job(job_class, attempt:, jitter: nil)
+        overrides = (job_class.respond_to?(:pgbus_retry_backoff_config) &&
+                    job_class.pgbus_retry_backoff_config) || {}
+
+        config = Pgbus.configuration
+        compute_delay(
+          attempt: attempt,
+          base: overrides[:base] || config.retry_backoff,
+          max: overrides[:max] || config.retry_backoff_max,
+          jitter: jitter || overrides[:jitter] || config.retry_backoff_jitter
+        )
+      end
+
+      # Core backoff computation.
+      #
+      # @param attempt [Integer] 1-based retry attempt number (read_ct - 1)
+      # @param base [Numeric] base delay in seconds (default: config.retry_backoff)
+      # @param max [Numeric] maximum delay cap (default: config.retry_backoff_max)
+      # @param jitter [Numeric] jitter factor 0..1 (default: config.retry_backoff_jitter)
+      # @return [Integer] delay in seconds
+      def compute_delay(attempt:, base: nil, max: nil, jitter: nil)
+        config = Pgbus.configuration
+        base ||= config.retry_backoff
+        max ||= config.retry_backoff_max
+        jitter = config.retry_backoff_jitter if jitter.nil?
+
+        exponent = [attempt - 1, 0].max
+        delay = base * (2**exponent)
+        delay = [delay, max].min
+
+        [apply_jitter(delay, jitter), max].min
+      end
+
+      private
+
+      def apply_jitter(delay, jitter)
+        return delay.to_i if jitter.nil? || jitter.zero?
+
+        spread = delay * jitter
+        jittered = delay + rand(-spread..spread)
+        [jittered.round, 0].max
+      end
+    end
+  end
+end

data/lib/pgbus/streams.rb

@@ -38,7 +38,7 @@ module Pgbus
       # Broadcasts a Turbo Stream HTML payload through the pgbus streamer.
       # PGMQ's `message` column is JSONB, so raw HTML strings can't be passed
       # directly. We wrap as `{"html": "..."}` on the way in and unwrap in
-      # Pgbus::Web::Streamer::Dispatcher before delivering to the SSE client.
+      # Pgbus::Web::Streamer::StreamEventDispatcher before delivering to the SSE client.
       # Callers pass a plain HTML string; the wrapping is an implementation
       # detail.
       #

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.6.1"
+  VERSION = "0.6.3"
 end

data/lib/pgbus/web/data_source.rb

@@ -875,28 +875,14 @@ module Pgbus
 
       # Extract uniqueness key from a JSON payload string and release its lock.
       def release_lock_for_payload(payload_str)
-        return unless payload_str
-
-        payload = payload_str.is_a?(String) ? JSON.parse(payload_str) : payload_str
-        key = payload[Uniqueness::METADATA_KEY]
+        key = extract_uniqueness_key_from_payload_str(payload_str)
         UniquenessKey.release!(key) if key
-      rescue JSON::ParserError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error parsing payload for lock release: #{e.message}" }
       end
 
       # Extract uniqueness keys from a collection of formatted messages and
       # release all associated locks in a single query.
       def release_locks_for_messages(messages)
-        keys = messages.filter_map do |m|
-          payload = m[:message]
-          next unless payload
-
-          parsed = payload.is_a?(String) ? JSON.parse(payload) : payload
-          parsed[Uniqueness::METADATA_KEY]
-        rescue JSON::ParserError
-          nil
-        end
-
+        keys = messages.filter_map { |m| extract_uniqueness_key_from_payload_str(m[:message]) }
         UniquenessKey.where(lock_key: keys).delete_all if keys.any?
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error releasing locks for messages: #{e.message}" }
@@ -908,18 +894,28 @@ module Pgbus
           "SELECT payload FROM pgbus_failed_events", "Pgbus Collect Failed Keys"
         )
 
-        keys = rows.to_a.filter_map do |row|
-          payload = JSON.parse(row["payload"])
-          payload[Uniqueness::METADATA_KEY]
-        rescue JSON::ParserError
-          nil
-        end
-
+        keys = rows.to_a.filter_map { |row| extract_uniqueness_key_from_payload_str(row["payload"]) }
         UniquenessKey.where(lock_key: keys).delete_all if keys.any?
       rescue StandardError => e
         Pgbus.logger.debug { "[Pgbus::Web] Error releasing locks for failed events: #{e.message}" }
       end
 
+      # Single unwrap point for PGMQ message / failed_event payload strings.
+      # Accepts a raw JSON string or an already-parsed Hash and returns the
+      # uniqueness metadata key, or nil when the payload is blank, unparseable,
+      # or carries no uniqueness metadata. Parse errors are swallowed at debug
+      # level because callers treat missing keys and malformed payloads
+      # identically (no lock to release).
+      def extract_uniqueness_key_from_payload_str(payload_str)
+        return nil unless payload_str
+
+        payload = payload_str.is_a?(String) ? JSON.parse(payload_str) : payload_str
+        payload[Uniqueness::METADATA_KEY]
+      rescue JSON::ParserError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error parsing payload for uniqueness key: #{e.message}" }
+        nil
+      end
+
       # Archive the queue message a failed_event row points to. Idempotent —
       # silently no-ops if the message no longer exists in the queue.
       def archive_failed_message(event)

data/lib/pgbus/web/metrics_serializer.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Web
+    # Converts DataSource output into Prometheus text exposition format
+    # (Content-Type: text/plain; version=0.0.4; charset=utf-8).
+    #
+    # Each metric family gets a HELP line, a TYPE line, and one or more
+    # sample lines. Labels are double-quoted per the Prometheus spec.
+    # All timing values are converted from milliseconds to seconds.
+    #
+    # Resilient by design: each section rescues StandardError independently
+    # so a failure in one data source method doesn't blank the entire
+    # scrape response.
+    class MetricsSerializer
+      def initialize(data_source)
+        @data_source = data_source
+      end
+
+      def serialize
+        lines = []
+        append_queue_metrics(lines)
+        append_job_metrics(lines)
+        append_process_metrics(lines)
+        append_summary_metrics(lines)
+        append_stream_metrics(lines)
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def append_queue_metrics(lines)
+        queues = @data_source.queues_with_metrics
+        return if queues.empty?
+
+        gauge(lines, "pgbus_queue_depth", "Number of messages in the queue (including invisible)") do
+          queues.map { |q| [q[:queue_length], { queue: q[:name] }] }
+        end
+
+        gauge(lines, "pgbus_queue_visible_depth", "Number of visible (ready to read) messages") do
+          queues.map { |q| [q[:queue_visible_length], { queue: q[:name] }] }
+        end
+
+        gauge(lines, "pgbus_queue_total_messages", "Total messages ever enqueued") do
+          queues.map { |q| [q[:total_messages], { queue: q[:name] }] }
+        end
+
+        gauge(lines, "pgbus_queue_oldest_message_age_seconds", "Age of the oldest message in seconds") do
+          queues.filter_map do |q|
+            next unless q[:oldest_msg_age_sec]
+
+            [q[:oldest_msg_age_sec], { queue: q[:name] }]
+          end
+        end
+
+        gauge(lines, "pgbus_queue_paused", "Whether the queue is paused (1) or active (0)") do
+          queues.map { |q| [q[:paused] ? 1 : 0, { queue: q[:name] }] }
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Metrics] Error serializing queue metrics: #{e.message}" }
+      end
+
+      def append_job_metrics(lines)
+        counts = @data_source.job_status_counts
+        unless counts.empty?
+          gauge(lines, "pgbus_jobs_total", "Number of jobs by status in the stats window") do
+            counts.map { |status, count| [count, { status: status }] }
+          end
+        end
+
+        summary = @data_source.job_stats_summary
+        if summary[:total].positive?
+          gauge(lines, "pgbus_job_duration_avg_seconds", "Average job duration in seconds") do
+            [[ms_to_s(summary[:avg_duration_ms])]]
+          end
+
+          gauge(lines, "pgbus_job_duration_max_seconds", "Maximum job duration in seconds") do
+            [[ms_to_s(summary[:max_duration_ms])]]
+          end
+        end
+
+        return unless Pgbus::JobStat.latency_columns? && summary[:avg_latency_ms]
+
+        gauge(lines, "pgbus_job_enqueue_latency_seconds", "Enqueue latency percentiles in seconds") do
+          [
+            [ms_to_s(summary[:p50_latency_ms]), { quantile: "0.5" }],
+            [ms_to_s(summary[:p95_latency_ms]), { quantile: "0.95" }],
+            [ms_to_s(summary[:p99_latency_ms]), { quantile: "0.99" }]
+          ]
+        end
+
+        gauge(lines, "pgbus_job_avg_retries", "Average retry count per job") do
+          [[summary[:avg_retries]]]
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Metrics] Error serializing job metrics: #{e.message}" }
+      end
+
+      def append_process_metrics(lines)
+        count = @data_source.processes.count
+        gauge(lines, "pgbus_active_processes", "Number of active pgbus worker processes") do
+          [[count]]
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Metrics] Error serializing process metrics: #{e.message}" }
+      end
+
+      def append_summary_metrics(lines)
+        stats = @data_source.summary_stats
+        gauge(lines, "pgbus_failed_events_total", "Total failed events") do
+          [[stats[:failed_count]]]
+        end
+
+        gauge(lines, "pgbus_dlq_depth", "Total messages across all dead letter queues") do
+          [[stats[:dlq_depth]]]
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Metrics] Error serializing summary metrics: #{e.message}" }
+      end
+
+      def append_stream_metrics(lines)
+        return unless @data_source.stream_stats_available?
+
+        summary = @data_source.stream_stats_summary
+        gauge(lines, "pgbus_stream_events_total", "Stream events by type in the stats window") do
+          [
+            [summary[:broadcasts], { event_type: "broadcast" }],
+            [summary[:connects], { event_type: "connect" }],
+            [summary[:disconnects], { event_type: "disconnect" }]
+          ]
+        end
+
+        gauge(lines, "pgbus_stream_active_connections", "Estimated active SSE connections") do
+          [[summary[:active_estimate]]]
+        end
+
+        gauge(lines, "pgbus_stream_avg_fanout", "Average broadcast fanout (subscribers per broadcast)") do
+          [[summary[:avg_fanout]]]
+        end
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Metrics] Error serializing stream metrics: #{e.message}" }
+      end
+
+      # Emits a Prometheus gauge metric family. The block must return an array
+      # of [value] or [value, { label: "val" }] pairs.
+      def gauge(lines, name, help)
+        samples = yield
+        return if samples.empty?
+
+        lines << "# HELP #{name} #{help}"
+        lines << "# TYPE #{name} gauge"
+        samples.each do |value, labels|
+          lines << format_sample(name, value, labels)
+        end
+      end
+
+      def format_sample(name, value, labels = nil)
+        if labels && !labels.empty?
+          label_str = labels.map { |k, v| "#{k}=\"#{v}\"" }.join(",")
+          "#{name}{#{label_str}} #{format_value(value)}"
+        else
+          "#{name} #{format_value(value)}"
+        end
+      end
+
+      def format_value(value)
+        value.is_a?(Float) ? value.to_s : value.to_i.to_s
+      end
+
+      def ms_to_s(milliseconds)
+        (milliseconds.to_f / 1000).round(4)
+      end
+    end
+  end
+end

data/lib/pgbus/web/streamer/heartbeat.rb

@@ -13,7 +13,7 @@ module Pgbus
       #      SSE clients.
       #
       #   2. Mark connections that have been idle longer than the
-      #      configured idle_timeout as dead. The Dispatcher's next pass
+      #      configured idle_timeout as dead. The StreamEventDispatcher's next pass
       #      picks them up via its disconnect path.
       #
       #   3. Post a DisconnectMessage for any connection already flagged
@@ -97,7 +97,7 @@ module Pgbus
         end
 
         def enqueue_disconnect(connection)
-          @queue << Dispatcher::DisconnectMessage.new(connection: connection)
+          @queue << StreamEventDispatcher::DisconnectMessage.new(connection: connection)
         end
       end
     end

data/lib/pgbus/web/streamer/instance.rb

@@ -43,7 +43,7 @@ module Pgbus
             health_check_ms: @config.streams_listen_health_check_ms,
             logger: @logger
           )
-          @dispatcher = Dispatcher.new(
+          @dispatcher = StreamEventDispatcher.new(
             client: @client,
             registry: @registry,
             listener: @listener,
@@ -92,7 +92,7 @@ module Pgbus
               return
             end
 
-            @dispatch_queue << Dispatcher::ConnectMessage.new(connection: connection)
+            @dispatch_queue << StreamEventDispatcher::ConnectMessage.new(connection: connection)
           end
         end
 

data/lib/pgbus/web/streamer/{dispatcher.rb → stream_event_dispatcher.rb}

@@ -26,8 +26,12 @@ module Pgbus
       #
       # All state ownership lives on this one thread: the registry is
       # thread-safe (Phase 2.1) but the in-flight buffers are local to
-      # the Dispatcher and accessed only from this thread, so no locks.
-      class Dispatcher
+      # the dispatcher and accessed only from this thread, so no locks.
+      #
+      # Named StreamEventDispatcher (rather than just "Dispatcher") to
+      # disambiguate from Pgbus::Process::Dispatcher, which is an
+      # unrelated worker-side pool coordinator. See issue #98 item 8.
+      class StreamEventDispatcher
         WakeMessage       = Listener::WakeMessage
         ConnectMessage    = Data.define(:connection)
         DisconnectMessage = Data.define(:connection)
@@ -110,7 +114,7 @@ module Pgbus
             # than calling Thread#kill, which leaves IO state corrupt.
             # The orphaned thread will exit on its own once the blocking
             # call returns and it sees @running == false on the next loop.
-            @logger.warn { "[Pgbus::Streamer::Dispatcher] thread did not terminate within 5s" }
+            @logger.warn { "[Pgbus::Streamer::StreamEventDispatcher] thread did not terminate within 5s" }
           end
           @thread = nil
           self
@@ -141,7 +145,7 @@ module Pgbus
             end
           end
         rescue StandardError => e
-          @logger.error { "[Pgbus::Streamer::Dispatcher] crashed: #{e.class}: #{e.message}" }
+          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] crashed: #{e.class}: #{e.message}" }
           raise
         end
 
@@ -176,7 +180,7 @@ module Pgbus
           when ConnectMessage    then handle_connect(msg)
           when DisconnectMessage then handle_disconnect(msg)
           else
-            @logger.warn { "[Pgbus::Streamer::Dispatcher] unknown message: #{msg.class}" }
+            @logger.warn { "[Pgbus::Streamer::StreamEventDispatcher] unknown message: #{msg.class}" }
           end
         rescue StandardError => e
           # Intentionally swallows per-message failures so one bad
@@ -184,7 +188,7 @@ module Pgbus
           # connected client. The top-level run_loop rescue (below)
           # does re-raise — a crash *between* messages is a real bug
           # and the supervisor should see it.
-          @logger.error { "[Pgbus::Streamer::Dispatcher] handling #{msg.class} raised #{e.class}: #{e.message}" }
+          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] handling #{msg.class} raised #{e.class}: #{e.message}" }
         end
 
         def handle_wake(msg)
@@ -310,7 +314,7 @@ module Pgbus
           @scanned_cursor.delete(connection)
           cleanup_stream_if_unused(stream)
           connection.mark_dead!
-          @logger.error { "[Pgbus::Streamer::Dispatcher] connect failed for #{connection.id}: #{e.class}: #{e.message}" }
+          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] connect failed for #{connection.id}: #{e.class}: #{e.message}" }
         end
 
         def handle_disconnect(msg)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -122,6 +122,7 @@ files:
 - README.md
 - Rakefile
 - app/controllers/pgbus/api/insights_controller.rb
+- app/controllers/pgbus/api/metrics_controller.rb
 - app/controllers/pgbus/api/stats_controller.rb
 - app/controllers/pgbus/application_controller.rb
 - app/controllers/pgbus/dashboard_controller.rb
@@ -283,6 +284,7 @@ files:
 - lib/pgbus/recurring/schedule.rb
 - lib/pgbus/recurring/scheduler.rb
 - lib/pgbus/recurring/task.rb
+- lib/pgbus/retry_backoff.rb
 - lib/pgbus/serializer.rb
 - lib/pgbus/stat_buffer.rb
 - lib/pgbus/streams.rb
@@ -297,15 +299,16 @@ files:
 - lib/pgbus/version.rb
 - lib/pgbus/web/authentication.rb
 - lib/pgbus/web/data_source.rb
+- lib/pgbus/web/metrics_serializer.rb
 - lib/pgbus/web/stream_app.rb
 - lib/pgbus/web/streamer.rb
 - lib/pgbus/web/streamer/connection.rb
-- lib/pgbus/web/streamer/dispatcher.rb
 - lib/pgbus/web/streamer/heartbeat.rb
 - lib/pgbus/web/streamer/instance.rb
 - lib/pgbus/web/streamer/io_writer.rb
 - lib/pgbus/web/streamer/listener.rb
 - lib/pgbus/web/streamer/registry.rb
+- lib/pgbus/web/streamer/stream_event_dispatcher.rb
 - lib/puma/plugin/pgbus_streams.rb
 - lib/tasks/pgbus_pgmq.rake
 - lib/tasks/pgbus_streams.rake