pgbus 0.9.7 → 0.9.8

data/lib/pgbus/config_loader.rb

@@ -11,16 +11,35 @@ module Pgbus
       env ||= (defined?(Rails) && Rails.respond_to?(:env) && Rails.env) || ENV.fetch("PGBUS_ENV", "development")
       raw = File.read(path)
       parsed = YAML.safe_load(ERB.new(raw).result, permitted_classes: [Symbol], aliases: true)
-      config_hash = parsed.fetch(env, parsed)
-      apply(config_hash)
+      # Distinguish sectioned (top-level env keys mapping to Hashes) from
+      # flat (top-level setter keys mapping to scalars/arrays). parsed.key?(env)
+      # alone can't tell them apart, so a flat file silently lost its typo
+      # warnings whenever no env section happened to match its keys.
+      if sectioned?(parsed)
+        apply(parsed.fetch(env)) if parsed.key?(env)
+      else
+        apply(parsed)
+      end
+    end
+
+    def sectioned?(parsed)
+      parsed.is_a?(Hash) && parsed.any? && parsed.values.all?(Hash)
     end
 
-    def apply(hash)
+    def apply(hash, warn_unknown: true)
       config = Pgbus.configuration
       hash.each do |key, value|
         setter = :"#{key}="
-        config.public_send(setter, value) if config.respond_to?(setter)
+        if config.respond_to?(setter)
+          config.public_send(setter, value)
+        elsif warn_unknown
+          config.logger.warn { "[Pgbus] Unknown configuration key ignored: #{key.inspect} — check for typos in pgbus.yml" }
+        end
       end
+      # Validate eagerly so a bad YAML value aborts boot with an ArgumentError
+      # naming the offending key, instead of failing later in a worker path.
+      # Honors an `eager_validation: false` key in the same hash (applied above).
+      config.validate! if config.eager_validation
       config
     end
   end

data/lib/pgbus/configuration.rb

@@ -86,7 +86,7 @@ module Pgbus
     attr_reader :pgmq_schema_mode
 
     # Event consumers
-    attr_accessor :event_consumers
+    attr_reader :event_consumers
 
     # Recurring jobs
     attr_accessor :recurring_tasks, :recurring_schedule_interval, :recurring_tasks_file, :skip_recurring
@@ -103,7 +103,7 @@ module Pgbus
     attr_accessor :zombie_detection
 
     # Job stats
-    attr_accessor :stats_enabled
+    attr_accessor :stats_enabled, :stats_flush_size, :stats_flush_interval
     attr_reader :stats_retention # rubocop:disable Style/AccessorGrouping
 
     # Web dashboard
@@ -112,6 +112,13 @@ module Pgbus
                   :metrics_enabled,
                   :dashboard_filter_parameters, :dashboard_filter_sensitive
 
+    # HTTP health endpoints (liveness/readiness for orchestrators like
+    # Kubernetes). `health_port` nil (default) leaves the standalone server in
+    # the supervisor disabled — mount Pgbus::Web::HealthApp in the host Rails
+    # app instead. When set, Supervisor#run serves /livez and /readyz over a
+    # plain TCPServer bound to `health_bind` (default localhost).
+    attr_accessor :health_port, :health_bind
+
     # Streams (turbo-rails replacement, SSE-based)
     attr_accessor :streams_enabled, :streams_path, :streams_queue_prefix, :streams_signed_name_secret,
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
@@ -136,6 +143,21 @@ module Pgbus
     # Set to false to opt out without uninstalling the appsignal gem.
     attr_accessor :appsignal_enabled, :appsignal_probe_enabled
 
