pgbus 0.11.1 → 0.11.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a52dc949281b6f2f1e9c847d38709fcc2723badd12370486faeb68b40ed55c42
-  data.tar.gz: 70a75a14bfe2225f63846314cbb60c0942e86b966c14b20e43eec74afc63adef
+  metadata.gz: df6f1cbda597599aaad006242fbb0b964edaa8fa599c413dfde949fc3b7e19a2
+  data.tar.gz: 4a57b939f12238bf4aac8fc601ee5cd529fd1311e6c6994dacfb55f925545e4b
 SHA512:
-  metadata.gz: dc59f389bf2b5e20b2e75a7a2c47301c242ea0b5857a240e5a59db3177effe34cbe694903d4396b07ef3ca67699f578a5d6b6d95f61d4318169ac477f237b526
-  data.tar.gz: a5a6a076c6cadb857c8690ef7d1363934c7f73bd76e8d91a87a936a91d05c4146c12bb67b5637204995d0ddef540833a8983ca4dd3d5ef1034a7b88473aa1e61
+  metadata.gz: 336b503f39a11252b461b98c124617d16f252a20e8ef343ea48d637d8552a6048ff8c0d9465d95fcb7c737616010da63669a8db3eacb9971d79b6ae9286ed432
+  data.tar.gz: 33d5b40c21ef5213f4014f27577e19c617ee0e71420dc3c3432c4e3d35f941cafbe0e6a41d33bac42cc9ec2eb65a159d3685f1cce28ff44e97a14ca9749134ab

data/CHANGELOG.md

@@ -10,6 +10,8 @@
 
 ### Added
 
