pgbus 0.17.0 → 0.17.2

data/lib/pgbus/failed_event_recorder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "time"
+
 module Pgbus
   # Records job failures to pgbus_failed_events for dashboard visibility.
   # Uses upsert (INSERT ON CONFLICT UPDATE) keyed on (queue_name, msg_id)
@@ -47,6 +49,48 @@ module Pgbus
         false
       end
 
+      # The message's latest recorded failure, read by a mover just before it
+      # dead-letters the message and clears the row (issue #495). failed_at
+      # comes back as an ISO 8601 UTC string whatever the adapter decodes it
+      # to. A failed read returns nil: it must never stop a dead-letter.
+      def last_error(queue_name:, msg_id:)
+        row = connection.select_one(
+          "SELECT error_class, error_message, backtrace, retry_count, failed_at " \
+          "FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2 LIMIT 1",
+          "FailedEvent Last Error",
+          [queue_name, msg_id.to_i]
+        )
+        return unless row
+
+        {
+          error_class: row["error_class"],
+          error_message: row["error_message"],
+          backtrace: row["backtrace"],
+          retry_count: row["retry_count"].to_i,
+          failed_at: iso_utc(row["failed_at"])
+        }
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus] FailedEvent last_error read failed: #{e.class}: #{e.message}" }
+        nil
+      end
+
+      # Drops every row recorded under any of `queue_names`. Called when a
+      # queue is dropped: PGMQ restarts msg_ids on recreate, so a surviving
+      # row would aim the dashboard's retry/discard at an unrelated message.
+      # Queue names are validated word characters, so the array literal is safe.
+      def clear_queue!(queue_names)
+        connection.exec_delete(
+          "DELETE FROM pgbus_failed_events WHERE queue_name = ANY($1::text[])",
+          "FailedEvent Clear Queue",
+          ["{#{queue_names.join(",")}}"]
+        )
+      rescue StandardError => e
+        Pgbus.logger.error do
+          "[Pgbus] Failed to clear failed events for dropped queue(s) #{queue_names.join(", ")}: " \
+            "#{e.class}: #{e.message}"
+        end
+      end
+
       def clear!(queue_name:, msg_id:)
         connection.exec_delete(
           "DELETE FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2",
@@ -65,6 +109,13 @@ module Pgbus
 
       private
 
+      def iso_utc(value)
+        time = value.is_a?(String) ? Time.parse(value) : value
+        time&.utc&.iso8601(6)
+      rescue ArgumentError
+        value.to_s
+      end
+
       def connection
         if defined?(BusRecord) && BusRecord.connected?
           BusRecord.connection

data/lib/pgbus/instrumentation.rb

@@ -15,7 +15,8 @@ module Pgbus
   #   pgbus.executor.execute       — full job execution (deserialize + perform + archive)
   #   pgbus.job_completed          — job archived successfully
   #   pgbus.job_failed             — job raised; carries :exception_object
-  #   pgbus.job_dead_lettered      — job exceeded max_retries and was DLQ-routed
+  #   pgbus.job_dead_lettered      — job exceeded max_retries and was DLQ-routed;
+  #                                  :error is the last recorded error class (or nil)
   #   pgbus.job_visibility_extended — heartbeat re-armed a running job's visibility timeout
   #                                  payload: queue, job_class, msg_id, vt, extensions
   #   pgbus.event_processed        — event handler succeeded

data/lib/pgbus/mcp/base_tool.rb

@@ -70,6 +70,31 @@ module Pgbus
           ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(redacted) }])
         end
 
+        # Past the count cap the total is a lower bound, so only a full page
+        # can have another one behind it. At the page ceiling the next call
+        # would clamp back to this page, so there is no "more" to fetch.
+        def more_pages?(count, page:, per_page:, shown:)
+          return false if page >= self::MAX_PAGE
+
+          count.capped? ? shown == per_page : page * per_page < count.total
+        end
+
+        DEAD_LETTER_SUMMARY_KEYS = %w[reason source source_queue attempts max_retries dead_lettered_at
+                                      retries_from_dlq error_class error_attempt error_recorded_at].freeze
+        DEAD_LETTER_ERROR_KEYS = %w[error_message backtrace].freeze
+
+        # Why a DLQ row died, from its DeadLetterHeader block (issue #495), or
+        # nil for a row dead-lettered before the block existed. The error
+        # message and backtrace can quote payload values, and the Redactor
+        # does not know those keys, so they are added only with include_error.
+        def dead_letter_summary(row, include_error:)
+          block = Pgbus::DeadLetterHeader.parse(row[:headers])
+          return unless block
+
+          keys = include_error ? DEAD_LETTER_SUMMARY_KEYS + DEAD_LETTER_ERROR_KEYS : DEAD_LETTER_SUMMARY_KEYS
+          block.slice(*keys)
+        end
+
         # Wrap an error message as an MCP error response (isError: true) so the
         # client surfaces it as a tool failure rather than a normal result.
         def error_response(message)