+    # Generic metrics adapter (Pgbus::Metrics). Consumes the same pgbus.*
+    # instrumentation events as AppSignal and forwards them to a backend:
+    #   nil (default) — install nothing, zero overhead
+    #   :prometheus   — in-process registry, scraped via PrometheusExporter
+    #   :statsd       — UDP datagrams to statsd_host:statsd_port
+    #   a Pgbus::Metrics::Backend instance — a custom backend
+    attr_accessor :metrics_backend, :statsd_host, :statsd_port
+
+    # When true (default), Pgbus.configure and ConfigLoader.apply run
+    # validate! after applying settings, so an invalid value fails loud at
+    # boot instead of dormant until a worker path consumes it. Set false to
+    # opt out (exotic setups that intentionally hold a transiently-invalid
+    # config); explicit validate! still works.
+    attr_accessor :eager_validation
+
     def initialize
       @database_url = nil
       @connection_params = nil
@@ -209,6 +231,11 @@ module Pgbus
 
       @stats_enabled = true
       @stats_retention = 30 * 24 * 3600 # 30 days
+      # StatBuffer flush thresholds. Buffered stats are lost on SIGKILL, so a
+      # smaller size/interval shrinks the residual loss window at the cost of
+      # more frequent bulk inserts. Defaults mirror StatBuffer's own constants.
+      @stats_flush_size = StatBuffer::DEFAULT_FLUSH_SIZE
+      @stats_flush_interval = StatBuffer::DEFAULT_FLUSH_INTERVAL
 
       @connects_to = nil
 
@@ -224,6 +251,10 @@ module Pgbus
       @dashboard_filter_parameters = nil # nil = auto-detect from Rails, then fall back to defaults
       @dashboard_filter_sensitive = true
 
+      # HTTP health endpoints — nil port disables the standalone server.
+      @health_port = nil
+      @health_bind = "127.0.0.1"
+
       @streams_enabled = true
       @streams_path = nil
       @streams_queue_prefix = "pgbus_stream"
@@ -287,6 +318,13 @@ module Pgbus
       # the same process, so the operator can disable it independently.
       @appsignal_enabled = true
       @appsignal_probe_enabled = true
+
+      # Generic metrics adapter: off by default (no subscription installed).
+      @metrics_backend = nil
+      @statsd_host = "127.0.0.1"
+      @statsd_port = 8125
+
+      @eager_validation = true
     end
 
     def queue_name(name)
@@ -311,7 +349,7 @@ module Pgbus
     # Returns the execution mode for a specific worker config hash,
     # falling back to the global execution_mode setting.
     def execution_mode_for(worker_config)
-      mode = worker_config[:execution_mode] || worker_config["execution_mode"] || execution_mode
+      mode = worker_config[:execution_mode] || execution_mode
       ExecutionPools.normalize_mode(mode)
     end
 
@@ -393,15 +431,26 @@ module Pgbus
         raise ArgumentError, "read_timeout must be a positive number or nil to disable"
       end
 
+      unless stats_flush_size.is_a?(Integer) && stats_flush_size.positive?
+        raise ArgumentError, "stats_flush_size must be a positive integer"
+      end
+      unless stats_flush_interval.is_a?(Numeric) && stats_flush_interval.positive?
+        raise ArgumentError, "stats_flush_interval must be a positive number"
+      end
+
+      unless health_port.nil? || (health_port.is_a?(Integer) && health_port.between?(1, 65_535))
+        raise ArgumentError, "health_port must be an integer between 1 and 65535 or nil to disable"
+      end
+
       # Validate global execution_mode
       ExecutionPools.normalize_mode(execution_mode)
 
       Array(workers).each do |w|
-        threads = w[:threads] || w["threads"] || 5
+        threads = w[:threads] || 5
         raise ArgumentError, "worker threads must be > 0" unless threads.is_a?(Integer) && threads.positive?
 
         # Validate per-worker execution_mode override if present
-        mode = w[:execution_mode] || w["execution_mode"]
+        mode = w[:execution_mode]
         ExecutionPools.normalize_mode(mode) if mode
       end
 
@@ -416,6 +465,7 @@ module Pgbus
       end
 
       validate_streams!
+      validate_metrics_backend!
 
       self
     end
@@ -465,6 +515,17 @@ module Pgbus
       raise ArgumentError, "streams_orphan_threshold must be a positive number or nil to disable"
     end
 
