pgbus 0.7.8 → 0.7.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48e02fc16de64a9ccec20b8b0d917e154e17dc2082c1e3933b80da1bdc2f0c2a
-  data.tar.gz: 811db2dfcb4c4271296d9125754af3865b117ebc8b45d3194bc4314cc43ffaba
+  metadata.gz: d7661d7d684ac911e36b15267b4b6135081fa3bd9ca0a795cfceae7e9977304a
+  data.tar.gz: 7cdb802918724dafa634925a99c48c9a0ee154356ec807e69ad6ec86cb48f9be
 SHA512:
-  metadata.gz: 2b41cd760d469af41c4e0ef0d9bfaffd3cb17ff81b38dbeb250605d78c737708f54ee43519fe25afeda83a5e15177a14e89e48d27471ae39ad5c79420d791e21
-  data.tar.gz: 50f209ed7b74e18c1bf927ca73fe80286c9a4333642af4f32e579bd6f9e40158007c07a39dfa6a3fc2082fd9ad1663f3e9b109ebd7021485f931a615ad9baabb
+  metadata.gz: 917889d47343e7c8775f6be1c9bc9d72b7ca8a26de356a9434ba1470f0f4f345215e9f016f9bba74b78007c72668254b92715944574fc056b20ceb1af92ebaac
+  data.tar.gz: 011533444eec2c09e29de3938d84e6fc06efd87c82621efcccf92008d88b3a3ac76464619c959617d022e076da4bed5ca03b50f3b5997e7d81ec9b52ccce90c3

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/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/configuration.rb

@@ -106,6 +106,10 @@ module Pgbus
                   :streams_write_deadline_ms, :streams_falcon_streaming_body,
                   :streams_stats_enabled, :streams_test_mode
 
+    # 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
       @connection_params = nil
@@ -212,6 +216,11 @@ module Pgbus
       # usually want job stats on and stream stats off, or vice versa.
       @streams_stats_enabled = false
       @streams_test_mode = false