+- **`pgbus dashboard` — print the vendored AppSignal dashboards as import-ready JSON.** The gem ships four AppSignal dashboard definitions (the main one submitted to appsignal/public_config#80 plus the health/streams/throughput extras), but they're stored in the automated-dashboard format — a `metric_keys` trigger wrapping the `dashboard` object — which AppSignal's "Import dashboard" dialog doesn't accept, so trying one on a real app meant hand-unwrapping JSON. `pgbus dashboard [main|health|streams|throughput]` prints the inner dashboard object ready to paste into the import dialog (`pgbus dashboard health | pbcopy`); `pgbus dashboard --list` enumerates the available names and titles.
+- **`config.doctor_on_boot` (+ `pgbus start --doctor` / `--doctor-strict`) — run the doctor preflight inside the booting supervisor, one Rails boot instead of two (issue #347).** The recommended deploy preflight was `bin/pgbus doctor || true` in the container entrypoint before `bin/pgbus start` — but both commands `require config/environment`, so the job container boots the full Rails app **twice** on every deploy (cost scaling with app boot time), and running doctor pre-supervisor makes the `Process liveness` check false-fail (no workers exist yet), which is exactly why the entrypoint has to swallow the exit code with `|| true` — losing any chance to gate on a genuinely-fatal finding. Now `config.doctor_on_boot = :report` (or `pgbus start --doctor`) runs the checks in the already-booted supervisor, after the DB is verified reachable and queues are bootstrapped but **before any worker is forked**: one boot, and the worker-dependent `Process liveness` check is skipped (it has no workers to observe yet and would false-fail on stale prior-generation rows during a redeploy). `config.doctor_on_boot = :strict` (or `--doctor-strict`) additionally **refuses to boot** — raising before forking anything, so the `ensure shutdown` path tears down the heartbeat/health server and no child starts — but *only* on a genuinely-fatal, non-transient check: a `Configuration` failure (a real config bug) or an **absent** PGMQ schema. It deliberately does **not** abort on `Queues`/`Database` failures — those are the transients the lenient queue bootstrap is built to ride out (children crash-and-backoff until the DB recovers), and `verify_connection!` already gated a hard-down DB moments earlier; making them strict-fatal would take down a whole fleet's cold boot in lockstep on a momentarily-saturated primary. Default `nil`/`false` = off (byte-identical to today; the supervisor constructs no `Doctor` and does zero extra work). The standalone `pgbus doctor` command and its exit-code semantics are unchanged. Refs #347.
 - **`Pgbus::Streams::PhlexHelpers` — a Phlex-includable `pgbus_stream_from`, and `Pgbus.stream_name_budget` (issue #334).** Two small helpers that stop consuming apps reimplementing pgbus glue. (1) `pgbus_stream_from` is a Rails view helper, so a Phlex component couldn't call it without hand-registering an output-helper macro (phlex-rails ships no `Phlex::Rails::Helpers::PgbusStreamFrom`). `include Pgbus::Streams::PhlexHelpers` now bridges it exactly like phlex-rails' own `TurboStreamFrom`. phlex-rails stays an **optional** dependency — the module references its `HelperMacros` and is loaded on demand (`require "pgbus/streams/phlex_helpers"`), never eagerly. (2) `Pgbus.stream_name_budget` exposes the maximum stream-name length (the pgmq queue-name cap minus the queue prefix) so apps size/truncate stream identifiers up front instead of hand-computing `MAX_QUEUE_NAME_LENGTH - queue_prefix.length - 1` at every call site. Refs #334.
 - **`EventBus::Registry#setup_all!(safe: true)` — a boot/rake-safe way to eagerly set up event subscribers (issue #334).** Calling `setup_all!` opens a PGMQ connection per subscriber (to create its queue + bind its topic), which is wrong during a `db:`/schema rake task (a live connection blocks `DROP DATABASE`) and crashes boot if the database isn't up yet — so apps wrapped it in a hand-rolled multi-class rescue plus a rake-task skip. `setup_all!(safe: true)` bakes that in: it skips entirely in a schema/asset rake context and swallows a connection error with a warning instead of raising. The default `setup_all!` is unchanged (raises). Refs #334.
 - **Connection-pooler safety (`config.require_primary`, `config.connection_guc_mode`) — pgbus is now correct-and-loud behind a transaction/read-write-splitting pooler instead of silently stalling (issue #332).** Three linked fixes. (1) **Primary affinity:** a read/write-splitting pooler (pgdog/pgcat) can route pgmq's VOLATILE `read`/`archive`/`delete` to a read replica, where workers read nothing (`read_ct=0`) and jobs stop with a **healthy heartbeat** — the supervisor watchdog keys on loop advancement, not read progress, so nothing surfaced the stall. The job read path had zero primary-affinity defense (only the LISTEN/streamer paths validated the primary via `PrimaryValidator`). Setting `config.require_primary = true` (default **false** — a single-primary deployment is byte-identical) makes `verify_connection!` reject a connection that lands on a replica (`pg_is_in_recovery() => t`) at supervisor boot, raising a clear `ConfigurationError` instead of forking children that read nothing. (2) **GUC forwarding:** pgbus's AR-config extraction dropped database.yml's `variables:` block, so `client_min_messages` (and any GUC) never reached pgmq's dedicated raw connections (NOTICE flooding that three consuming apps hand-patched via `connection_params`). GUCs are now forwarded, on both the AR-extracted and explicit-`connection_params` paths, by `config.connection_guc_mode`: `:options` (default) bakes them into the libpq `options` STARTUP param (byte-compatible with today for the read-timeout `statement_timeout`, now also carrying `variables:`), while `:session` applies them via post-connect `SET` on a fresh connection instead — for a transaction-mode PgBouncer that **rejects** the `options` startup param with a FATAL. `pgbus doctor` gains a ninth check ("Primary affinity") that warns (never fails) when the job connection is currently on a replica, naming the direct-port remediation. DB-gated integration tests prove both GUC modes round-trip a forwarded GUC and that `require_primary` verifies on a real primary. Refs #332.
@@ -32,6 +34,7 @@
 
 ### Fixed
 
+- **AppSignal main dashboard: job and event lines now split by `job_class` and `routing_key`.** Applied the upstream review suggestions committed on appsignal/public_config#80 to the vendored `dashboard.json`: the "Job status per queue" panel gains a `job_class` wildcard tag filter and label (`%job_class% - %queue% - %status%`), and "Event handler status" gains `routing_key` (`%handler% - %status% - %routing_key%`). Without the wildcard tag entry a `%placeholder%` in the line label never resolves, so lines from different job classes / routing keys were collapsed together. The subscriber already emitted both tags; only the dashboard definition lagged.
 - **Migration generators now route to the pgbus database when `connects_to` is configured, even without an explicit `--database` (issue #344).** `rails g pgbus:add_stream_queues` (and every sibling generator via `Generators::MigrationPath`) keyed the separate-database decision purely on the `--database` flag. An app that had already set `config.connects_to = { database: { writing: :pgbus } }` (so its pgbus migrations live in `db/pgbus_migrate/` per database.yml's `migrations_paths:`) still got the migration written to the **primary** DB's `db/migrate/` on a bare invocation — where it then ran against the wrong database — and the "Next steps" output told the operator to run `rails db:migrate` instead of `rails db:migrate:pgbus`. `MigrationPath` now auto-detects the target database from `connects_to` (via the existing `DatabaseTargetDetector`: runtime config → initializer scan → application.rb scan) when `--database` is absent; an explicit `--database` still wins. The detected name drives both the migration path (resolving `migrations_paths` for that database, falling back to the `db/pgbus_migrate` convention) and the `db:migrate:<name>` suffix in every generator's post-install output. An app with no separate database is unaffected. Refs #344.
 - **`extract_ar_connection_hash` no longer forces `host: "localhost"` / `port: 5432` on a socket-based (host-less) database.yml — pgmq's connections now match ActiveRecord's on Unix-socket dev setups (issue #343).** A local database.yml with no `host:` is a Unix-socket connection: ActiveRecord connects via libpq's default socket (`PGHOST` / the default socket dir), but pgbus's AR-config extraction defaulted the absent `host`/`port` to TCP `localhost:5432`, silently diverging from AR and pointing pgmq's dedicated raw connections at a *different* server (or nothing) on any machine where the socket dir isn't `localhost`. Apps on socket-based dev DBs therefore couldn't use the AR-extraction path at all and had to pin an explicit `connection_params` Hash whose only real job was *not* defaulting `host` (cosmos carried an `after_initialize` block for exactly this). The two fallbacks are dropped: `host`/`port` now pass through as-is and `.compact` removes them when absent, so libpq applies its own socket defaults and matches AR. A config that *does* set `host`/`port` is byte-identical to before. Refs #343.
 - **`config.log_format` no longer breaks `ActiveSupport::TaggedLogging` — tags are preserved instead of dropped, and `logger.tagged` no longer raises (issue #334).** TaggedLogging works by extending the logger's formatter instance with a module that prepends the current tags. Installing a fresh pgbus formatter (`LogFormatter::JSON`/`Text`) stripped that extension, so `logger.tagged("req-42") { ... }` dropped the tag — and, worse, raised `NoMethodError: undefined method 'tagged'` on the pgbus formatter (a deploy-breaker several apps hit, then worked around with a dedicated `$stdout` logger). `log_format=` now re-extends the replacement formatter with `ActiveSupport::TaggedLogging::Formatter` when the previous one carried it, so tagging keeps working. Refs #334.

data/README.md

@@ -820,15 +820,23 @@ end
 
 #### Dashboards
 
-Three importable AppSignal dashboards ship with the gem:
+Four importable AppSignal dashboards ship with the gem:
 
-| File | Purpose |
-|------|---------|
-| `lib/pgbus/integrations/appsignal/dashboards/pgbus_throughput.json` | Jobs/sec, perform-duration percentiles, send/read counts |
-| `lib/pgbus/integrations/appsignal/dashboards/pgbus_health.json` | Queue depth, oldest message age, DLQ, dead tuples, MVCC horizon, worker recycles |
-| `lib/pgbus/integrations/appsignal/dashboards/pgbus_streams.json` | Broadcasts, fanout, active SSE connections, outbox, recurring tasks |
+| Name | File | Purpose |
+|------|------|---------|
+| `main` | `lib/pgbus/integrations/appsignal/dashboard.json` | All-in-one overview (the automated dashboard submitted to appsignal/public_config) |
+| `throughput` | `lib/pgbus/integrations/appsignal/dashboards/pgbus_throughput.json` | Jobs/sec, perform-duration percentiles, send/read counts |
+| `health` | `lib/pgbus/integrations/appsignal/dashboards/pgbus_health.json` | Queue depth, oldest message age, DLQ, dead tuples, MVCC horizon, worker recycles |
+| `streams` | `lib/pgbus/integrations/appsignal/dashboards/pgbus_streams.json` | Broadcasts, fanout, active SSE connections, outbox, recurring tasks |
+
+The files are stored in AppSignal's automated-dashboard format (a `metric_keys` trigger wrapping
+the dashboard object); `pgbus dashboard <name>` unwraps one into the JSON that AppSignal's
+"New dashboard" → "Import dashboard" dialog accepts:
 
-Import via the AppSignal dashboard UI ("New dashboard" → "Import JSON") or the AppSignal API.
+```bash
+pgbus dashboard --list            # available names and titles
+pgbus dashboard health | pbcopy   # paste into the import dialog
+```
 
 ### Metrics adapter (Prometheus / StatsD)
 
@@ -1872,6 +1880,25 @@ rake pgbus:doctor  # identical checks, for a Rake-based deploy pipeline
 
 The report ends with a resolved-config summary (queue prefix, pool size, roles, capsules) with any password redacted from `database_url` / `connection_params`. Warnings do not fail the exit code — only a `:fail` result does.
 
+##### Doctor preflight at boot (single Rails boot)
+
+Running `pgbus doctor || true` in a container entrypoint before `pgbus start` boots the full Rails app **twice** on every deploy, and the pre-supervisor `Process liveness` check false-fails (no workers exist yet) — which is why the `|| true` is needed, swallowing any genuinely-fatal finding too. Instead, run the preflight *inside* the booting supervisor:
+
+```bash
+pgbus start --doctor          # run the preflight, log the report, always boot
+pgbus start --doctor-strict   # refuse to boot on a fatal check (exit non-zero, fork nothing)
+```
+
+or set it in the initializer:
+
+```ruby
+Pgbus.configure do |c|
+  c.doctor_on_boot = :report   # or :strict; nil/false (default) is off
+end
+```
+
+The boot preflight runs after the DB is verified reachable and queues are bootstrapped, but **before any worker is forked** — one Rails boot, and the `Process liveness` check is skipped (nothing to observe yet, so it can't false-fail). `:strict` aborts the boot only on a genuinely-fatal, non-transient check — a `Configuration` failure or an **absent** PGMQ schema. A transient DB blip that the lenient queue bootstrap is designed to ride out (surfacing as a `Queues` or `Database` failure) is reported but never aborts, so a fleet-wide cold boot against a momentarily-saturated primary doesn't fail every pod in lockstep.
+
 #### pgbus dlq
 
 Dead-letter inspect/drain operations from a headless deployment or incident runbook, routed through `Web::DataSource` so retry/discard semantics are identical to the dashboard (origin-queue re-enqueue, transactional produce+delete, lock release on discard) with zero raw SQL and no direct PGMQ calls:

data/lib/pgbus/cli/dashboard.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  module CLI
+    # Prints the vendored AppSignal dashboard definitions as import-ready
+    # JSON. The files ship in the automated-dashboard format used by
+    # appsignal/public_config (a `metric_keys` trigger wrapping a
+    # `dashboard` object); AppSignal's "Import dashboard" dialog wants the
+    # inner object only, so this command unwraps it:
+    #
+    #   pgbus dashboard              # main dashboard
+    #   pgbus dashboard health      # one of the extra dashboards
+    #   pgbus dashboard --list      # available names and titles
+    module Dashboard
+      module_function
+
+      def start(args)
+        name = args.first || "main"
+        return list if ["--list", "list"].include?(name)
+
+        path = available[name]
+        unless path
+          warn "Unknown dashboard: #{name.inspect} (available: #{available.keys.join(", ")})"
+          exit 1
+        end
+
+        puts JSON.pretty_generate(definition(path))
+      end
+
+      def list
+        available.each do |name, path|
+          puts format("%-12s %s", name, definition(path)["title"])
+        end
+      end
+
+      # The main dashboard plus the extras, keyed by their short CLI name
+      # (pgbus_health.json => "health").
+      def available
+        require "pgbus/integrations/appsignal"
+
+        extras = Dir[File.join(Integrations::Appsignal::DASHBOARDS_DIR, "*.json")].to_h do |path|
+          [File.basename(path, ".json").delete_prefix("pgbus_"), path]
+        end
+        { "main" => Integrations::Appsignal::DASHBOARD_PATH }.merge(extras)
+      end
+
+      def definition(path)
+        JSON.parse(File.read(path)).fetch("dashboard")
+      end
+    end
+  end
+end

data/lib/pgbus/cli.rb

@@ -18,6 +18,8 @@ module Pgbus
         list_queues
       when "dlq"
         DLQ.start(args[1..] || [])
+      when "dashboard"
+        Dashboard.start(args[1..] || [])
       when "mcp"
         start_mcp_server
       when "doctor"
@@ -51,6 +53,16 @@ module Pgbus
       Pgbus.configuration.execution_mode = options[:execution_mode].to_sym if options[:execution_mode]
       apply_capsule_filter(options[:capsule]) if options[:capsule]
       apply_role_filter(options)
+      apply_doctor_flag(options)
+    end
+
+    # --doctor runs the boot preflight in report mode; --doctor-strict aborts
+    # the boot on a fatal finding. Both set config.doctor_on_boot, which the
+    # supervisor reads at boot (issue #347). Strict wins if both are passed — it
+    # is the stronger gate, so a user asking for both clearly wants strict.
+    def apply_doctor_flag(options)
+      Pgbus.configuration.doctor_on_boot = :report if options[:doctor]
+      Pgbus.configuration.doctor_on_boot = :strict if options[:doctor_strict]
     end
 
     def parse_start_options(args)
@@ -81,6 +93,14 @@ module Pgbus
         opts.on("--execution-mode MODE", "Execution mode: threads (default) or async") do |v|
           options[:execution_mode] = v
         end
+
+        opts.on("--doctor", "Run doctor preflight checks at boot and log the report (issue #347)") do
+          options[:doctor] = true
+        end
+
+        opts.on("--doctor-strict", "Run doctor preflight and refuse to boot on a fatal finding") do
+          options[:doctor_strict] = true
+        end
       end.parse!(args.dup)
       options
     end
@@ -178,6 +198,8 @@ module Pgbus
           queues   List queues with metrics
           dlq      Inspect and drain dead-letter queues
                    (list/show/retry/retry-all/purge)
+          dashboard  Print an AppSignal dashboard as import-ready JSON
+                     (main/health/streams/throughput; --list to enumerate)
           mcp      Start the read-only MCP diagnostic server over stdio
           doctor   Run environment diagnostics (config, DB, PGMQ, queues,
                    LISTEN/NOTIFY, process liveness); exits 1 on any failure
@@ -199,6 +221,12 @@ module Pgbus
                              pattern)
           --execution-mode   Execution mode: threads (default) or async
                              (fiber-based, lower connection usage)
+          --doctor           Run doctor preflight checks in the booting
+                             supervisor and log the report (one Rails boot
+                             instead of `pgbus doctor` + `pgbus start`)
+          --doctor-strict    Like --doctor, but refuse to boot (exit non-zero,
+                             fork nothing) if a fatal check fails (bad config
+                             or an absent PGMQ schema)
 
         Environment for `mcp`:
           PGBUS_MCP_TOKEN          If set, PGBUS_MCP_AUTH_TOKEN must match for

data/lib/pgbus/client.rb

@@ -1099,6 +1099,14 @@ module Pgbus
     ].freeze
     private_constant :STALE_CONNECTION_PATTERNS
 
+    # Compiled once: matches an error message containing any stale-connection
+    # pattern as a substring, case-insensitively (replacing the previous
+    # `message.downcase` + substring scan). Regexp.union escapes the literal
+    # parens in "pqsocket() ...", so they match literally.
+    STALE_CONNECTION_PATTERN =
+      Regexp.new(Regexp.union(STALE_CONNECTION_PATTERNS).source, Regexp::IGNORECASE).freeze
+    private_constant :STALE_CONNECTION_PATTERN
+
     # How many times a matched stale-connection error is retried before it
     # propagates. Two attempts (not one) so a transient window — a PgBouncer
     # restart or a brief failover — that outlasts the first immediate retry
@@ -1482,8 +1490,11 @@ module Pgbus
     end
 
     def stale_connection_error?(error)
-      message = error.message.to_s.downcase
-      STALE_CONNECTION_PATTERNS.any? { |pattern| message.include?(pattern) }
+      # Substring match against any stale-connection pattern. Deliberately a
+      # single Regexp rather than `STALE_CONNECTION_PATTERNS.any? { |p| msg.include?(p) }`:
+      # Style/ArrayIntersect misfires on that shape and "corrects" it to
+      # `patterns.intersect?(msg)`, which raises TypeError (String isn't an Array).
+      STALE_CONNECTION_PATTERN.match?(error.message.to_s)
     end
 
     # Substring pgmq-ruby uses when a pool checkout times out — a

data/lib/pgbus/configuration.rb

@@ -89,6 +89,19 @@ module Pgbus
     # PGMQ schema installation mode (:auto, :extension, :embedded)
     attr_reader :pgmq_schema_mode
 
+    # Run doctor preflight checks inside the supervisor at boot (issue #347),
+    # so an entrypoint need not boot Rails twice (once for `pgbus doctor`, once
+    # for `pgbus start`). nil/false (default) — off, byte-identical to today.
+    #   :report — run the preflight and log the report, always continue booting.
+    #   :strict — additionally REFUSE to boot (raise before forking any worker)
+    #             when a genuinely-fatal, non-transient check fails. The strict
+    #             set is deliberately narrow (Configuration, PGMQ schema) so a
+    #             transient boot-time DB blip — which the lenient queue bootstrap
+    #             is designed to ride out via child crash-and-backoff — never
+    #             aborts a whole fleet's cold boot in lockstep. Set via the
+    #             `--doctor` / `--doctor-strict` start flags too.
+    attr_reader :doctor_on_boot
+
     # Event consumers
     attr_reader :event_consumers
 
@@ -248,6 +261,7 @@ module Pgbus
       @worker_notify_database_url = nil
 
       @pgmq_schema_mode = :auto
+      @doctor_on_boot = nil
 
       @event_consumers = nil
 
@@ -566,6 +580,28 @@ module Pgbus
       @pgmq_schema_mode = mode
     end
 
+    VALID_DOCTOR_ON_BOOT_MODES = [nil, :report, :strict].freeze
+
+    # nil/false are both "off"; a String is coerced to a Symbol so the CLI flags
+    # and YAML-ish configs work. Validated at assignment time (like the other
+    # enum options), not in validate!.
+    def doctor_on_boot=(mode)
+      coerced = case mode
+                when nil, false then nil
+                when Symbol then mode
+                when String then mode.to_sym
+                else
+                  raise Pgbus::ConfigurationError,
+                        "Invalid doctor_on_boot type: #{mode.class}. Must be nil, false, String, or Symbol"
+                end
+      unless VALID_DOCTOR_ON_BOOT_MODES.include?(coerced)
+        raise Pgbus::ConfigurationError,
+              "Invalid doctor_on_boot: #{coerced.inspect}. Must be nil/false (off), :report, or :strict"
+      end
+
+      @doctor_on_boot = coerced
+    end
+
     def validate!
       if pool_size && !(pool_size.is_a?(Numeric) && pool_size.positive?)
         raise Pgbus::ConfigurationError, "pool_size must be a positive number or nil (auto-tune)"

data/lib/pgbus/doctor.rb

@@ -25,26 +25,47 @@ module Pgbus
 
     STATUS_ICON = { ok: "✓", warn: "!", fail: "✗" }.freeze
 
+    # The ordered check suite, name → method. The name strings are the public,
+    # stable identity of each check (used in the report and to select subsets).
+    CHECKS = {
+      "Configuration" => :check_configuration,
+      "Database" => :check_database,
+      "PGMQ schema" => :check_pgmq_schema,
+      "Queues" => :check_queues,
+      "LISTEN/NOTIFY" => :check_notify,
+      "Process liveness" => :check_processes,
+      "GlobalID allowlist" => :check_allowed_global_id_models,
+      "Broadcast queue" => :check_broadcast_queue,
+      "Primary affinity" => :check_primary
+    }.freeze
+
+    # Process liveness reads the pgbus_processes table (via HealthAnalyzer), so
+    # it is only meaningful once workers have registered. The supervisor boot
+    # preflight (issue #347) runs BEFORE forking any worker, so it excludes this
+    # check — otherwise stale prior-generation worker rows plus a visible backlog
+    # would produce a false STALLED verdict on a redeploy.
+    BOOT_SKIP = ["Process liveness"].freeze
+
+    # The subset of checks whose :fail is genuinely deploy-fatal AND not a
+    # transient the supervisor is designed to ride out. Only these abort a
+    # `:strict` boot. Configuration#validate! failing is a real config bug;
+    # an absent PGMQ schema means the migrations never ran. Deliberately NOT
+    # Queues/Database: the lenient queue bootstrap swallows a boot-time DB blip
+    # so children crash-and-backoff and recover, and verify_connection! already
+    # gated a hard-down DB before the preflight — making either strict-fatal
+    # would turn a tolerated transient into a fleet-wide lockstep boot abort.
+    STRICT_FATAL = ["Configuration", "PGMQ schema"].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)
+      @data_source = data_source
     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,
-        check_broadcast_queue,
-        check_primary
-      ].map(&:to_h)
+      @run ||= run_checks(CHECKS.keys)
     end
 
     # True when no check failed. Warnings do not fail the run — they surface a
@@ -53,11 +74,34 @@ module Pgbus
       run.none? { |c| c[:status] == :fail }
     end
 
+    # --- Supervisor boot preflight (issue #347) ---
+
+    # The checks safe to run inside the booting supervisor before any worker is
+    # forked: everything except the worker-dependent process-liveness check.
+    # Runs a genuine SUBSET — check_processes is never invoked — so there is no
+    # pre-fork HealthAnalyzer/DataSource round-trip.
+    def boot_checks
+      @boot_checks ||= run_checks(CHECKS.keys - BOOT_SKIP)
+    end
+
+    # True unless a strict-fatal check (see STRICT_FATAL) failed. Warnings and
+    # transient-shaped failures (Queues, Database) never block a `:strict` boot.
+    def boot_ok?
+      boot_checks.none? { |c| c[:status] == :fail && STRICT_FATAL.include?(c[:name]) }
+    end
+
+    # Human-readable report for the boot preflight — the boot_checks subset.
+    def boot_report
+      report(boot_checks)
+    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
+    # Defaults to the full run; pass a filtered result array (e.g. boot_checks)
+    # to render a subset.
+    def report(checks = run)
       lines = ["Pgbus Doctor", "=" * 40]
-      run.each do |check|
+      checks.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
@@ -86,6 +130,21 @@ module Pgbus
 
     private
 
+    # Run the named checks in CHECKS order and return an array of result hashes.
+    # Only the requested checks are INVOKED — a check omitted from `names` does
+    # no work (e.g. boot_checks never calls check_processes, so no HealthAnalyzer
+    # round-trip pre-fork).
+    def run_checks(names)
+      CHECKS.filter_map { |name, method| send(method).to_h if names.include?(name) }
+    end
+
+    # The dashboard data source backing the process-liveness check. Built lazily
+    # so the boot preflight (which excludes that check) never constructs a
+    # DataSource or touches the dashboard layer at the fork boundary.
+    def data_source
+      @data_source ||= Pgbus::Web::DataSource.new(client: @client)
+    end
+
     # True in a Rails production environment. Guarded so the doctor still runs
     # outside Rails (plain Ruby, tests) without assuming Rails is loaded.
     def production?
@@ -181,7 +240,7 @@ module Pgbus
     # 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
+      verdict = Pgbus::MCP::HealthAnalyzer.new(data_source).verdict
       status = verdict[:status]
       detail = Array(verdict[:reasons]).first || status
 

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -11,7 +11,7 @@
         "display": "LINE",
         "title": "Job status per queue",
         "description": "Processed, failed, and dead-lettered jobs per queue.",
-        "line_label": "%queue% - %status%",
+        "line_label": "%job_class% - %queue% - %status%",
         "format": "number",
         "draw_null_as_zero": true,
         "metrics": [
@@ -23,6 +23,10 @@
               }
             ],
             "tags": [
+              {
+                "key": "job_class",
+                "value": "*"
+              },
               {
                 "key": "queue",
                 "value": "*"
@@ -232,7 +236,7 @@
         "display": "LINE",
         "title": "Event handler status",
         "description": "Processed and failed event handler invocations.",
-        "line_label": "%handler% - %status%",
+        "line_label": "%handler% - %status% - %routing_key%",
         "format": "number",
         "draw_null_as_zero": true,
         "metrics": [
@@ -251,6 +255,10 @@
               {
                 "key": "status",
                 "value": "*"
+              },
+              {
+                "key": "routing_key",
+                "value": "*"
               }
             ]
           }

data/lib/pgbus/process/supervisor.rb

@@ -76,6 +76,14 @@ module Pgbus
         # notify_trigger_current? makes those calls cheap no-ops.
         bootstrap_queues
 
+        # Optional in-process doctor preflight (issue #347): run the diagnostic
+        # checks here — after config is loaded, the DB is verified reachable, and
+        # queues are bootstrapped, but BEFORE any worker is forked — so an
+        # entrypoint gets a single Rails boot instead of `pgbus doctor` + `pgbus
+        # start`. :strict aborts the boot (raising, so nothing forks) on a
+        # genuinely-fatal finding; :report only logs. Off by default.
+        run_doctor_preflight unless config.doctor_on_boot.nil?
+
         boot_processes
         monitor_loop
       ensure
@@ -683,6 +691,33 @@ module Pgbus
         ErrorReporter.report(e, { action: "bootstrap_queues" })
       end
 
+      # In-process doctor preflight (issue #347). Runs the boot-safe subset of
+      # doctor checks (everything except the worker-dependent process-liveness
+      # check, which has no workers to observe yet) against the supervisor's own
+      # config and the already-verified shared client, and logs the report.
+      #
+      # In :strict mode, a genuinely-fatal check (Doctor::STRICT_FATAL —
+      # Configuration or an absent PGMQ schema) aborts the boot by raising
+      # Pgbus::ConfigurationError. Because this runs before boot_processes, no
+      # child is forked, and `run`'s `ensure shutdown` tears down the heartbeat
+      # and health server — the same fail-fast path verify_connection! uses.
+      # A transient-shaped failure (Queues, Database) is reported but never
+      # aborts: the lenient bootstrap above is built to let children ride out a
+      # boot-time DB blip, and a strict abort there would take down a whole
+      # fleet's cold boot in lockstep.
+      def run_doctor_preflight
+        doctor = Pgbus::Doctor.new(config: config, client: Pgbus.client)
+        report = doctor.boot_report
+        Pgbus.logger.info { "[Pgbus] doctor preflight (#{config.doctor_on_boot}):\n#{report}" }
+
+        return unless config.doctor_on_boot == :strict
+        return if doctor.boot_ok?
+
+        raise Pgbus::ConfigurationError,
+              "doctor preflight failed a fatal check (doctor_on_boot: :strict) — refusing to boot. " \
+              "See the report above."
+      end
+
       def load_rails_app
         return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
 

data/lib/pgbus/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.11.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -253,6 +253,7 @@ files:
 - lib/pgbus/bus_record.rb
 - lib/pgbus/circuit_breaker.rb
 - lib/pgbus/cli.rb
+- lib/pgbus/cli/dashboard.rb
 - lib/pgbus/cli/dlq.rb
 - lib/pgbus/client.rb
 - lib/pgbus/client/connection_health.rb