+    def validate_metrics_backend!
+      value = metrics_backend
+      return if value.nil?
+      return if %i[prometheus statsd].include?(value)
+      return if defined?(Pgbus::Metrics::Backend) && value.is_a?(Pgbus::Metrics::Backend)
+
+      raise ArgumentError,
+            "metrics_backend must be nil, :prometheus, :statsd, or a " \
+            "Pgbus::Metrics::Backend instance (got #{value.inspect})"
+    end
+
     # Returns true if the given stream name should be durable based on
     # `streams_durable_patterns` (exact string or Regexp match) or the
     # `streams_default_broadcast_mode` fallback.
@@ -552,13 +613,29 @@ module Pgbus
                    parsed = CapsuleDSL.parse(value)
                    assign_auto_names(parsed)
                  when Array
-                   value
+                   value.map { |entry| normalize_entry(entry, group: "worker") }
                  else
                    raise ArgumentError,
                          "workers must be a String (DSL), Array (legacy form), or nil — got #{value.class}"
                  end
     end
 
+    # Event consumer configs arrive with symbol keys (Ruby DSL) or string keys
+    # (YAML via ConfigLoader). Normalize once here so every read site uses
+    # symbol access only. nil passes through (no consumers configured).
+    def event_consumers=(value)
+      @event_consumers =
+        case value
+        when nil
+          nil
+        when Array
+          value.map { |entry| normalize_entry(entry, group: "event_consumer") }
+        else
+          raise ArgumentError,
+                "event_consumers must be an Array or nil — got #{value.class}"
+        end
+    end
+
     # Define a named capsule and append it to the workers list.
     #
     #   c.capsule :critical, queues: %w[critical], threads: 5
@@ -850,11 +927,20 @@ module Pgbus
       numeric
     end
 
-    # Read a capsule's name from either symbol or string key, normalized
-    # to a string for comparison. Returns nil for unnamed (legacy) entries.
+    # Symbolize the top-level keys of a worker/consumer config entry so every
+    # downstream read site can use symbol access only. YAML (via ConfigLoader)
+    # yields string keys; the Ruby DSL and +capsule+ builder yield symbols.
+    # Entries are flat hashes with array/scalar values — no deep recursion.
+    def normalize_entry(entry, group:)
+      raise ArgumentError, "#{group} entry must be a Hash, got #{entry.class}: #{entry.inspect}" unless entry.is_a?(Hash)
+
+      entry.transform_keys(&:to_sym)
+    end
+
+    # Read a capsule's name (symbol key after normalization), as a string for
+    # comparison. Returns nil for unnamed (legacy) entries.
     def capsule_name(entry)
-      raw = entry[:name] || entry["name"]
-      raw&.to_s
+      entry[:name]&.to_s
     end
 
     # Auto-assign :name to parsed capsules where the first queue token would
@@ -887,7 +973,7 @@ module Pgbus
       existing_named = (@workers || []).select { |c| capsule_name(c) }
       return if existing_named.empty?
 
-      existing_queues = existing_named.flat_map { |c| c[:queues] || c["queues"] || [] }
+      existing_queues = existing_named.flat_map { |c| c[:queues] || [] }
       return if existing_queues.empty?
 
       if existing_queues.include?(CapsuleDSL::WILDCARD)
@@ -915,7 +1001,7 @@ module Pgbus
       return 0 unless entries
 
       entries.sum do |entry|
-        threads = entry[:threads] || entry["threads"] || default_threads
+        threads = entry[:threads] || default_threads
         unless threads.is_a?(Integer) && threads.positive?
           raise ArgumentError,
                 "#{group} threads must be a positive integer, got #{threads.inspect}"

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,250 @@
+# 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 six 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
+      ].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
+
+    # 1. Configuration validity.
+    def check_configuration
+      @config.validate!
+      Check.new(name: "Configuration", status: :ok, detail: "valid")
+    rescue 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
+
+    # 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

@@ -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

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/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

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?