+
+      # 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)

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": [] }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # Minutely probe that pushes pgbus-wide gauges into AppSignal.
+      #
+      # All readings come from Pgbus::Web::DataSource so the probe doesn't
+      # duplicate query logic. DataSource is built to be resilient — every
+      # method rescues StandardError and returns a safe default — but we
+      # still wrap each section in our own rescue so a probe iteration
+      # never raises out into the AppSignal probe runner.
+      module Probe
+        METRIC_PREFIX = "pgbus_"
+        private_constant :METRIC_PREFIX
+
+        class << self
+          def install! # rubocop:disable Naming/PredicateMethod
+            return false if @installed
+
+            ::Appsignal::Probes.register :pgbus, new_probe_instance
+            @installed = true
+            true
+          end
+
+          def installed?
+            @installed == true
+          end
+
+          def reset!
+            ::Appsignal::Probes.unregister(:pgbus) if defined?(::Appsignal::Probes) &&
+                                                      ::Appsignal::Probes.respond_to?(:unregister)
+            @installed = false
+          end
+
+          # Visible for testing — returns a fresh runnable probe.
+          def new_probe_instance
+            Runner.new
+          end
+        end
+
+        # The actual probe object; AppSignal calls #call once per minute.
+        class Runner
+          def initialize(data_source: nil)
+            @data_source = data_source
+          end
+
+          def call
+            return unless data_source
+
+            track_queues
+            track_processes
+            track_summary
+            track_streams
+          end
+
+          private
+
+          def data_source
+            @data_source ||=
+              (::Pgbus::Web::DataSource.new if defined?(::Pgbus::Web::DataSource))
+          end
+
+          def track_queues
+            data_source.queues_with_metrics.each do |q|
+              tags = { queue: q[:name] }
+              gauge "queue_depth", q[:queue_length], tags
+              gauge "queue_visible_depth", q[:queue_visible_length], tags
+              gauge "queue_paused", q[:paused] ? 1 : 0, tags
+              age = q[:oldest_msg_age_sec]
+              gauge "queue_oldest_message_age_seconds", age, tags if age
+            end
+          rescue StandardError => e
+            log_failure("queue metrics", e)
+          end
+
+          def track_processes
+            gauge "active_processes", data_source.processes.count
+          rescue StandardError => e
+            log_failure("process metrics", e)
+          end
+
+          def track_summary
+            stats = data_source.summary_stats
+            gauge "total_queues", stats[:total_queues]
+            gauge "total_depth", stats[:total_depth]
+            gauge "total_visible", stats[:total_visible]
+            gauge "dlq_depth", stats[:dlq_depth]
+            gauge "failed_events_total", stats[:failed_count]
+            gauge "throughput_rate", stats[:throughput_rate]
+            gauge "total_dead_tuples", stats[:total_dead_tuples]
+            gauge "tables_needing_vacuum", stats[:tables_needing_vacuum]
+            gauge "oldest_transaction_age_seconds", stats[:oldest_transaction_age_sec]
+          rescue StandardError => e
+            log_failure("summary metrics", e)
+          end
+
+          def track_streams
+            return unless data_source.respond_to?(:stream_stats_available?) &&
+                          data_source.stream_stats_available?
+
+            summary = data_source.stream_stats_summary
+            gauge "stream_broadcasts_60m", summary[:broadcasts]
+            gauge "stream_connects_60m", summary[:connects]
+            gauge "stream_disconnects_60m", summary[:disconnects]
+            gauge "stream_active_connections", summary[:active_estimate]
+            gauge "stream_avg_fanout", summary[:avg_fanout]
+            gauge "stream_avg_broadcast_ms", summary[:avg_broadcast_ms]
+          rescue StandardError => e
+            log_failure("stream metrics", e)
+          end
+
+          def gauge(key, value, tags = {})
+            return if value.nil?
+
+            ::Appsignal.set_gauge("#{METRIC_PREFIX}#{key}", value, tags)
+          end
+
+          def log_failure(label, error)
+            Pgbus.logger.debug do
+              "[Pgbus::AppSignal::Probe] #{label} failed: #{error.class}: #{error.message}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # Translates Pgbus::Instrumentation events into AppSignal transactions
+      # and custom metrics.
+      #
+      # Job and event-handler events open a BACKGROUND_JOB transaction so they
+      # appear under AppSignal's "Performance > Background jobs" view, with
+      # action `<JobClass>#perform` or `<HandlerClass>#handle`. All other
+      # events are reported as counters or distributions only.
+      #
+      # All metric names are prefixed `pgbus_`. Tag keys avoid high-cardinality
+      # values (no msg_id, no event_id) so AppSignal's metric storage stays
+      # efficient.
+      module Subscriber
+        BACKGROUND_JOB = "background_job"
+        METRIC_PREFIX = "pgbus_"
+        private_constant :BACKGROUND_JOB, :METRIC_PREFIX
+
+        # Tracked so we can detach in reset! (used by specs).
+        @subscriptions = []
+
+        class << self
+          def install!
+            return false if @installed
+
+            @subscriptions = [
+              subscribe("pgbus.executor.execute") { |event| on_executor_execute(event) },
+              subscribe("pgbus.job_completed") { |event| on_job_completed(event) },
+              subscribe("pgbus.job_failed") { |event| on_job_failed(event) },
+              subscribe("pgbus.job_dead_lettered") { |event| on_job_dead_lettered(event) },
+              subscribe("pgbus.event_processed") { |event| on_event_processed(event) },
+              subscribe("pgbus.event_failed") { |event| on_event_failed(event) },
+              subscribe("pgbus.client.send_message") { |event| on_send_message(event) },
+              subscribe("pgbus.client.send_batch") { |event| on_send_batch(event) },
+              subscribe("pgbus.client.read_batch") { |event| on_read_batch(event) },
+              subscribe("pgbus.stream.broadcast") { |event| on_stream_broadcast(event) },
+              subscribe("pgbus.outbox.publish") { |event| on_outbox_publish(event) },
+              subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
+              subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) }
+            ]
+            @installed = true
+          end
+
+          def installed?
+            @installed == true
+          end
+
+          def reset!
+            @subscriptions&.each { |s| ActiveSupport::Notifications.unsubscribe(s) }
+            @subscriptions = []
+            @installed = false
+          end
+
+          private
+
+          def subscribe(name, &block)
+            # silence rubocop unused
+            ActiveSupport::Notifications.subscribe(name) do |*args|
+              event = ActiveSupport::Notifications::Event.new(*args)
+              safely { block.call(event) }
+            end
+          end
+
+          # Errors in the subscriber must never affect the producer thread.
+          # AppSignal can be misconfigured, the agent can be down, etc. — log
+          # and move on.
+          def safely
+            yield
+          rescue StandardError => e
+            Pgbus.logger.warn do
+              "[Pgbus::AppSignal] subscriber error: #{e.class}: #{e.message}"
+            end
+          end
+
+          # ── Job execution ───────────────────────────────────────────────
+
+          def on_executor_execute(event)
+            payload = event.payload
+            transaction = ::Appsignal::Transaction.create(BACKGROUND_JOB)
+            transaction.set_action_if_nil("#{payload[:job_class] || "UnknownJob"}#perform")
+            apply_queue_start(transaction, payload[:enqueued_at])
+            transaction.add_tags(job_tags(payload))
+            transaction.add_params_if_nil { { arguments: payload[:arguments] } }
+            ::Appsignal.add_distribution_value(
+              "#{METRIC_PREFIX}job_duration_ms",
+              event.duration,
+              { queue: payload[:queue], job_class: payload[:job_class] }
+            )
+          ensure
+            ::Appsignal::Transaction.complete_current!
+          end
+
+          def on_job_completed(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}queue_job_count",
+              1,
+              { queue: payload[:queue], job_class: payload[:job_class], status: "processed" }
+            )
+          end
+
+          def on_job_failed(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}queue_job_count",
+              1,
+              { queue: payload[:queue], job_class: payload[:job_class], status: "failed" }
+            )
+            err = payload[:exception_object]
+            ::Appsignal.set_error(err) if err && ::Appsignal.respond_to?(:set_error)
+          end
+
+          def on_job_dead_lettered(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}queue_job_count",
+              1,
+              { queue: payload[:queue], job_class: payload[:job_class], status: "dead_lettered" }
+            )
+          end
+
+          # ── Event handler ───────────────────────────────────────────────
+
+          def on_event_processed(event)
+            payload = event.payload
+            transaction = ::Appsignal::Transaction.create(BACKGROUND_JOB)
+            transaction.set_action_if_nil("#{payload[:handler] || "UnknownHandler"}#handle")
+            apply_queue_start(transaction, payload[:published_at])
+            transaction.add_tags(handler_tags(payload))
+            ::Appsignal.add_distribution_value(
+              "#{METRIC_PREFIX}event_duration_ms",
+              event.duration,
+              { handler: payload[:handler], routing_key: payload[:routing_key] }
+            )
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}event_count",
+              1,
+              { handler: payload[:handler], routing_key: payload[:routing_key], status: "processed" }
+            )
+          ensure
+            ::Appsignal::Transaction.complete_current!
+          end
+
+          def on_event_failed(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}event_count",
+              1,
+              { handler: payload[:handler], routing_key: payload[:routing_key], status: "failed" }
+            )
+            err = payload[:exception_object]
+            ::Appsignal.set_error(err) if err && ::Appsignal.respond_to?(:set_error)
+          end
+
+          # ── Client (PGMQ wrapper) ───────────────────────────────────────
+
+          def on_send_message(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}messages_sent",
+              1,
+              { queue: payload[:queue] }
+            )
+            ::Appsignal.add_distribution_value(
+              "#{METRIC_PREFIX}send_duration_ms",
+              event.duration,
+              { queue: payload[:queue] }
+            )
+          end
+
+          def on_send_batch(event)
+            payload = event.payload
+            count = payload[:count] || payload[:batch_size] || 1
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}messages_sent",
+              count,
+              { queue: payload[:queue] }
+            )
+            ::Appsignal.add_distribution_value(
+              "#{METRIC_PREFIX}send_batch_duration_ms",
+              event.duration,
+              { queue: payload[:queue] }
+            )
+          end
+
+          def on_read_batch(event)
+            payload = event.payload
+            count = payload[:count] || payload[:fetched] || 0
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}messages_read",
+              count,
+              { queue: payload[:queue] }
+            )
+          end
+
+          # ── Streams ─────────────────────────────────────────────────────
+
+          def on_stream_broadcast(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}stream_broadcast_count",
+              1,
+              { stream: payload[:stream], deferred: payload[:deferred] ? "true" : "false" }
+            )
+            return unless payload[:bytes]
+
+            ::Appsignal.add_distribution_value(
+              "#{METRIC_PREFIX}stream_broadcast_bytes",
+              payload[:bytes],
+              { stream: payload[:stream] }
+            )
+          end
+
+          # ── Outbox ──────────────────────────────────────────────────────
+
+          def on_outbox_publish(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}outbox_published",
+              1,
+              { kind: payload[:kind] || "job" }
+            )
+            ::Appsignal.add_distribution_value(
+              "#{METRIC_PREFIX}outbox_publish_duration_ms",
+              event.duration,
+              { kind: payload[:kind] || "job" }
+            )
+          end
+
+          # ── Recurring scheduler ─────────────────────────────────────────
+
+          def on_recurring_enqueue(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}recurring_enqueued",
+              1,
+              { task: payload[:task], class_name: payload[:class_name] }
+            )
+          end
+
+          # ── Worker lifecycle ────────────────────────────────────────────
+
+          def on_worker_recycle(event)
+            payload = event.payload
+            ::Appsignal.increment_counter(
+              "#{METRIC_PREFIX}worker_recycled",
+              1,
+              { reason: payload[:reason] }
+            )
+          end
+
+          # ── Helpers ─────────────────────────────────────────────────────
+
+          # AppSignal expects queue-start as Unix epoch milliseconds. Pgbus
+          # carries it as either an ISO-8601 String or a Time — both happen
+          # in practice (executor passes the JSON string, handler passes a
+          # parsed Time).
+          def apply_queue_start(transaction, value)
+            return unless value
+
+            millis =
+              case value
+              when Time
+                (value.to_f * 1_000).to_i
+              when String
+                (Time.parse(value).to_f * 1_000).to_i
+              when Numeric
+                value.to_i
+              end
+            transaction.set_queue_start(millis) if millis
+          rescue ArgumentError
+            # Unparseable timestamp — skip rather than blow up.
+          end
+
+          def job_tags(payload)
+            tags = {
+              "queue" => payload[:queue],
+              "job_class" => payload[:job_class],
+              "attempts" => payload[:read_ct]
+            }
+            tags["active_job_id"] = payload[:job_id] if payload[:job_id]
+            tags["provider_job_id"] = payload[:provider_job_id] if payload[:provider_job_id]
+            tags["request_id"] = payload[:provider_job_id] || payload[:job_id]
+            tags.compact
+          end
+
+          def handler_tags(payload)
+            {
+              "handler" => payload[:handler],
+              "routing_key" => payload[:routing_key],
+              "attempts" => payload[:read_ct]
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/integrations/appsignal.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "pgbus/integrations/appsignal/subscriber"
+require "pgbus/integrations/appsignal/probe"
+
+module Pgbus
+  module Integrations
+    # AppSignal integration for pgbus.
+    #
+    # Loaded automatically by Pgbus::Engine when the appsignal gem is present
+    # and config.appsignal_enabled is true (default). To opt out:
+    #
+    #   Pgbus.configure do |c|
+    #     c.appsignal_enabled = false
+    #   end
+    #
+    # The integration:
+    #   * Subscribes to pgbus.* ActiveSupport::Notifications and translates
+    #     them into AppSignal background-job transactions and metrics.
+    #   * Registers a minutely probe that reports queue depth, DLQ size,
+    #     dead-tuple counts, MVCC horizon age, and stream stats from
+    #     Pgbus::Web::DataSource.
+    #
+    # All metric names are prefixed `pgbus_` so they group cleanly in
+    # AppSignal's custom-metrics view.
+    module Appsignal
+      module_function
+
+      def install! # rubocop:disable Naming/PredicateMethod
+        return false unless defined?(::Appsignal)
+        return false if @installed
+
+        Subscriber.install!
+        Probe.install! if Pgbus.configuration.appsignal_probe_enabled
+        @installed = true
+        Pgbus.logger.info { "[Pgbus] AppSignal integration installed" }
+        true
+      end
+
+      def installed?
+        @installed == true
+      end
+
+      # Test hook: tear everything down so a fresh install! can run.
+      def reset!
+        Subscriber.reset! if defined?(Subscriber)
+        Probe.reset! if defined?(Probe)
+        @installed = false
+      end
+    end
+  end
+end

data/lib/pgbus/outbox.rb

@@ -5,22 +5,26 @@ module Pgbus
     module_function
 
     def publish(queue_name, payload, headers: nil, priority: nil, delay: 0)
-      OutboxEntry.create!(
-        queue_name: queue_name,
-        payload: payload,
-        headers: headers,
-        priority: priority || Pgbus.configuration.default_priority,
-        delay: delay
-      )
+      Instrumentation.instrument("pgbus.outbox.publish", queue: queue_name, kind: :job) do
+        OutboxEntry.create!(
+          queue_name: queue_name,
+          payload: payload,
+          headers: headers,
+          priority: priority || Pgbus.configuration.default_priority,
+          delay: delay
+        )
+      end
     end
 
     def publish_event(routing_key, payload, headers: nil)
-      event_data = EventBus::Publisher.build_event_data(payload)
-      OutboxEntry.create!(
-        routing_key: routing_key,
-        payload: event_data,
-        headers: headers
-      )
+      Instrumentation.instrument("pgbus.outbox.publish", routing_key: routing_key, kind: :event) do
+        event_data = EventBus::Publisher.build_event_data(payload)
+        OutboxEntry.create!(
+          routing_key: routing_key,
+          payload: event_data,
+          headers: headers
+        )
+      end
     end
 
     def flush!

data/lib/pgbus/process/worker.rb

@@ -302,15 +302,33 @@ module Pgbus
       end
 
       def check_recycle
-        return unless @lifecycle.running? && recycle_needed?
+        return unless @lifecycle.running?
+
+        reason = recycle_reason
+        return unless reason
 
         Pgbus.stopping = true
         @lifecycle.transition_to(:draining)
+        Pgbus::Instrumentation.instrument(
+          "pgbus.worker.recycle",
+          reason: reason,
+          jobs_processed: @jobs_processed.value,
+          memory_mb: current_memory_mb,
+          lifetime_seconds: monotonic_now - @started_at_monotonic
+        )
         @wake_signal.notify!
       end
 
+      def recycle_reason
+        return :max_jobs if exceeded_max_jobs?
+        return :max_memory if exceeded_max_memory?
+        return :max_lifetime if exceeded_max_lifetime?
+
+        nil
+      end
+
       def recycle_needed?
-        exceeded_max_jobs? || exceeded_max_memory? || exceeded_max_lifetime?
+        !recycle_reason.nil?
       end
 
       def exceeded_max_jobs?

data/lib/pgbus/recurring/scheduler.rb

@@ -41,8 +41,16 @@ module Pgbus
 
       def tick(now)
         schedule.due_tasks(now).each do |task, run_at|
-          schedule.enqueue_task(task, run_at: run_at)
-          @last_runs[task.key] = now
+          Pgbus::Instrumentation.instrument(
+            "pgbus.recurring.enqueue",
+            task: task.key,
+            class_name: task.class_name,
+            queue: task.queue_name,
+            run_at: run_at
+          ) do
+            schedule.enqueue_task(task, run_at: run_at)
+            @last_runs[task.key] = now
+          end
         rescue StandardError => e
           Pgbus.logger.error do
             "[Pgbus] Error scheduling recurring task #{task.key}: #{e.class}: #{e.message}"

data/lib/pgbus/streams.rb

@@ -73,11 +73,19 @@ module Pgbus
         wrapped = { "html" => payload.to_s }
         wrapped["visible_to"] = visible_to.to_s if visible_to
         transaction = current_open_transaction
-        if transaction
-          transaction.after_commit { @client.send_message(@name, wrapped) }
-          nil
-        else
-          @client.send_message(@name, wrapped)
+        instrument_payload = {
+          stream: @name,
+          visible_to: visible_to,
+          deferred: !transaction.nil?,
+          bytes: wrapped["html"].bytesize
+        }
+        Instrumentation.instrument("pgbus.stream.broadcast", instrument_payload) do
+          if transaction
+            transaction.after_commit { @client.send_message(@name, wrapped) }
+            nil
+          else
+            @client.send_message(@name, wrapped)
+          end
         end
       end
 

data/lib/pgbus/version.rb

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

data/lib/pgbus.rb

@@ -40,6 +40,10 @@ module Pgbus
         loader.ignore("#{__dir__}/generators")
         loader.ignore("#{__dir__}/active_job")
         loader.ignore("#{__dir__}/pgbus/testing")
+        # Vendor integrations are loaded conditionally (when the vendor gem
+        # is present) by lib/pgbus/engine.rb. Keeping them out of Zeitwerk
+        # means we don't reference vendor constants at autoload time.
+        loader.ignore("#{__dir__}/pgbus/integrations")
         # lib/puma/plugin/pgbus_streams.rb is a Puma plugin — it's required
         # explicitly by the user from config/puma.rb via `plugin :pgbus_streams`.
         # Without this ignore, Zeitwerk scans lib/puma/ under the pgbus loader

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.7.8
+  version: 0.7.9
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -273,6 +273,12 @@ files:
 - lib/pgbus/generators/database_target_detector.rb
 - lib/pgbus/generators/migration_detector.rb
 - lib/pgbus/instrumentation.rb
+- lib/pgbus/integrations/appsignal.rb
+- lib/pgbus/integrations/appsignal/dashboards/pgbus_health.json
+- lib/pgbus/integrations/appsignal/dashboards/pgbus_streams.json
+- lib/pgbus/integrations/appsignal/dashboards/pgbus_throughput.json
+- lib/pgbus/integrations/appsignal/probe.rb
+- lib/pgbus/integrations/appsignal/subscriber.rb
 - lib/pgbus/log_formatter.rb
 - lib/pgbus/outbox.rb
 - lib/pgbus/outbox/poller.rb