data/lib/pgbus/mcp/tools/concurrency_tool.rb

@@ -17,14 +17,33 @@ module Pgbus
           their limit — plus up to 100 key rows with value/limit, lease expiry,
           whether the lease is still fresh, parked count and oldest wait. A key
           with a stale lease and a parked backlog is a stuck pipeline: its holder
-          died before releasing the slot.
+          died before releasing the slot. The key rows are paginated (default
+          100 per page, capped at 100); the response also carries page,
+          per_page, total (number of keys, capped at 10000) and has_more.
         DESC
 
-        input_schema(properties: {}, required: [])
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
 
-        def self.call(server_context: nil)
+        input_schema(
+          properties: {
+            page: { type: "integer", description: "1-based page number (default 1, max 1000).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 100, max 100).", minimum: 1 }
+          },
+          required: []
+        )
+
+        def self.call(page: 1, per_page: MAX_PER_PAGE, server_context: nil)
           data_source = data_source_from(server_context)
-          json_response(data_source.concurrency_stats)
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = page.to_i.clamp(1, MAX_PAGE)
+          stats = data_source.concurrency_stats(page: page, per_page: per_page)
+          count = data_source.list_count(:concurrency_keys)
+
+          json_response(
+            stats.merge(page: page, per_page: per_page, total: count.total,
+                        has_more: more_pages?(count, page: page, per_page: per_page, shown: stats[:keys].size))
+          )
         end
       end
     end

data/lib/pgbus/mcp/tools/dlq_detail_tool.rb

@@ -12,7 +12,7 @@ module Pgbus
         title "Pgbus Dead-Letter Detail"
         description <<~DESC
           Inspect one dead-letter message: read_ct, vt, enqueued_at, source
-          queue. Pass the full physical DLQ queue name (e.g.
+          queue, and a dead_letter summary of why it died. Pass the full physical DLQ queue name (e.g.
           "pgbus_default_dlq") in +queue+ to disambiguate — msg_ids are only
           unique within a single DLQ table, so the same id can exist in more
           than one. Without +queue+ the tool scans every "_dlq" table and
@@ -48,7 +48,9 @@ module Pgbus
           return error_response("Dead-letter message #{msg_id} not found") unless detail
           return detail if detail.is_a?(::MCP::Tool::Response)
 
-          json_response({ message: detail }, server_context: server_context, include_payloads: include_payloads)
+          summary = dead_letter_summary(detail, include_error: payloads_allowed?(server_context, include_payloads))
+          json_response({ message: detail.merge(dead_letter: summary) },
+                        server_context: server_context, include_payloads: include_payloads)
         end
 
         # When the caller didn't specify a queue, scan every DLQ for the id and

data/lib/pgbus/mcp/tools/dlq_tool.rb

@@ -10,9 +10,12 @@ module Pgbus
         title "Pgbus Dead-Letter Queue"
         description <<~DESC
           List messages sitting in dead-letter queues (queues whose name ends
-          in "_dlq") with read_ct, vt and enqueued_at. Paginated (default 25,
-          max 100). Message bodies and headers are redacted unless the server
-          allows payloads and include_payloads is set.
+          in "_dlq") with read_ct, vt and enqueued_at, and a dead_letter
+          summary of why each died (reason, source queue, attempts, error
+          class; null for messages dead-lettered before pgbus recorded it).
+          Paginated (default 25, max 100). Message bodies, headers and the
+          error message/backtrace are redacted unless the server allows
+          payloads and include_payloads is set.
         DESC
 
         MAX_PER_PAGE = 100
@@ -34,7 +37,10 @@ module Pgbus
           data_source = data_source_from(server_context)
           per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
           page = page.to_i.clamp(1, MAX_PAGE)
