pgbus 0.7.8 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48e02fc16de64a9ccec20b8b0d917e154e17dc2082c1e3933b80da1bdc2f0c2a
-  data.tar.gz: 811db2dfcb4c4271296d9125754af3865b117ebc8b45d3194bc4314cc43ffaba
+  metadata.gz: 60cc7178f84e5d28919085f5c5a9d824aca958180d433daf13cb04a369ed25c0
+  data.tar.gz: 5a7fdb569f90cf3e60ef5951e86d6ed0c3c31c7703b0f88be91c2df3054b8817
 SHA512:
-  metadata.gz: 2b41cd760d469af41c4e0ef0d9bfaffd3cb17ff81b38dbeb250605d78c737708f54ee43519fe25afeda83a5e15177a14e89e48d27471ae39ad5c79420d791e21
-  data.tar.gz: 50f209ed7b74e18c1bf927ca73fe80286c9a4333642af4f32e579bd6f9e40158007c07a39dfa6a3fc2082fd9ad1663f3e9b109ebd7021485f931a615ad9baabb
+  metadata.gz: 8cc8aa7893bdb605379f4cea9542766062b5a759a89d6149e49a39729484f56790bc131b1063b16a855357a0ab4979aeb52f4bd9f572568e793482fcabaf9939
+  data.tar.gz: '052525538d45540220e66da0d43f007727848543d8f1184f7598f481e3abe3fe6be961eb6c634f414c158cd884b856305a35ded77e39d2f0f4d7c24bc10cf1a4'

data/README.md

@@ -728,6 +728,48 @@ Reporters are wired into all critical rescue paths: job execution failures, work
 
 `ErrorReporter.report` is guaranteed to never raise — if a reporter or the logger itself throws, the error is swallowed silently. This preserves fault-tolerance invariants at every rescue site.
 
