pgbus 0.9.7 → 0.9.9

data/lib/pgbus/dedup_cache.rb

@@ -60,11 +60,19 @@ module Pgbus
 
     def evict(key)
       @cache.delete(key)
+      # Concurrent::Array#delete is O(n), but this only runs on expiry and n is
+      # bounded by @max_size, so it stays cheap. Without it, @insertion_order
+      # leaks and stale duplicates can evict live keys in evict_oldest.
+      @insertion_order.delete(key)
     end
 
     def evict_oldest
       while @cache.size >= @max_size && !@insertion_order.empty?
         oldest_key = @insertion_order.shift
+        # Skip residual order entries for keys already gone from @cache so a
+        # stale duplicate never evicts a freshly re-marked (live) key.
+        next unless @cache.key?(oldest_key)
+
         @cache.delete(oldest_key)
       end
     end

data/lib/pgbus/doctor.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "uri"
+require "pgbus/mcp/health_analyzer"
+
+module Pgbus
+  # Preflight diagnostics for a pgbus deployment — the single command that
+  # answers "is this environment healthy enough to run?". Runs seven checks and
+  # returns a machine-readable result plus a human report, so `pgbus doctor`
+  # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
+  # 1 on any failure).
+  #
+  # Doctor never touches PGMQ or PostgreSQL directly: every probe goes through
+  # Pgbus::Client (DB, PGMQ schema, queues, NOTIFY) or Pgbus::Web::DataSource
+  # (process liveness, via Pgbus::MCP::HealthAnalyzer). It also never raises —
+  # a broken environment turns into :fail results, never a crash — so it is
+  # safe to run against a database that is down or a half-installed schema.
+  class Doctor
+    # A single check result. status is one of :ok, :warn, :fail.
+    Check = Struct.new(:name, :status, :detail) do
+      def to_h
+        { name: name, status: status, detail: detail }
+      end
+    end
+
+    STATUS_ICON = { ok: "✓", warn: "!", fail: "✗" }.freeze
+
+    def initialize(config: Pgbus.configuration, client: Pgbus.client, data_source: nil)
+      @config = config
+      @client = client
+      @data_source = data_source || Pgbus::Web::DataSource.new(client: client)
+    end
+
+    # Run all checks and return an array of result hashes:
+    #   { name:, status: :ok|:warn|:fail, detail: }
+    def run
+      @run ||= [
+        check_configuration,
+        check_database,
+        check_pgmq_schema,
+        check_queues,
+        check_notify,
+        check_processes,
+        check_allowed_global_id_models
+      ].map(&:to_h)
+    end
+
+    # True when no check failed. Warnings do not fail the run — they surface a
+    # concern (e.g. an outdated PGMQ schema) without blocking a deploy.
+    def success?
+      run.none? { |c| c[:status] == :fail }
+    end
+
+    # Human-readable report: one line per check, then a resolved-config summary
+    # with passwords redacted. Suitable for stdout in the CLI and rake task.
+    def report
+      lines = ["Pgbus Doctor", "=" * 40]
+      run.each do |check|
+        icon = STATUS_ICON.fetch(check[:status], "?")
+        lines << format("%<icon>s %<name>-22s %<detail>s", icon: icon, name: check[:name], detail: check[:detail])
+      end
+      lines << ""
+      lines << "Configuration"
+      lines << ("-" * 40)
+      config_summary.each { |key, value| lines << format("  %<key>-20s %<value>s", key: key, value: value) }
+      lines.join("\n")
+    end
+
+    # Resolved-config summary for the report. Password-bearing fields
+    # (database_url, connection_params) are redacted.
+    def config_summary
+      {
+        queue_prefix: @config.queue_prefix,
+        default_queue: @config.default_queue,
+        pgmq_schema_mode: @config.pgmq_schema_mode,
+        resolved_pool_size: safe { @config.resolved_pool_size },
+        listen_notify: @config.listen_notify,
+        roles: @config.roles || "all",
+        capsules: capsule_summary,
+        database_url: redacted_database_url,
+        connection_params: redacted_connection_params
+      }.compact
+    end
+
+    private
+
+    # True in a Rails production environment. Guarded so the doctor still runs
+    # outside Rails (plain Ruby, tests) without assuming Rails is loaded.
+    def production?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+    end
+
+    # 1. Configuration validity.
+    def check_configuration
+      @config.validate!
+      Check.new(name: "Configuration", status: :ok, detail: "valid")
+    rescue Pgbus::ConfigurationError, ArgumentError => e
+      Check.new(name: "Configuration", status: :fail, detail: e.message)
+    rescue StandardError => e
+      Check.new(name: "Configuration", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # 2. Database connectivity — SELECT 1 via Client#ping.
+    def check_database
+      @client.ping
+      Check.new(name: "Database", status: :ok, detail: "reachable")
+    rescue StandardError => e
+      Check.new(name: "Database", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # 3. PGMQ schema presence + installed-vs-vendored version.
+    #
+    # A nil version does NOT automatically mean "not installed": PGMQ installed
+    # via the extension, or before pgbus added version tracking, leaves the
+    # pgmq schema fully working with no row in pgbus_pgmq_schema_versions. So we
+    # distinguish, mirroring `pgbus:pgmq:status`: schema absent → fail; schema
+    # present but untracked → warn; tracked but behind → warn; current → ok.
+    def check_pgmq_schema
+      installed = @client.pgmq_schema_version
+      latest = Pgbus::PgmqSchema.latest_version
+
+      if installed.nil?
+        unless @client.pgmq_installed?
+          return Check.new(name: "PGMQ schema", status: :fail,
+                           detail: "not installed — run `rails generate pgbus:install`")
+        end
+
+        return Check.new(name: "PGMQ schema", status: :warn,
+                         detail: "installed but no version tracking — run `rails generate pgbus:upgrade_pgmq`")
+      end
+
+      if Gem::Version.new(installed) < Gem::Version.new(latest)
+        Check.new(name: "PGMQ schema", status: :warn,
+                  detail: "installed #{installed}, vendored #{latest} — run `rails generate pgbus:upgrade_pgmq`")
+      else
+        Check.new(name: "PGMQ schema", status: :ok, detail: "up to date (#{installed})")
+      end
+    rescue StandardError => e
+      Check.new(name: "PGMQ schema", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # 4. Queue existence — every configured queue must have its PGMQ table(s).
+    # Resolve each logical queue to the PHYSICAL names bootstrap creates (via the
+    # client's queue strategy) so a priority queue's _p0.._pN sub-tables are what
+    # we diff against list_queues — not the bare prefixed name priority mode
+    # never creates.
+    def check_queues
+      configured = @client.configured_queues.flat_map { |q| @client.physical_queue_names(q) }
+      existing = existing_queue_names
+      missing = configured - existing
+
+      if missing.empty?
+        Check.new(name: "Queues", status: :ok, detail: "#{configured.size} configured queue(s) present")
+      else
+        Check.new(name: "Queues", status: :fail, detail: "missing queue(s): #{missing.join(", ")}")
+      end
+    rescue StandardError => e
+      Check.new(name: "Queues", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # 5. LISTEN/NOTIFY — when configured on, every configured queue should carry
+    # the insert-NOTIFY trigger. A missing trigger is a warning, not a failure:
+    # pgbus still works (it falls back to polling), it just loses instant wakeup.
+    def check_notify
+      return Check.new(name: "LISTEN/NOTIFY", status: :ok, detail: "disabled in config") unless @config.listen_notify
+
+      without_trigger = @client.configured_queues.reject { |q| @client.notify_enabled?(q) }
+      if without_trigger.empty?
+        Check.new(name: "LISTEN/NOTIFY", status: :ok, detail: "triggers live on all configured queues")
+      else
+        Check.new(name: "LISTEN/NOTIFY", status: :warn,
+                  detail: "no insert trigger on: #{without_trigger.join(", ")} (falling back to polling)")
+      end
+    rescue StandardError => e
+      Check.new(name: "LISTEN/NOTIFY", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # 6. Process liveness — the top-level health verdict (OK/DEGRADED/STALLED)
+    # from the shared HealthAnalyzer. STALLED (the silent-worker-wedge) is a
+    # failure; DEGRADED is a warning; OK passes.
+    def check_processes
+      verdict = Pgbus::MCP::HealthAnalyzer.new(@data_source).verdict
+      status = verdict[:status]
+      detail = Array(verdict[:reasons]).first || status
+
+      case status
+      when "STALLED" then Check.new(name: "Process liveness", status: :fail, detail: detail)
+      when "DEGRADED" then Check.new(name: "Process liveness", status: :warn, detail: detail)
+      else Check.new(name: "Process liveness", status: :ok, detail: "OK")
+      end
+    rescue StandardError => e
+      Check.new(name: "Process liveness", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # 7. GlobalID allowlist — security. allowed_global_id_models = nil means
+    # "allow ANY model as a GlobalID event/job argument", which lets a crafted
+    # payload deserialize arbitrary AR models. It's the default for upgrade
+    # continuity, so this is a warning (never a failure), and only in production
+    # where the blast radius is real.
+    def check_allowed_global_id_models
+      if @config.allowed_global_id_models.nil? && production?
+        return Check.new(name: "GlobalID allowlist", status: :warn,
+                         detail: "allowed_global_id_models is nil (allow-all) in production — " \
+                                 "set an explicit allowlist of models permitted as GlobalID arguments")
+      end
+
+      Check.new(name: "GlobalID allowlist", status: :ok,
+                detail: @config.allowed_global_id_models.nil? ? "allow-all (non-production)" : "allowlist configured")
+    rescue StandardError => e
+      Check.new(name: "GlobalID allowlist", status: :fail, detail: "#{e.class}: #{e.message}")
+    end
+
+    # Physical queue names known to PGMQ. list_queues rows may be Hashes (with a
+    # :queue_name key) or value objects responding to #queue_name.
+    def existing_queue_names
+      Array(@client.list_queues).map do |row|
+        if row.respond_to?(:queue_name)
+          row.queue_name
+        elsif row.is_a?(Hash)
+          row[:queue_name] || row["queue_name"]
+        end
+      end.compact
+    end
+
+    def capsule_summary
+      Array(@config.workers).map { |w| w[:name] || (w[:queues] || []).join("+") }.join(", ")
+    end
+
+    # Redact the password from a libpq URL/URI while keeping host/db visible so
+    # the operator can still confirm which database they pointed at.
+    def redacted_database_url
+      return nil unless @config.database_url
+
+      redact_url(@config.database_url)
+    end
+
+    # connection_params is a free-form libpq keyword hash, so redact every key
+    # whose name looks secret (password, sslpassword, ...) — not just :password —
+    # rather than assuming a fixed shape. Preserves symbol/string key form.
+    SECRET_KEY_PATTERN = /pass|secret|token/i
+    private_constant :SECRET_KEY_PATTERN
+
+    def redacted_connection_params
+      params = @config.connection_params
+      return nil unless params.is_a?(Hash)
+
+      params.each_with_object({}) do |(key, value), out|
+        out[key] = key.to_s.match?(SECRET_KEY_PATTERN) ? "[REDACTED]" : value
+      end
+    end
+
+    # Replace the password in a userinfo authority (scheme://user:pass@host) or a
+    # key=value conninfo string (password=secret). Falls back to a blanket
+    # redaction label if parsing fails, never leaking the original.
+    #
+    # The userinfo password can itself contain '@' and ':' (common in generated
+    # secrets), so match it greedily up to the LAST '@' before the authority's
+    # host — a lazy `[^@]+` would stop at the first '@' and leak the remainder.
+    def redact_url(url)
+      redacted = url.sub(%r{(://[^:/@]+:).+(@[^@/]*(?:[/?]|\z))}, '\1[REDACTED]\2')
+      redacted.gsub(/(\bpassword=)('[^']*'|[^\s'"]+)/i, '\1[REDACTED]')
+    rescue StandardError
+      "[REDACTED]"
+    end
+
+    # Wrap a value-producing block so a broken resolver (e.g. resolved_pool_size
+    # raising on a malformed worker config) degrades to nil instead of raising
+    # out of config_summary.
+    def safe
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/pgbus/engine.rb

@@ -60,6 +60,7 @@ module Pgbus
       load File.expand_path("../tasks/pgbus_pgmq.rake", __dir__)
       load File.expand_path("../tasks/pgbus_streams.rake", __dir__)
       load File.expand_path("../tasks/pgbus_autovacuum.rake", __dir__)
+      load File.expand_path("../tasks/pgbus_doctor.rake", __dir__)
     end
 
     initializer "pgbus.i18n" do
@@ -86,6 +87,20 @@ module Pgbus
       end
     end
 
+    # Generic metrics adapter. Opt-in via config.metrics_backend; nil (default)
+    # installs no subscription, so there is zero overhead when unused. Runs
+    # independently of AppSignal — both consume the same pgbus.* events and both
+    # can be active at once.
+    initializer "pgbus.metrics", after: :load_config_initializers do
+      ActiveSupport.on_load(:after_initialize) do
+        next if Pgbus.configuration.metrics_backend.nil?
+
+        backend = Pgbus::Metrics.resolve_backend(Pgbus.configuration.metrics_backend)
+        Pgbus::Metrics::Subscriber.install!(backend: backend)
+        Pgbus.logger.info { "[Pgbus] Metrics subscriber installed (#{backend.class})" }
+      end
+    end
+
     # Install the watermark cache middleware ahead of the app's own
     # middleware so the thread-local cache is cleared between every
     # Rack request. Without this, repeated page renders served by the

data/lib/pgbus/execution_pools/async_pool.rb

@@ -25,7 +25,7 @@ module Pgbus
 
       def post(&block)
         raise_if_fatal!
-        raise "Execution pool is shutting down" if shutdown?
+        raise Pgbus::ExecutionPoolError, "Execution pool is shutting down" if shutdown?
 
         reserved = false
         reserve_capacity!
@@ -46,6 +46,13 @@ module Pgbus
         available_capacity.positive?
       end
 
+      # True only when every slot is free — all in-flight work has finished.
+      # idle? answers "can this pool accept work?"; quiesced? answers
+      # "has this pool drained?". The worker drain loop needs the latter.
+      def quiesced?
+        available_capacity >= @capacity
+      end
+
       def shutdown
         @state_mutex.synchronize do
           return false if @shutdown_flag
@@ -186,7 +193,7 @@ module Pgbus
 
       def reserve_capacity!
         @mutex.synchronize do
-          raise "Execution pool is at capacity" if @available_capacity <= 0
+          raise Pgbus::ExecutionPoolError, "Execution pool is at capacity" if @available_capacity <= 0
 
           @available_capacity -= 1
         end

data/lib/pgbus/execution_pools/thread_pool.rb

@@ -37,6 +37,13 @@ module Pgbus
         available_capacity.positive?
       end
 
+      # True only when every slot is free — all in-flight work has finished.
+      # idle? answers "can this pool accept work?"; quiesced? answers
+      # "has this pool drained?". The worker drain loop needs the latter.
+      def quiesced?
+        available_capacity >= @capacity
+      end
+
       def shutdown
         @pool.shutdown
       end

data/lib/pgbus/generators/config_converter.rb

@@ -11,7 +11,9 @@ module Pgbus
     #
     # Drops settings that:
     #   - match the gem default (no point restating it)
-    #   - are deprecated (e.g. pool_size, which is now auto-tuned)
+    #   - are deprecated (settings that no longer exist in the public API —
+    #     see DEPRECATED_SETTINGS; pool_size is NOT one of these, it's a
+    #     live accessor that overrides auto-tuning and is preserved)
     #
     # Converts seconds to durations when they evenly divide into a clean
     # unit (7 days, 30 days, 10 minutes). Falls back to the raw integer
@@ -28,7 +30,7 @@ module Pgbus
     # generator's CLI wrapper writes the new initializer and tells the
     # user to delete the YAML when ready.
     class ConfigConverter
-      class Error < StandardError; end
+      class Error < Pgbus::Error; end
 
       # Setters that accept ActiveSupport::Duration (PR 5).
       DURATION_SETTINGS = %w[
@@ -38,15 +40,15 @@ module Pgbus
 
       # Settings that no longer exist in the public API. The converter
       # silently drops these from the generated initializer so users on
-      # legacy YAML get a clean migration.
+      # legacy YAML get a clean migration. NOTE: pool_size is intentionally
+      # NOT here — it's a live Configuration#pool_size accessor users set to
+      # override auto-tuning, so it must survive the conversion unchanged.
       #
-      #   - pool_size              -> auto-tuned from worker thread counts
       #   - notify_throttle_ms     -> Pgbus::Client::NOTIFY_THROTTLE_MS
       #   - circuit_breaker_*      -> Pgbus::CircuitBreaker constants
       #   - archive_compaction_*   -> Pgbus::Process::Dispatcher constants
       #   - dead_letter_queue_suffix -> Pgbus::DEAD_LETTER_SUFFIX (frozen)
       DEPRECATED_SETTINGS = %w[
-        pool_size
         notify_throttle_ms
         circuit_breaker_threshold circuit_breaker_base_backoff circuit_breaker_max_backoff
         archive_compaction_interval archive_compaction_batch_size

data/lib/pgbus/generators/migration_detector.rb

@@ -35,9 +35,10 @@ module Pgbus
     #
     # 5. Indexes missing on existing tables → queued. Additive, safe.
     #
-    # 6. Modern replacements for legacy tables (e.g. pgbus_job_locks →
-    #    pgbus_uniqueness_keys) → queue the migration path only if the
-    #    legacy table still exists. Otherwise queue the fresh install.
+    # 6. Modern uniqueness table (pgbus_uniqueness_keys) missing → queue
+    #    add_uniqueness_keys unconditionally. A legacy pgbus_job_locks
+    #    table left over from an older install is not dropped by this
+    #    detector — run `pgbus:migrate_job_locks` by hand to retire it.
     class MigrationDetector
       # Sentinel returned when the database looks empty of pgbus tables.
       # The caller (pgbus:update generator) should redirect the user to
@@ -58,13 +59,14 @@ module Pgbus
 
       # generator_key → Rails generator name. Passed to Thor's invoke.
       #
-      # Note: uniqueness_keys uses the migrate_job_locks generator for
-      # both the fresh-install and upgrade-from-job_locks paths. The
-      # template is idempotent: `unless table_exists?(:pgbus_uniqueness_keys)`
-      # creates it, and `if table_exists?(:pgbus_job_locks)` drops the
-      # legacy table. One generator covers both cases.
+      # Note: uniqueness_keys invokes add_uniqueness_keys, which only
+      # creates the modern pgbus_uniqueness_keys table. If the legacy
+      # pgbus_job_locks table is also present (an install mid-migration),
+      # run `pgbus:migrate_job_locks` separately to drop it — that
+      # generator is not part of this detector's default flow since it
+      # requires the legacy table to already exist.
       GENERATOR_MAP = {
-        uniqueness_keys: "pgbus:migrate_job_locks",
+        uniqueness_keys: "pgbus:add_uniqueness_keys",
         add_job_stats: "pgbus:add_job_stats",
         add_job_stats_latency: "pgbus:add_job_stats_latency",
         add_job_stats_queue_index: "pgbus:add_job_stats_queue_index",
@@ -81,7 +83,7 @@ module Pgbus
       # Human-friendly description of each migration for the generator
       # output. Keeps the update generator's run log readable.
       DESCRIPTIONS = {
-        uniqueness_keys: "uniqueness keys table (job deduplication, also upgrades legacy job_locks if present)",
+        uniqueness_keys: "uniqueness keys table (job deduplication)",
         add_job_stats: "job stats table (Insights dashboard)",
         add_job_stats_latency: "job stats latency columns (enqueue_latency_ms, retry_count)",
         add_job_stats_queue_index: "job stats (queue_name, created_at) index",
@@ -128,10 +130,9 @@ module Pgbus
         CORE_INSTALL_TABLES.none? { |t| table_exists?(t) }
       end
 
-      # Legacy pgbus_job_locks → modern pgbus_uniqueness_keys.
-      # The migrate_job_locks template is idempotent: it creates
-      # uniqueness_keys if missing and drops job_locks if present.
-      # One symbol covers both cases; see GENERATOR_MAP.
+      # Queue add_uniqueness_keys whenever the modern table is missing.
+      # This does not touch a legacy pgbus_job_locks table — that is
+      # handled separately by `pgbus:migrate_job_locks`, see GENERATOR_MAP.
       def uniqueness_key_migrations
         return [] if table_exists?("pgbus_uniqueness_keys")
 
@@ -180,8 +181,11 @@ module Pgbus
       def recurring_migrations
         # pgbus_recurring_tasks + pgbus_recurring_executions are the two
         # tables the recurring generator creates. If BOTH exist, nothing
-        # to do. If either is missing, we need the generator (which is
-        # idempotent via if_not_exists on both tables).
+        # to do. If either is missing, we queue the generator. The
+        # add_recurring template uses plain create_table (no if_not_exists),
+        # so idempotency is provided by this detector, not the template:
+        # the migration is only queued while a table is absent, and never
+        # re-invoked once both tables are present.
         return [] if table_exists?("pgbus_recurring_tasks") && table_exists?("pgbus_recurring_executions")
 
         [:add_recurring]

data/lib/pgbus/instrumentation.rb

@@ -11,6 +11,7 @@ module Pgbus
   #   pgbus.client.send_batch      — batch enqueue
   #   pgbus.client.read_batch      — batch dequeue
   #   pgbus.client.read_message    — single message dequeue
+  #   pgbus.client.pool            — connection pool snapshot (size/available/pool_timeout); emitted per worker heartbeat
   #   pgbus.executor.execute       — full job execution (deserialize + perform + archive)
   #   pgbus.job_completed          — job archived successfully
   #   pgbus.job_failed             — job raised; carries :exception_object
@@ -20,7 +21,8 @@ module Pgbus
   #   pgbus.stream.broadcast       — stream broadcast (sync or deferred)
   #   pgbus.outbox.publish         — outbox row created
   #   pgbus.recurring.enqueue      — scheduler enqueued a due recurring task
-  #   pgbus.worker.recycle         — worker hit a recycle threshold
+  #   pgbus.worker.recycle         — worker hit a recycle threshold (reason/jobs_processed/memory_mb/lifetime_seconds)
+  #   pgbus.consumer.recycle       — consumer hit a recycle threshold (same payload shape as pgbus.worker.recycle)
   #   pgbus.serializer.serialize   — job/event serialization
   #   pgbus.serializer.deserialize — job/event deserialization
   #

data/lib/pgbus/integrations/appsignal/probe.rb

@@ -51,8 +51,9 @@ module Pgbus
 
         # The actual probe object; AppSignal calls #call once per minute.
         class Runner
-          def initialize(data_source: nil)
+          def initialize(data_source: nil, client: nil)
             @data_source = data_source
+            @client = client
             @hostname = Socket.gethostname
           end
 
@@ -63,6 +64,7 @@ module Pgbus
             track_processes
             track_summary
             track_streams
+            track_pool
           end
 
           private
@@ -72,6 +74,10 @@ module Pgbus
               (::Pgbus::Web::DataSource.new if defined?(::Pgbus::Web::DataSource))
           end
 
+          def client
+            @client ||= (::Pgbus.client if defined?(::Pgbus) && ::Pgbus.respond_to?(:client))
+          end
+
           def track_queues
             data_source.queues_with_metrics.each do |q|
               tags = { queue: q[:name] }
@@ -110,6 +116,22 @@ module Pgbus
             log_failure("summary metrics", e)
           end
 
+          # The PGMQ connection pool is per-process (each host owns its own
+          # pool), so — unlike the cluster-wide queue/summary gauges — these
+          # are tagged with the hostname, same policy as active_processes.
+          # pool_stats already rescues to {} internally; the outer rescue here
+          # keeps a probe iteration alive if the client itself is unavailable.
+          def track_pool
+            stats = client&.pool_stats || {}
+            return if stats.empty?
+
+            tags = { hostname: @hostname }
+            gauge "pool_size", stats[:size], tags
+            gauge "pool_available", stats[:available], tags
+          rescue StandardError => e
+            log_failure("pool metrics", e)
+          end
+
           def track_streams
             return unless data_source.respond_to?(:stream_stats_available?) &&
                           data_source.stream_stats_available?

data/lib/pgbus/integrations/appsignal/subscriber.rb

@@ -41,7 +41,13 @@ module Pgbus
               subscribe("pgbus.stream.broadcast") { |event| on_stream_broadcast(event) },
               subscribe("pgbus.outbox.publish") { |event| on_outbox_publish(event) },
               subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
-              subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) }
+              subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) },
+              subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) }
+              # pgbus.client.pool is deliberately NOT subscribed here — the
+              # minutely Probe#track_pool already reports pgbus_pool_size /
+              # pgbus_pool_available gauges for AppSignal (see probe.rb).
+              # Subscribing here too would double-report on every heartbeat
+              # and skew the gauges.
             ]
             @installed = true
           end
@@ -250,7 +256,16 @@ module Pgbus
             ::Appsignal.increment_counter(
               "#{METRIC_PREFIX}worker_recycled",
               1,
-              { reason: payload[:reason] }
+              { reason: payload[:reason], kind: "worker" }
+            )
+          end
+
+          def on_consumer_recycle(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}worker_recycled",
+              1,
+              { reason: payload[:reason], kind: "consumer" }
             )
           end
 

data/lib/pgbus/metrics/backend.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Metrics
+    # Interface every metrics backend implements. The Subscriber only ever calls
+    # these three methods, so a backend that satisfies them plugs in directly as
+    # `config.metrics_backend`.
+    #
+    #   increment(name, value = 1, tags = {}) — monotonic counter add
+    #   gauge(name, value, tags = {})         — point-in-time value
+    #   histogram(name, value, tags = {})     — timing/size distribution sample
+    #
+    # `name` is a `pgbus_`-prefixed String; `tags` is a Hash of low-cardinality
+    # label => value pairs (no msg_id, no event_id).
+    class Backend
+      def increment(_name, _value = 1, _tags = {})
+        raise NotImplementedError, "#{self.class}#increment"
+      end
+
+      def gauge(_name, _value, _tags = {})
+        raise NotImplementedError, "#{self.class}#gauge"
+      end
+
+      def histogram(_name, _value, _tags = {})
+        raise NotImplementedError, "#{self.class}#histogram"
+      end
+
+      # No-op backend. Used as the resolved backend for a nil configuration so
+      # callers never have to nil-check, though in practice the Subscriber is
+      # simply not installed when metrics_backend is nil.
+      class Null < Backend
+        def increment(_name, _value = 1, _tags = {}) = nil
+        def gauge(_name, _value, _tags = {}) = nil
+        def histogram(_name, _value, _tags = {}) = nil
+      end
+    end
+  end
+end