-          rows = data_source.dlq_messages(page: page, per_page: per_page)
+          include_error = payloads_allowed?(server_context, include_payloads)
+          rows = data_source.dlq_messages(page: page, per_page: per_page).map do |row|
+            row.merge(dead_letter: dead_letter_summary(row, include_error: include_error))
+          end
 
           json_response(
             { page: page, per_page: per_page, messages: rows },

data/lib/pgbus/mcp/tools/locks_tool.rb

@@ -12,15 +12,33 @@ module Pgbus
         description <<~DESC
           List active job uniqueness locks with their lock_key, queue_name,
           msg_id, and age in seconds. A lock that outlives its message
-          indicates a leaked uniqueness key blocking re-enqueues. Returns the
-          100 most recent locks.
+          indicates a leaked uniqueness key blocking re-enqueues. Paginated
+          (default 100 per page, capped at 100); the response carries page,
+          per_page, total (capped at 10000) and has_more.
         DESC
 
-        input_schema(properties: {}, required: [])
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
 
-        def self.call(server_context: nil)
+        input_schema(
+          properties: {
+            page: { type: "integer", description: "1-based page number (default 1, max 1000).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 100, max 100).", minimum: 1 }
+          },
+          required: []
+        )
+
+        def self.call(page: 1, per_page: MAX_PER_PAGE, server_context: nil)
           data_source = data_source_from(server_context)
-          json_response({ locks: data_source.job_locks })
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = page.to_i.clamp(1, MAX_PAGE)
+          locks = data_source.job_locks(page: page, per_page: per_page)
+          count = data_source.list_count(:job_locks)
+
+          json_response(
+            { locks: locks, page: page, per_page: per_page, total: count.total,
+              has_more: more_pages?(count, page: page, per_page: per_page, shown: locks.size) }
+          )
         end
       end
     end

data/lib/pgbus/mcp/tools/recurring_tool.rb

@@ -12,15 +12,44 @@ module Pgbus
         description <<~DESC
           List recurring (cron) tasks with their schedule, human-readable
           schedule, queue, enabled state, last_run_at and next_run_at. Use this
-          to confirm scheduled work is firing on time.
+          to confirm scheduled work is firing on time. Returns every task unless
+          page or per_page is given; then it is paginated (per_page defaults to
+          100, capped at 100). The response carries page, per_page, total
+          (capped at 10000 when paginated; the exact row count when not) and
+          has_more; per_page is null when unpaginated.
         DESC
 
-        input_schema(properties: {}, required: [])
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
 
-        def self.call(server_context: nil)
+        input_schema(
+          properties: {
+            page: { type: "integer", description: "1-based page number (default 1, max 1000).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 100 once paginating, max 100).", minimum: 1 }
+          },
+          required: []
+        )
+
+        def self.call(page: nil, per_page: nil, server_context: nil)
           data_source = data_source_from(server_context)
-          json_response({ recurring_tasks: data_source.recurring_tasks })
+          return unpaged(data_source) if page.nil? && per_page.nil?
+
+          per_page = (per_page || MAX_PER_PAGE).to_i.clamp(1, MAX_PER_PAGE)
+          page = (page || 1).to_i.clamp(1, MAX_PAGE)
+          tasks = data_source.recurring_tasks(page: page, per_page: per_page)
+          count = data_source.list_count(:recurring_tasks)
+
+          json_response(
+            { recurring_tasks: tasks, page: page, per_page: per_page, total: count.total,
+              has_more: more_pages?(count, page: page, per_page: per_page, shown: tasks.size) }
+          )
+        end
+
+        def self.unpaged(data_source)
+          tasks = data_source.recurring_tasks
+          json_response({ recurring_tasks: tasks, page: 1, per_page: nil, total: tasks.size, has_more: false })
         end
+        private_class_method :unpaged
       end
     end
   end

data/lib/pgbus/outbox/poller.rb

@@ -139,7 +139,7 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Process::Heartbeat.new(
           kind: "outbox_poller",
-          metadata: { pid: ::Process.pid }
+          metadata: { pid: ::Process.pid, started_at: Time.now.to_f, supervisor_pid: ::Process.ppid }
         )
         @heartbeat.start
       end

data/lib/pgbus/process/claim_buffer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # The read-ahead buffer a Worker or Consumer owns (issue #486).
+    #
+    # Under database latency the claim loop used to issue one read round trip
+    # per job: once the pool is full, slots free one at a time and each loop
+    # step read `qty = free slots` = 1. With `read_ahead = N` the loop claims
+    # up to N messages beyond its free slots and parks them here, so one read
+    # returns a batch and the pool never waits on the reader.
+    #
+    # Surplus claims cannot live inside the execution pool: AsyncPool#post
+    # raises at zero capacity and a queued block could not be handed back on
+    # drain. So the buffer is drained into the pool only while it has a free
+    # slot, and returned to the queue (vt: 0) on drain, recycle or shutdown.
+    #
+    # Every buffered message is kept invisible by a VisibilityHeartbeat hold
+    # from claim until the run starts, under the executor's key
+    # (`source_queue || queue_name`, `prefixed: source_queue.nil?`), so the
+    # run's own tracking takes over the same entry with no gap. The hold does
+    # not know the job class, so a job that opted out with
+    # `pgbus_visibility_heartbeat false` is still held while it waits here:
+    # the opt-out covers its run, not the wait. With the heartbeat disabled
+    # globally there is no hold at all (Configuration#validate! warns).
+    #
+    # Only ever touched from the owning process's loop thread, so no mutex.
+    class ClaimBuffer
+      Claim = Struct.new(:queue_name, :message, :source_queue, :hold)
+
+      HOLD_LABEL = "(read-ahead)"
+
+      def initialize(config: Pgbus.configuration)
+        @config = config
+        @claims = []
+      end
+
+      def size
+        @claims.size
+      end
+
+      def empty?
+        @claims.empty?
+      end
+
+      def push(queue_name, message, source_queue = nil, client: Pgbus.client)
+        hold = VisibilityHeartbeat.hold(
+          client: client, queue_name: source_queue || queue_name, prefixed: source_queue.nil?,
+          msg_id: message.msg_id, job_class: HOLD_LABEL, config: @config
+        )
+        @claims << Claim.new(queue_name, message, source_queue, hold)
+        self
+      end
+
+      def shift
+        @claims.shift
+      end
+
+      # Yields the oldest claims, one per free pool slot, and returns how many.
+      # Capacity is re-read before every claim: the block's post takes a slot.
+      def drain_into(pool)
+        drained = 0
+        while !@claims.empty? && pool.available_capacity.positive?
+          yield @claims.shift
+          drained += 1
+        end
+        drained
+      end
+
+      # How many messages the next read should claim: enough to fill the free
+      # slots and top the buffer back up to `read_ahead`, never more than
+      # `prefetch_room` (prefetch_limit minus everything already claimed).
+      # With read_ahead 0 and an empty buffer this is `free_slots`: the
+      # pre-#486 qty.
+      def deficit(free_slots:, read_ahead:, prefetch_room: nil)
+        want = free_slots + read_ahead - @claims.size
+        want = [want, prefetch_room].min if prefetch_room
+        want.clamp(0..)
+      end
+
+      # Hand every buffered message back to the queue right away instead of
+      # leaving it invisible until its timeout. Their read_ct has already been
+      # bumped, the same cost a crash or a stale claim pays. A failed return
+      # is logged and skipped: the hold is already dropped, so the message
+      # reappears when its current timeout runs out. Returns the count. One
+      # claim at a time, so #size stays true while the returns are written.
+      def return_all!(client: Pgbus.client)
+        returned = 0
+        while (claim = @claims.shift)
+          return_claim(claim, client)
+          returned += 1
+        end
+        returned
+      end
+
+      private
+
+      # The hold goes first: a heartbeat tick that still held the entry could
+      # otherwise write its extension after the vt: 0 and hide the message
+      # again for a full visibility_timeout. (VisibilityHeartbeat#extend!
+      # re-checks registration, which shrinks the remaining window to the
+      # tick's own check-then-write.)
+      def return_claim(claim, client)
+        VisibilityHeartbeat.release(claim.hold)
+        queue = claim.source_queue || claim.queue_name
+        client.set_visibility_timeout(queue, claim.message.msg_id.to_i, vt: 0, prefixed: claim.source_queue.nil?)
+      rescue StandardError => e
+        Pgbus.logger.warn do
+          "[Pgbus] Could not return read-ahead message msg_id=#{claim.message.msg_id} queue=#{queue}: " \
+            "#{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/process/consumer.rb

@@ -7,7 +7,7 @@ module Pgbus
     class Consumer
       include SignalHandler
 
-      attr_reader :topics, :threads, :config, :execution_mode,
+      attr_reader :topics, :threads, :config, :execution_mode, :read_ahead,
                   :queue_names, :wake_signal, :notify_retry_backoff, :circuit_breaker
       # notify_listener is writable so tests can simulate a start_notify_listener
       # success from inside a stub (production sets it in start_notify_listener).
@@ -30,6 +30,11 @@ module Pgbus
         @jobs_processed.value
       end
 
+      # Messages claimed by read-ahead and not yet handed to the pool (#486).
+      def buffered
+        @claim_buffer.size
+      end
+
       # Seed the processed-job counter. Used by tests to drive the recycle
       # thresholds without running thousands of real jobs; production only ever
       # increments it via the AtomicFixnum during message handling.
@@ -60,7 +65,7 @@ module Pgbus
                      queue_names: nil, liveness_pipe: nil, stat_buffer: :default,
                      notify_listener: nil, notify_retry_at: 0.0,
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
-                     started_at_monotonic: nil, wake_pipe: nil)
+                     started_at_monotonic: nil, wake_pipe: nil, read_ahead: nil)
         @topics = Array(topics)
         @threads = threads
         @config = config