+### AppSignal integration
+
+When the `appsignal` gem is loaded in your app, Pgbus auto-installs a subscriber and a minutely probe that report into AppSignal:
+
+- **Background-job transactions** for every ActiveJob run and every event-bus handler invocation. Action names follow the AppSignal convention: `MyJob#perform`, `MyHandler#handle`. Tags include `queue`, `job_class`/`handler`, `routing_key`, `attempts`, and the `active_job_id` / `provider_job_id`. `enqueued_at` becomes the AppSignal `queue_start` timestamp so "time on queue" shows up correctly in the timeline.
+- **Custom counters and distributions** for sends, reads, broadcasts, outbox publishes, recurring scheduling, and worker recycles. All metric names are prefixed `pgbus_`.
+- **A minutely probe** that gauges queue depth (visible vs total), oldest message age per queue, DLQ depth, failed events count, dead-tuple totals, MVCC horizon age, active processes, and stream connection estimates.
+
+There is nothing to wire up — load the appsignal gem and the integration installs itself in a Rails initializer. To opt out:
+
+```ruby
+Pgbus.configure do |c|
+  c.appsignal_enabled = false        # disable subscriber + probe entirely
+  c.appsignal_probe_enabled = false  # keep transactions, drop the gauge probe
+end
+```
+
+#### Dashboards
+
+Three 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 |
+
+Import via the AppSignal dashboard UI ("New dashboard" → "Import JSON") or the AppSignal API.
+
+#### Custom subscriptions
+
+The integration is built on `ActiveSupport::Notifications`. If you want to push pgbus telemetry into a different APM (Datadog, New Relic, OpenTelemetry), subscribe directly:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/^pgbus\./) do |name, start, finish, _id, payload|
+  duration_ms = (finish - start) * 1_000
+  YourApm.record(name, duration_ms, payload)
+end
+```
+
+Events emitted: `pgbus.executor.execute`, `pgbus.job_completed`, `pgbus.job_failed`, `pgbus.job_dead_lettered`, `pgbus.event_processed`, `pgbus.event_failed`, `pgbus.client.send_message`, `pgbus.client.send_batch`, `pgbus.client.read_batch`, `pgbus.stream.broadcast`, `pgbus.outbox.publish`, `pgbus.recurring.enqueue`, `pgbus.worker.recycle`. Payload keys are documented in `lib/pgbus/instrumentation.rb`.
+
 ### Structured logging
 
 Pgbus ships two log formatters inspired by Sidekiq's `Logger::Formatters`:

data/app/helpers/pgbus/streams_helper.rb

@@ -131,7 +131,9 @@ module Pgbus
       return nil if cache[:script_emitted]
 
       cache[:script_emitted] = true
-      script = '<script type="module">import "pgbus/stream_source_element"</script>'
+      nonce = content_security_policy_nonce if respond_to?(:content_security_policy_nonce)
+      nonce_attr = nonce ? %( nonce="#{CGI.escape_html(nonce)}") : ""
+      script = %(<script type="module"#{nonce_attr}>import "pgbus/stream_source_element"</script>)
       script.respond_to?(:html_safe) ? script.html_safe : script
     end
 

data/lib/pgbus/active_job/executor.rb

@@ -33,6 +33,15 @@ module Pgbus
           signal_batch_discarded(payload)
           Uniqueness.release_lock(Uniqueness.extract_key(payload))
           record_stat(payload, queue_name, "dead_lettered", execution_start, message: message)
+          instrument(
+            "pgbus.job_dead_lettered",
+            queue: queue_name,
+            job_class: job_class,
+            job_id: payload["job_id"],
+            provider_job_id: payload["provider_job_id"],
+            read_ct: read_count,
+            msg_id: message.msg_id.to_i
+          )
           Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{tag} job_class=#{job_class}" }
           return :dead_lettered
         end
@@ -60,7 +69,17 @@ module Pgbus
         job_succeeded = false
 
         msg_id = message.msg_id.to_i
-        Instrumentation.instrument("pgbus.executor.execute", queue: queue_name, job_class: job_class) do
+        instrument_payload = {
+          queue: queue_name,
+          job_class: job_class,
+          job_id: payload["job_id"],
+          provider_job_id: payload["provider_job_id"],
+          arguments: payload["arguments"],
+          enqueued_at: payload["enqueued_at"],
+          read_ct: read_count,
+          msg_id: msg_id
+        }
+        Instrumentation.instrument("pgbus.executor.execute", instrument_payload) do
           job = ::ActiveJob::Base.deserialize(payload)
           Pgbus.logger.debug { "[Pgbus::Executor] running #{tag} job_class=#{job_class}" }
           execute_job(job)
@@ -85,7 +104,17 @@ module Pgbus
         # silently lost control flow — no failed event row, no job_failed
         # notification, uniqueness lock held until VT expired. See issue #126.
         handle_failure(message, queue_name, e, payload: payload)
-        instrument("pgbus.job_failed", queue: queue_name, job_class: payload&.dig("job_class"), error: e.class.name)
+        instrument(
+          "pgbus.job_failed",
+          queue: queue_name,
+          job_class: payload&.dig("job_class"),
+          job_id: payload&.dig("job_id"),
+          provider_job_id: payload&.dig("provider_job_id"),
+          read_ct: message.read_ct.to_i,
+          msg_id: message.msg_id.to_i,
+          error: e.class.name,
+          exception_object: e
+        )
         record_stat(payload, queue_name, "failed", execution_start, message: message)
         Pgbus.logger.debug { "[Pgbus::Executor] failed #{tag} job_class=#{payload&.dig("job_class")} error=#{e.class}" }
         # Don't signal concurrency on transient failure — the job will be retried.

data/lib/pgbus/client/notify_stream.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Client
+    # Fire-and-forget PG NOTIFY for ephemeral stream broadcasts. No PGMQ
+    # queue is created — the payload travels via the Postgres NOTIFY channel
+    # only, matching the channel naming convention that PGMQ's trigger uses:
+    #   pgmq.q_<full_queue_name>.INSERT
+    #
+    # Subscribers already LISTEN on this channel via the Streamer's Listener.
+    # When a subscriber is connected, the StreamEventDispatcher receives the
+    # NOTIFY and fans out the payload. When no subscriber is connected,
+    # the NOTIFY is silently discarded by Postgres — no queue, no storage,
+    # no orphan tables.
+    #
+    # The payload is JSON-serialized into the NOTIFY's optional payload
+    # parameter (max 8000 bytes in Postgres). Broadcasts exceeding this
+    # limit will raise a PG::ProgramLimitExceeded error — callers needing
+    # large payloads should use durable mode (which inserts into PGMQ).
+    module NotifyStream
+      def notify_stream(stream_name, payload)
+        full_name = config.queue_name(stream_name)
+        sanitized = QueueNameValidator.sanitize!(full_name)
+        channel = "pgmq.q_#{sanitized}.INSERT"
+        json = payload.is_a?(String) ? payload : JSON.generate(payload)
+
+        Instrumentation.instrument("pgbus.stream.notify", stream: stream_name, bytes: json.bytesize) do
+          synchronized do
+            @pgmq.with_connection do |conn|
+              conn.exec_params("SELECT pg_notify($1, $2)", [channel, json])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/client.rb

@@ -3,11 +3,13 @@
 require "json"
 require_relative "client/read_after"
 require_relative "client/ensure_stream_queue"
+require_relative "client/notify_stream"
 
 module Pgbus
   class Client
     include ReadAfter
     include EnsureStreamQueue
+    include NotifyStream
 
     attr_reader :pgmq, :config
 

data/lib/pgbus/configuration.rb

@@ -104,7 +104,13 @@ module Pgbus
                   :streams_default_retention, :streams_retention, :streams_heartbeat_interval,
                   :streams_max_connections, :streams_idle_timeout, :streams_listen_health_check_ms,
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
-                  :streams_stats_enabled, :streams_test_mode
+                  :streams_stats_enabled, :streams_test_mode,
+                  :streams_orphan_sweep_interval, :streams_orphan_threshold
+    attr_reader :streams_default_broadcast_mode # rubocop:disable Style/AccessorGrouping
+
+    # AppSignal integration (auto-loaded when ::Appsignal is defined and this is true).
+    # Set to false to opt out without uninstalling the appsignal gem.
+    attr_accessor :appsignal_enabled, :appsignal_probe_enabled
 
     def initialize
       @database_url = nil
@@ -212,6 +218,14 @@ module Pgbus
       # usually want job stats on and stream stats off, or vice versa.
       @streams_stats_enabled = false
       @streams_test_mode = false
+      @streams_default_broadcast_mode = :ephemeral
+      @streams_orphan_sweep_interval = 3600    # 1 hour
+      @streams_orphan_threshold = 86_400       # 24 hours
+
+      # AppSignal: auto-on when the appsignal gem is loaded; probe runs in
+      # the same process, so the operator can disable it independently.
+      @appsignal_enabled = true
+      @appsignal_probe_enabled = true
     end
 
     def queue_name(name)
@@ -255,6 +269,18 @@ module Pgbus
                           end
     end
 
+    VALID_BROADCAST_MODES = %i[ephemeral durable].freeze
+
+    def streams_default_broadcast_mode=(mode)
+      mode = mode.to_sym
+      unless VALID_BROADCAST_MODES.include?(mode)
+        raise ArgumentError,
+              "Invalid streams_default_broadcast_mode: #{mode}. Must be one of: #{VALID_BROADCAST_MODES.join(", ")}"
+      end
+
+      @streams_default_broadcast_mode = mode
+    end
+
     VALID_PGMQ_SCHEMA_MODES = %i[auto extension embedded].freeze
 
     def pgmq_schema_mode=(mode)
@@ -334,6 +360,15 @@ module Pgbus
       end
 
       raise ArgumentError, "streams_retention must be a Hash" unless streams_retention.is_a?(Hash)
+
+      if streams_orphan_sweep_interval && !(streams_orphan_sweep_interval.is_a?(Numeric) && streams_orphan_sweep_interval.positive?)
+        raise ArgumentError, "streams_orphan_sweep_interval must be a positive number or nil to disable"
+      end
+
+      return if streams_orphan_threshold.nil?
+      return if streams_orphan_threshold.is_a?(Numeric) && streams_orphan_threshold.positive?
+
+      raise ArgumentError, "streams_orphan_threshold must be a positive number or nil to disable"
     end
 
     # Set the worker capsule list. Accepts:

data/lib/pgbus/engine.rb

@@ -71,6 +71,21 @@ module Pgbus
       require "pgbus/web/data_source"
     end
 
+    # AppSignal is third-party and entirely optional. We require the
+    # integration only when the host app has the appsignal gem loaded
+    # AND hasn't disabled it via config.appsignal_enabled. AppSignal
+    # itself loads early (it's typically required from config/environment.rb
+    # before Rails finishes booting), so by the time `after_initialize`
+    # fires the constant check is reliable.
+    initializer "pgbus.integrations.appsignal", after: :load_config_initializers do
+      ActiveSupport.on_load(:after_initialize) do
+        next unless defined?(::Appsignal) && Pgbus.configuration.appsignal_enabled
+
+        require "pgbus/integrations/appsignal"
+        Pgbus::Integrations::Appsignal.install!
+      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/event_bus/handler.rb

@@ -30,12 +30,32 @@ module Pgbus
       def process!(message)
         raw = JSON.parse(message.message)
         event = build_event(raw)
+        routing_key = raw.dig("headers", "routing_key") || raw["routing_key"]
 
         return :skipped if self.class.idempotent? && !claim_idempotency?(event.event_id)
 
-        handle(event)
-        instrument("pgbus.event_processed", event_id: event.event_id, handler: self.class.name)
+        instrument_payload = {
+          event_id: event.event_id,
+          handler: self.class.name,
+          routing_key: routing_key,
+          published_at: event.published_at,
+          read_ct: message.read_ct.to_i,
+          msg_id: message.msg_id.to_i
+        }
+        Instrumentation.instrument("pgbus.event_processed", instrument_payload) do
+          handle(event)
+        end
         :handled
+      rescue StandardError => e
+        instrument(
+          "pgbus.event_failed",
+          event_id: event&.event_id,
+          handler: self.class.name,
+          routing_key: routing_key,
+          error: e.class.name,
+          exception_object: e
+        )
+        raise
       end
 
       # Mirrors Pgbus::ActiveJob::Executor#execute_job: wrap the handler

data/lib/pgbus/instrumentation.rb

@@ -7,12 +7,21 @@ module Pgbus
   # automatically when used with the block form of AS::Notifications.instrument.
   #
   # Events emitted:
-  #   pgbus.client.send_message   — single message enqueue
-  #   pgbus.client.send_batch     — batch enqueue
-  #   pgbus.client.read_batch     — batch dequeue
-  #   pgbus.client.read_message   — single message dequeue
-  #   pgbus.executor.execute      — full job execution (deserialize + perform + archive)
-  #   pgbus.serializer.serialize  — job/event serialization
+  #   pgbus.client.send_message    — single message enqueue
+  #   pgbus.client.send_batch      — batch enqueue
+  #   pgbus.client.read_batch      — batch dequeue
+  #   pgbus.client.read_message    — single message dequeue
+  #   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.event_processed        — event handler succeeded
+  #   pgbus.event_failed           — event handler raised; carries :exception_object
+  #   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.serializer.serialize   — job/event serialization
   #   pgbus.serializer.deserialize — job/event deserialization
   #
   module Instrumentation

data/lib/pgbus/integrations/appsignal/dashboards/pgbus_health.json

@@ -0,0 +1,87 @@
+{
+  "title": "Pgbus — Health",
+  "description": "Backlog, dead-letter activity, dead-tuple growth, and MVCC horizon. The 'should I page someone?' dashboard.",
+  "graphs": [
+    {
+      "title": "Queue depth (visible vs total)",
+      "description": "Visible depth excludes messages whose VT hasn't expired. A divergence between the two means workers are slow but the queue isn't growing.",
+      "line_label": "%queue",
+      "format": "number",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_queue_depth", "fields": ["GAUGE"], "tags": [] },
+        { "name": "pgbus_queue_visible_depth", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Oldest message age (seconds)",
+      "description": "Per-queue head-of-line waiting time. If this climbs while queue depth stays flat, a single poison message is stuck in the VT loop.",
+      "line_label": "%queue",
+      "format": "duration",
+      "format_input": "second",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_queue_oldest_message_age_seconds", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "DLQ depth + failed events",
+      "description": "Messages that exceeded max_retries plus the failed-events table. Spikes after a deploy point at a regression.",
+      "format": "number",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_dlq_depth", "fields": ["GAUGE"], "tags": [] },
+        { "name": "pgbus_failed_events_total", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Dead-lettered jobs per minute",
+      "line_label": "%queue %job_class",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_queue_job_count", "fields": ["COUNTER"], "tags": [{ "key": "status", "value": "dead_lettered" }] }
+      ]
+    },
+    {
+      "title": "Active processes",
+      "description": "Workers + dispatcher + scheduler currently heartbeating into pgbus_processes.",
+      "format": "number",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_active_processes", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Dead tuples in queue/archive tables",
+      "description": "If autovacuum can't keep up the index gets bloated and lock acquisition slows. Tune autovacuum_vacuum_scale_factor on the offending tables when this climbs.",
+      "format": "number",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_total_dead_tuples", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Oldest open transaction (seconds)",
+      "description": "MVCC horizon pin. Long-running transactions prevent VACUUM from cleaning the dead tuples above. Anything over 60s is a smell.",
+      "format": "duration",
+      "format_input": "second",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_oldest_transaction_age_seconds", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Worker recycles per minute",
+      "description": "Recycles by reason. Steady max_jobs is healthy; spiking max_memory means you have a leak.",
+      "line_label": "%reason",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_worker_recycled", "fields": ["COUNTER"], "tags": [] }
+      ]
+    }
+  ]
+}

data/lib/pgbus/integrations/appsignal/dashboards/pgbus_streams.json

@@ -0,0 +1,65 @@
+{
+  "title": "Pgbus — Streams",
+  "description": "Real-time SSE pub/sub. Broadcasts, fanout, active connections, and the outbox/recurring scheduler.",
+  "graphs": [
+    {
+      "title": "Stream broadcasts per minute",
+      "line_label": "%stream %deferred",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_stream_broadcast_count", "fields": ["COUNTER"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Active SSE connections",
+      "description": "Estimated from connect/disconnect events in the last 60 minutes. Use as a rough capacity gauge — exact count requires the SSE process telemetry.",
+      "format": "number",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_stream_active_connections", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Average fanout per broadcast",
+      "description": "Mean number of connections that received each broadcast over the last hour.",
+      "format": "number",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_stream_avg_fanout", "fields": ["GAUGE"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Broadcast payload size (bytes)",
+      "description": "Distribution of payload bytes. Use to spot accidentally-streaming-an-entire-page bugs.",
+      "line_label": "%stream",
+      "format": "size",
+      "format_input": "byte",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_stream_broadcast_bytes", "fields": ["MEAN", "P95"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Outbox publishes per minute",
+      "line_label": "%kind",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_outbox_published", "fields": ["COUNTER"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Recurring tasks enqueued per minute",
+      "line_label": "%task",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_recurring_enqueued", "fields": ["COUNTER"], "tags": [] }
+      ]
+    }
+  ]
+}

data/lib/pgbus/integrations/appsignal/dashboards/pgbus_throughput.json

@@ -0,0 +1,81 @@
+{
+  "title": "Pgbus — Throughput & Latency",
+  "description": "Job and event throughput, perform-duration percentiles, and PGMQ send/read counts. Drives the most common 'is the worker keeping up?' question.",
+  "graphs": [
+    {
+      "title": "Jobs processed per minute",
+      "description": "Successful, failed, and dead-lettered jobs. A spike in failed without a spike in processed usually means a deploy regression.",
+      "line_label": "%queue %job_class %status",
+      "format": "number",
+      "format_input": null,
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_queue_job_count", "fields": ["COUNTER"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Job perform duration (ms)",
+      "description": "Distribution of how long perform_now takes per job class. P95 and P99 are the lines to watch.",
+      "line_label": "%job_class",
+      "format": "duration",
+      "format_input": "millisecond",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_job_duration_ms", "fields": ["MEAN", "P95", "P99"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Events processed per minute",
+      "description": "Event-bus handler invocations grouped by routing key.",
+      "line_label": "%routing_key %handler %status",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_event_count", "fields": ["COUNTER"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Event handler duration (ms)",
+      "line_label": "%handler",
+      "format": "duration",
+      "format_input": "millisecond",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_event_duration_ms", "fields": ["MEAN", "P95", "P99"], "tags": [] }
+      ]
+    },
+    {
+      "title": "PGMQ messages sent (per minute)",
+      "line_label": "%queue",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_messages_sent", "fields": ["COUNTER"], "tags": [] }
+      ]
+    },
+    {
+      "title": "Send duration (ms)",
+      "line_label": "%queue",
+      "format": "duration",
+      "format_input": "millisecond",
+      "kind": "timeseries",
+      "metrics": [
+        { "name": "pgbus_send_duration_ms", "fields": ["MEAN", "P95", "P99"], "tags": [] }
+      ]
+    },
+    {
+      "title": "PGMQ messages read (per minute)",
+      "description": "Messages fetched from queues by workers. Compare against 'sent' to spot backlog growth.",
+      "line_label": "%queue",
+      "format": "number",
+      "kind": "timeseries",
+      "draw_null_as_zero": true,
+      "metrics": [
+        { "name": "pgbus_messages_read", "fields": ["COUNTER"], "tags": [] }
+      ]
+    }
+  ]
+}