@@ -68,8 +73,12 @@ module Pgbus
         @shutting_down = false
         @recycling = false
         @jobs_processed = Concurrent::AtomicFixnum.new(0)
+        @read_ahead = read_ahead || config.read_ahead
+        @claim_buffer = ClaimBuffer.new(config: config)
         @loop_tick_at = Concurrent::AtomicReference.new(nil)
         @started_at_monotonic = started_at_monotonic || monotonic_now
+        # Wall clock for the Processes page's uptime (issue #493).
+        @started_at = Time.current
         @wake_signal = WakeSignal.new
         @pool = ExecutionPools.build(
           mode: @execution_mode,
@@ -134,7 +143,12 @@ module Pgbus
           check_recycle
           ensure_notify_listener
 
-          break if @shutting_down
+          if @shutting_down
+            # No drain loop here: buffered claims go straight back to the
+            # queue; shutdown then waits for the ones already running.
+            @claim_buffer.return_all!(client: Pgbus.client) unless @claim_buffer.empty?
+            break
+          end
 
           consume
           @stat_buffer&.flush_if_due
@@ -171,20 +185,35 @@ module Pgbus
         @queue_names = @registry.queue_names_for_topics(topics)
       end
 
+      # Same loop step as Worker#claim_and_execute (issue #486): feed
+      # buffered claims to free slots, read the deficit, feed again, and wait
+      # only when the step moved nothing.
       def consume
-        idle = @pool.available_capacity
-        return @wake_signal.wait(timeout: wake_timeout) if idle <= 0
-
-        tagged_messages = fetch_messages(idle)
-
-        if tagged_messages.empty?
-          @wake_signal.wait(timeout: wake_timeout)
-          return
+        drained = drain_claim_buffer
+        claimed = claim_deficit
+        drained += drain_claim_buffer
+        @wake_signal.wait(timeout: wake_timeout) if drained.zero? && claimed.zero?
+      end
+
+      # The hold is released before handle_message's own heartbeat tracking
+      # registers the same key, so the message is never untracked in between.
+      def drain_claim_buffer
+        @claim_buffer.drain_into(@pool) do |claim|
+          @pool.post do
+            VisibilityHeartbeat.release(claim.hold)
+            handle_message(claim.message, claim.queue_name)
+          end
         end
+      end
 
-        tagged_messages.each do |queue_name, message|
-          @pool.post { handle_message(message, queue_name) }
-        end
+      def claim_deficit
+        want = @claim_buffer.deficit(free_slots: @pool.available_capacity, read_ahead: @read_ahead)
+        return 0 if want.zero?
+
+        tagged_messages = fetch_messages(want)
+        client = Pgbus.client
+        tagged_messages.each { |queue_name, message| @claim_buffer.push(queue_name, message, client: client) }
+        tagged_messages.size
       end
 
       # Returns an array of [queue_name, message] pairs. Queues whose circuit
@@ -219,7 +248,7 @@ module Pgbus
 
         if message.read_ct.to_i > config.max_retries
           Pgbus.logger.warn { "[Pgbus] Consumer moving message #{message.msg_id} to DLQ after #{message.read_ct} reads" }
-          Pgbus.client.move_to_dead_letter(queue_name, message)
+          dead_letter(message, queue_name)
           record_stat(message, queue_name, "dead_lettered", execution_start)
           return
         end
@@ -236,6 +265,9 @@ module Pgbus
         end
 
         Pgbus.client.archive_message(queue_name, message.msg_id.to_i)
+        # A redelivery that succeeds leaves no stale failure behind. First
+        # deliveries never had one: no query on the hot path (#484's gate).
+        FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i) if message.read_ct.to_i > 1
         @circuit_breaker.record_success(queue_name)
         record_stat(message, queue_name, "success", execution_start)
       rescue StandardError => e
@@ -243,6 +275,9 @@ module Pgbus
         # Message stays in queue; VT will expire and it becomes available again.
         # read_ct tracks delivery attempts — when it exceeds max_retries,
         # the next read will route to DLQ above.
+        # A dead-letter read fails only in the move: keep the handler's error
+        # on the row for the next attempt's DLQ block instead of the move's.
+        record_failed_event(message, queue_name, e) unless message.read_ct.to_i > config.max_retries
         @circuit_breaker.record_failure(queue_name)
         record_stat(message, queue_name, "failed", execution_start)
       ensure
@@ -254,6 +289,31 @@ module Pgbus
         @jobs_processed.increment
       end
 
+      # Order: read the last error, move with the dead-letter block, then
+      # clear the failed-event row. A move that raises keeps the row, so the
+      # next attempt still carries the reason.
+      def dead_letter(message, queue_name)
+        last_error = FailedEventRecorder.last_error(queue_name: queue_name, msg_id: message.msg_id.to_i)
+        headers = DeadLetterHeader.build(
+          existing: message.headers, reason: DeadLetterHeader::REASON_MAX_RETRIES, source: "consumer",
+          source_queue: config.queue_name(queue_name), attempts: message.read_ct.to_i,
+          max_retries: config.max_retries, error: last_error
+        )
+        Pgbus.client.move_to_dead_letter(queue_name, message, headers: headers)
+        FailedEventRecorder.clear!(queue_name: queue_name, msg_id: message.msg_id.to_i)
+      end
+
+      # The executor's handle_failure, for events (issue #494): one upsert per
+      # failure, under the LOGICAL queue name, so the dashboard reads the event
+      # as retrying with its error. No ErrorReporter call: Handler#process!
+      # already instruments pgbus.event_failed, which feeds the reporters.
+      def record_failed_event(message, queue_name, error)
+        FailedEventRecorder.record!(
+          queue_name: queue_name, msg_id: message.msg_id.to_i, payload: message.message,
+          headers: message.headers, error: error, retry_count: [message.read_ct.to_i - 1, 0].max
+        )
+      end
+
       # Run every handler that owns this message, with the message's visibility
       # timeout held open for as long as they take (issue #470).
       #
@@ -555,13 +615,30 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "consumer",
-          metadata: { topics: topics, threads: threads, pid: ::Process.pid },
+          metadata: {
+            topics: topics, threads: threads, pid: ::Process.pid, execution_mode: @execution_mode,
+            started_at: @started_at.to_f, supervisor_pid: ::Process.ppid
+          },
           on_beat: -> { on_heartbeat },
-          loop_tick_supplier: -> { @loop_tick_at.get }
+          loop_tick_supplier: -> { @loop_tick_at.get },
+          metadata_supplier: -> { throughput_metadata }
         )
         @heartbeat.start
       end
 
+      # What the Processes page states about a consumer (issue #493), read
+      # once per beat, never per message. String keys: the value round-trips
+      # through JSON in the metadata column.
+      def throughput_metadata
+        pool = @pool.metadata
+        {
+          "jobs_processed" => @jobs_processed.value, "buffered" => @claim_buffer.size,
+          "capacity" => pool[:capacity], "busy" => pool[:busy], "memory_mb" => current_memory_mb,
+          "max_jobs" => config.max_jobs_per_worker, "max_memory_mb" => config.max_memory_mb,
+          "max_lifetime" => config.max_worker_lifetime
+        }.compact
+      end
+
       # Runs once per heartbeat interval (not per message), so it's the right
       # place to emit connection-pool observability without touching any per-job
       # hot path. Reading the pool must never crash the beat — pool_stats already

data/lib/pgbus/process/dispatcher.rb

@@ -697,7 +697,7 @@ module Pgbus
       def start_heartbeat
         @heartbeat = Heartbeat.new(
           kind: "dispatcher",
-          metadata: { pid: ::Process.pid },
+          metadata: { pid: ::Process.pid, started_at: Time.now.to_f, supervisor_pid: ::Process.ppid },
           loop_tick_supplier: -> { @loop_tick_at.get }
         )
         @heartbeat.start