pgbus 0.19.3 → 0.19.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd3bef8697d00eb6c47ce8c5d96c0c7780f8905015db0f3ffdfd963c23685c05
-  data.tar.gz: 62484196117af7568316b85c3e90cda2c36a1ecb0d65de651b586593abb27fa8
+  metadata.gz: d5167e34401cdf1e4d452969bd1ebebd569e145bc559f62ea7d3913156e02ccf
+  data.tar.gz: 2f47167e2c3abc31d02482117db5cf0cf3d0c8b2e3413351864493782033503b
 SHA512:
-  metadata.gz: 4319f21f8a8bf47371677468b81c4c99d44c0e00f59f62014d910a1912208cbd58d0410f6177d6d393f6ec0336a455e36351e4cd8ebb31d1dce242afca155b6a
-  data.tar.gz: b0eb5972c1a2a7d0a2e6a8606b8e58911df19aeb759b817d1b96beb576d5785dd0851ebc9457a60546d7cf65ee76a58aac13f342ef49b6d744361bc16d15dfdd
+  metadata.gz: 936892796bbb42eb143e61bb6ae1e9f3ac4f1056127ddd96d1dd59638ba87f2c01b4c5e6fa26fa6a3b32e8d19b359070dceba20afd4ce91dd76edbbb98062efa
+  data.tar.gz: 30cfff6ead30c7b35d3454c56b41793b9f984c1283073c414e1e83b357325d5ab930160ecfa035b3cb9a6f2e1f1d832172d7684f8cdb467aa0354daa84273eaa

data/CHANGELOG.md

@@ -13,6 +13,8 @@
 
 ### Fixed
 
+- **`Pgbus.batch` inside a database transaction counts the jobs that enqueue after commit, and waits for them.** A job with Active Job's `enqueue_after_transaction_commit` added inside an open transaction is enqueued only when the transaction commits, after the block has returned and its thread tag is gone. The batch counted nothing, finished empty when the block returned and sent its `on_complete` (and `on_success`) callback before any member job existed; the jobs then ran outside the batch. Even a rolled-back transaction sent the callback. Now `b.add`, `batch.add` and `perform_later` record the batch on the job instance (`enqueue_batch_id`, transient: never serialized, cleared once the enqueue is done), the adapter tags and counts each job from it at the real enqueue, and the batch starts processing (or an open batch re-checks for finish) through `ActiveRecord.after_all_transactions_commit`, after every deferred enqueue has counted itself in. On a rollback nothing is sent, no callback fires and the batch row is rolled back with the transaction. A deferred first attempt discarded at enqueue (uniqueness or concurrency `on_conflict: :discard`) is uncounted as before, and a `retry_on` re-enqueue still re-joins without a second count. Outside a transaction nothing changes, including the queries a batch runs. Known gaps: a bare `ActiveJob.perform_all_later` inside the block does not record the batch (use `b.add`); a `batch.add` inside a transaction raises `AlreadyFinished` when the transaction commits, not at the `add` line, if the batch finished in the meantime; a batch row on a separate `connects_to` database is not part of the caller's transaction. Refs #553.
+- **AppSignal: the job's transaction is current while the job runs, and carries its error (issue #552).** The AppSignal subscriber opened the `background_job` transaction from a finish-only notification callback, after the job had run, and completed it in the same call. `pgbus.job_failed` fired after that, so its `Appsignal.set_error` found no current transaction and reported nothing: a job whose class no longer exists (`ActiveJob::UnknownJobClassError`) or whose arguments cannot be deserialized retried and dead-lettered with nothing in AppSignal but the counters, an error raised inside `perform` arrived only as an action-less sample from the Rails error reporter, and job code calling `Appsignal.add_tags`, `set_error` or `instrument` attached to nothing. Event handlers had the same shape. The subscriber now listens to `pgbus.executor.execute` and `pgbus.event_processed` on both sides (`start` and `finish`): the `<JobClass>#perform` / `<Handler>#handle` transaction opens before the job or handler runs, is current for the whole execution (deserialize, perform, archive), records the exception the execution raised and completes at the end, so an error raised inside `perform` lands on it once, with its duration and queue start. A failure raised before that span opens (a message body that is not JSON, an event that cannot be built, a dead-letter move that failed) is reported from `pgbus.job_failed` / `pgbus.event_failed` on a transaction of its own with the same action and tags; an error the span already recorded is not reported twice. A transaction that is already current is reused and left to its owner to complete, as AppSignal's own ActiveJob hook does, and a span inside another of its kind restores the outer one when it finishes. Like that hook, the span records any exception that ends the execution, so a job interrupted between `perform` and the archive (an `Async::Stop` on shutdown under `execution_mode: :async`, an `Interrupt`) now shows up as an error sample too. The counters and the `pgbus_job_duration_ms` / `pgbus_event_duration_ms` distributions are recorded as before, once per execution. Refs #552.
 - **The dashboard's confirm and alert dialogs open centred again (issue #529).** The engine's stylesheet is built with Tailwind 4, whose preflight sets `margin: 0` on every element. A modal `<dialog>` keeps the browser's `inset: 0` but lost the `margin: auto` that centres it inside that inset, so every Pause, Purge and Delete confirmation opened in the top-left corner. Both dialogs now carry `m-auto`. The confirm dialog's Confirm button was white on yellow (1.91:1). It now uses the dark-on-yellow warning colours (`bg-yellow-400 text-yellow-950`), and the axe gate audits an open confirm dialog in light and dark mode. Refs #529.
 
 ## [0.19.0] - 2026-10-16

data/README.md

@@ -917,13 +917,19 @@ By default, Pgbus logs caught exceptions and continues. To route them to your AP
 ```ruby
 Pgbus.configure do |c|
   c.error_reporters << ->(ex, ctx) {
-    Appsignal.set_error(ex) { |t| t.set_tags(ctx) }
+    Appsignal.report_error(ex) do |t|
+      t.set_namespace("background_job") if ctx[:job_class]
+      t.set_action("#{ctx[:job_class]}#perform") if ctx[:job_class]
+      t.add_tags(ctx)
+    end
   }
 end
 ```
 
 Each reporter receives `(exception, context_hash)`. The context hash includes keys like `action`, `queue`, `job_class`, and `msg_id` depending on the call site. Reporters that accept a third argument also receive the Pgbus configuration object.
 
+Use `Appsignal.report_error`, not `Appsignal.set_error`: a reporter may run from a rescue where no AppSignal transaction is current, and there `set_error` does nothing. `report_error` works whether a transaction is current or not. With the [AppSignal integration](#appsignal-integration) installed, job and handler errors already reach AppSignal on their own transaction, so a reporter like the one above is only needed for the other rescue paths. It does not report those job errors a second time: AppSignal marks an exception once it is on a transaction (`Transaction#add_error`) and does not add a marked exception to another one.
+
 Reporters are wired into all critical rescue paths: job execution failures, worker fetch/process errors, dispatcher maintenance, supervisor fork failures, circuit breaker trips, outbox publish errors, and failed event recording. Non-critical paths (dashboard queries, stat recording) remain log-only.
 
 `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.
@@ -951,7 +957,7 @@ If you upgraded from 0.9.x and previously did `rescue ArgumentError` around `Pgb
 
 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.
+- **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. The transaction is current for the whole execution (deserialize, `perform`/`handle`, archive), so `Appsignal.add_tags`, `Appsignal.set_error` and `Appsignal.instrument` called from job or handler code attach to it, and the error an execution raised is reported on it, also when it was raised before `perform` (an unknown job class, arguments that cannot be deserialized).
 - **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.
 

data/lib/pgbus/active_job/adapter.rb

@@ -11,14 +11,16 @@ module Pgbus
         payload_hash = Concurrency.inject_metadata(active_job, payload_hash)
         payload_hash = Uniqueness.inject_metadata(active_job, payload_hash)
         payload_hash = FairShare.inject_metadata(active_job, payload_hash)
-        payload_hash = inject_batch_metadata(payload_hash, active_job: active_job)
+        payload_hash = inject_batch_metadata(payload_hash, active_job)
 
         if uniqueness_rejected?(active_job, payload_hash, queue: queue)
-          uncount_batch_job(payload_hash)
+          uncount_batch_job(payload_hash, active_job)
           return active_job
         end
 
         enqueue_with_concurrency(active_job, queue, payload_hash)
+      ensure
+        forget_enqueue_batch_id(active_job)
       end
 
       def enqueue_at(active_job, timestamp)
@@ -27,15 +29,17 @@ module Pgbus
         payload_hash = Concurrency.inject_metadata(active_job, payload_hash)
         payload_hash = Uniqueness.inject_metadata(active_job, payload_hash)
         payload_hash = FairShare.inject_metadata(active_job, payload_hash)
-        payload_hash = inject_batch_metadata(payload_hash, active_job: active_job)
+        payload_hash = inject_batch_metadata(payload_hash, active_job)
         delay = [(timestamp - Time.current.to_f).ceil, 0].max
 
         if uniqueness_rejected?(active_job, payload_hash, queue: queue)
-          uncount_batch_job(payload_hash)
+          uncount_batch_job(payload_hash, active_job)
           return active_job
         end
 
         enqueue_with_concurrency(active_job, queue, payload_hash, delay: delay)
+      ensure
+        forget_enqueue_batch_id(active_job)
       end
 
       def enqueue_all(active_jobs)
@@ -114,7 +118,7 @@ module Pgbus
         Batch.backfill_execution(payload_hash, msg_id, physical_queue(queue, priority)) if msg_id
         # A retry re-enqueue that is now live (sent, or parked as a blocked
         # execution) must stop the original attempt from signalling completion.
-        Batch.note_retry_reenqueued(payload_hash["job_id"]) if (msg_id || blocked) && retry_retagged?(payload_hash)
+        Batch.note_retry_reenqueued(payload_hash["job_id"]) if (msg_id || blocked) && retry_retagged?(payload_hash, active_job)
         uniqueness_key = Thread.current[:pgbus_acquired_uniqueness_key]
         UniquenessKey.clear_bind_stamp!(uniqueness_key) if uniqueness_key
         Thread.current[:pgbus_acquired_uniqueness_key] = nil
@@ -131,7 +135,7 @@ module Pgbus
         # database error from the slot upsert or the park is not ambiguous.
         if msg_id.nil? && !(sending && ambiguous_delivery?(e))
           rollback_acquired_uniqueness_lock
-          uncount_batch_job(payload_hash)
+          uncount_batch_job(payload_hash, active_job)
         else
           # Drop the thread-local so a later discard on this thread cannot
           # release that job's uniqueness lock, but do not DELETE the
@@ -210,7 +214,7 @@ module Pgbus
           # acquired earlier in this enqueue (no executor will release it), and
           # uncount it from its batch so completion is not waited on forever.
           rollback_acquired_uniqueness_lock
-          uncount_batch_job(payload_hash)
+          uncount_batch_job(payload_hash, active_job)
         when :raise
           raise ConcurrencyLimitExceeded, "Concurrency limit reached for key: #{key}"
         end
@@ -283,25 +287,39 @@ module Pgbus
 
       # Reverses inject_batch_metadata for a job discarded at enqueue time
       # (uniqueness duplicate or concurrency :discard conflict): the message is
-      # never sent, so it can never signal completion. Only applies while the
-      # tagging batch's block is still active on this thread.
-      def uncount_batch_job(payload_hash)
+      # never sent, so it can never signal completion. Only applies to a job
+      # counted in as a member (see #member_batch_id).
+      def uncount_batch_job(payload_hash, active_job)
         batch_id = payload_hash[Batch::METADATA_KEY]
         return unless batch_id
 
-        if batch_id == Thread.current[:pgbus_batch_id]
+        if batch_id == member_batch_id(active_job)
           Batch.untrack_enqueue(payload_hash)
-        elsif retry_retagged?(payload_hash)
+        elsif retry_retagged?(payload_hash, active_job)
           # The retry never became live; the original attempt's row and its
           # normal completion signal stand.
           Batch.forget_retry_reenqueued(payload_hash["job_id"])
         end
       end
 
-      # Tagged for a batch while no Batch#enqueue block is active on this
-      # thread — only a retry_on re-enqueue gets there (issue #424).
-      def retry_retagged?(payload_hash)
-        payload_hash[Batch::METADATA_KEY] && Thread.current[:pgbus_batch_id].nil?
+      # Tagged for a batch the job was neither added to nor enqueued inside
+      # the block of — only a retry_on re-enqueue gets there (issue #424).
+      def retry_retagged?(payload_hash, active_job)
+        payload_hash[Batch::METADATA_KEY] && member_batch_id(active_job).nil?
+      end
+
+      # The batch a job joins as a new member: the one it was added to, kept
+      # on the instance so it survives an enqueue deferred to after commit
+      # (issue #553), else the Batch#enqueue block active on this thread. The
+      # instance wins: a deferred enqueue can run while another batch's
+      # block is open on the committing thread.
+      def member_batch_id(active_job)
+        (active_job.enqueue_batch_id if active_job.respond_to?(:enqueue_batch_id)) ||
+          Thread.current[:pgbus_batch_id]
+      end
+
+      def forget_enqueue_batch_id(active_job)
+        active_job.enqueue_batch_id = nil if active_job.respond_to?(:enqueue_batch_id=)
       end
 
       # A retry_on re-enqueue of a job that is already a batch member: same
@@ -316,18 +334,17 @@ module Pgbus
         active_job.batch_id
       end
 
-      # Tag the payload with the active batch and count it in (guarded
-      # increment + execution row, before the send — Batch.track_enqueue). Pass
-      # track: false to only tag, when the caller counts a bulk once.
-      def inject_batch_metadata(payload_hash, active_job: nil, track: true)
-        batch_id = Thread.current[:pgbus_batch_id]
+      # Tag the payload with the job's batch and count it in (guarded
+      # increment + execution row, before the send — Batch.track_enqueue).
+      def inject_batch_metadata(payload_hash, active_job)
+        batch_id = member_batch_id(active_job)
         if batch_id
           tagged = payload_hash.merge(Batch::METADATA_KEY => batch_id)
-          Batch.track_enqueue(tagged) if track
+          Batch.track_enqueue(tagged)
           return tagged
         end
 
-        retry_batch_id = active_job && retry_batch_id_for(active_job)
+        retry_batch_id = retry_batch_id_for(active_job)
         return payload_hash unless retry_batch_id
 
         tagged = payload_hash.merge(Batch::METADATA_KEY => retry_batch_id)
@@ -335,14 +352,20 @@ module Pgbus
         tagged
       end
 
+      # Only tags: the bulk is counted once per batch below. A retry re-enqueue
+      # never takes the bulk path (retry_on enqueues one job at a time).
+      def tag_bulk_member(payload_hash, active_job)
+        batch_id = member_batch_id(active_job)
+        batch_id ? payload_hash.merge(Batch::METADATA_KEY => batch_id) : payload_hash
+      end
+
       def enqueue_immediate(queue, jobs, priority: nil)
         return if jobs.empty?
 
         payloads = jobs.map do |j|
-          inject_batch_metadata(FairShare.inject_metadata(j, Serializer.serialize_job_hash(j)), track: false)
+          tag_bulk_member(FairShare.inject_metadata(j, Serializer.serialize_job_hash(j)), j)
         end
-        # One guarded increment for the whole bulk, not one per job.
-        Batch.track_enqueue(payloads) if Thread.current[:pgbus_batch_id]
+        track_bulk(payloads)
         physical = physical_queue(queue, priority)
         msg_ids = nil
         msg_ids = Pgbus.client.send_batch(queue, payloads, priority: priority)
@@ -361,6 +384,24 @@ module Pgbus
       rescue Pgbus::SchemaNotReady => e
         Pgbus.logger.error { "[Pgbus] #{e.message}" }
         raise
+      ensure
+        jobs.each { |j| forget_enqueue_batch_id(j) }
+      end
+
+      # One guarded increment per batch for the whole bulk, not one per job.
+      # When a later batch refuses (finished), the batches already counted are
+      # uncounted before the error goes up: nothing has been sent yet.
+      def track_bulk(payloads)
+        tracked = []
+        payloads.select { |p| p[Batch::METADATA_KEY] }
+                .group_by { |p| p[Batch::METADATA_KEY] }
+                .each_value do |members|
+                  Batch.track_enqueue(members)
+                  tracked.concat(members)
+                end
+      rescue StandardError
+        tracked.each { |payload| Batch.untrack_enqueue(payload) }
+        raise
       end
 
       def scheduled_in_future?(job)

data/lib/pgbus/active_job/batch_id.rb

@@ -16,11 +16,33 @@ module Pgbus
     # Both round-trip through +serialize+/+deserialize+, and both are omitted
     # from the serialized hash when unset — an unbatched job's payload is
     # byte-for-byte what it was before this mixin existed.
+    #
+    # A third, transient id, +enqueue_batch_id+, is the batch this instance
+    # was *added* to. +b.add+ / +batch.add+ set it, and +enqueue+ copies the
+    # block's tag onto it, before Active Job decides whether to defer the
+    # enqueue to after commit (+enqueue_after_transaction_commit+). The
+    # deferred enqueue keeps the instance, so the adapter still finds the
+    # batch once the block's thread tag is gone (issue #553). It is never
+    # serialized and the adapter clears it once the enqueue is done.
     module BatchId
       extend ActiveSupport::Concern
 
       included do
-        attr_accessor :batch_id, :callback_batch_id
+        attr_accessor :batch_id, :callback_batch_id, :enqueue_batch_id
+      end
+
+      # Mark +jobs+ as added to +batch_id+ (instances without this mixin are
+      # left alone; they join through the block's thread tag only).
+      def self.capture(jobs, batch_id)
+        jobs.each { |job| job.enqueue_batch_id = batch_id if job.respond_to?(:enqueue_batch_id=) }
+      end
+
+      # Plain assignment, not ||=: an id left by an add whose enqueue never
+      # ran (rolled back, or aborted by a before_enqueue) must not follow the
+      # instance into this one. b.add / batch.add never come through here.
+      def enqueue(...)
+        self.enqueue_batch_id = Thread.current[:pgbus_batch_id]
+        super
       end
 
       def serialize

data/lib/pgbus/batch/builder.rb

@@ -59,6 +59,7 @@ module Pgbus
         raise ArgumentError, UNTAGGED_MESSAGE unless Thread.current[:pgbus_batch_id] == @batch.batch_id
 
         jobs = self.class.job_instances(jobs)
+        Pgbus::ActiveJob::BatchId.capture(jobs, @batch.batch_id)
         ::ActiveJob.perform_all_later(jobs) if jobs.any?
         yield if block_given?
         jobs

data/lib/pgbus/batch.rb

@@ -45,6 +45,19 @@ module Pgbus
     # Thread.current): b.add raises anywhere else, and a plain perform_later
     # from a thread or fiber the block spawns does not join the batch.
     #
+    # Inside a database transaction the batch stays pending until the
+    # transaction commits: a job with enqueue_after_transaction_commit keeps
+    # the batch on its instance (b.add, batch.add and perform_later put it
+    # there) and counts itself in at commit, before the batch starts. On a
+    # rollback no job is sent and, when pgbus shares the application's
+    # database, the batch row is gone with the rest (a separate pgbus
+    # database commits the row on its own connection). A bare
+    # ActiveJob.perform_all_later in the block does not keep it: use b.add.
+    # Add jobs that defer: one sent at once, on a connection other than the
+    # caller's, can run before the batch commits and is then accounted for
+    # only by the stalled-execution sweep. A job instance is one member (one
+    # job_id): enqueue it once.
+    #
     #   Pgbus::Batch.start(description: "Import") do |b|
     #     b.on_complete ImportDoneJob
     #     b.add(*rows.map { |row| ImportRowJob.new(row.id) })
@@ -124,7 +137,7 @@ module Pgbus
       end
       @started = true
       count_jobs(&)
-      start_processing
+      self.class.send(:after_transactions_commit) { start_processing }
       self
     end
 
@@ -139,6 +152,7 @@ module Pgbus
       return jobs if jobs.empty? && block.nil?
 
       enqueue do
+        Pgbus::ActiveJob::BatchId.capture(jobs, batch_id)
         ::ActiveJob.perform_all_later(jobs) if jobs.any?
         yield if block
       end
@@ -473,6 +487,22 @@ module Pgbus
         finish_if_needed(try_finish!(batch_id))
       end
 
+      # Run the end-of-block start (or an open batch's re-check) once every
+      # open transaction has committed, and at once when none is open
+      # (issue #553). Jobs with enqueue_after_transaction_commit register
+      # their enqueue as an after_commit callback during the block; Active
+      # Record runs a transaction's callbacks in registration order and
+      # appends a savepoint's to its parent's on release, so every one of
+      # them has counted itself into the still-pending row before this runs.
+      # On a rollback none of them runs, and the row (created in the same
+      # transaction) is gone. Active Record 7.1 has no
+      # after_all_transactions_commit, and Active Job 7.1 never defers.
+      def after_transactions_commit(&)
+        return yield unless ::ActiveRecord.respond_to?(:after_all_transactions_commit)
+
+        ::ActiveRecord.after_all_transactions_commit(&)
+      end
+
       def finish_if_needed(result)
         return result unless result&.fetch(:just_finished, false) && result[:record]
 
@@ -629,8 +659,10 @@ module Pgbus
       raise AlreadyFinished, "Can't add jobs into an already finished batch" if finished?
 
       count_jobs(&)
-      reload
-      self.class.send(:finish_if_needed, BatchEntry.check_finished!(batch_id))
+      self.class.send(:after_transactions_commit) do
+        reload
+        self.class.send(:finish_if_needed, BatchEntry.check_finished!(batch_id))
+      end
       self
     end
 

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "pgbus/integrations/appsignal/span_subscriber"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # The `<Handler>#handle` transaction around pgbus.event_processed, and
+      # the fallback for an error pgbus.event_failed reports from outside it
+      # (an event that could not be built never reaches the span).
+      class EventSpan < SpanSubscriber
+        private
+
+        def frame_key = :pgbus_appsignal_event_span
+
+        def attached_key = :pgbus_appsignal_event_span_error
+
+        def describe(transaction, payload)
+          transaction.set_action_if_nil("#{payload[:handler] || "UnknownHandler"}#handle")
+          apply_queue_start(transaction, payload[:published_at])
+          transaction.add_tags(handler_tags(payload))
+        end
+
+        # The processed count is taken at finish whether or not the handler
+        # raised, as Metrics::Subscriber does: a raised handler counts as
+        # processed and, through pgbus.event_failed, as failed.
+        def finished(payload, duration)
+          tags = { handler: payload[:handler], routing_key: payload[:routing_key] }
+          ::Appsignal.add_distribution_value("pgbus_event_duration_ms", duration, tags)
+          ::Appsignal.increment_counter("pgbus_event_count", 1, tags.merge(status: "processed"))
+        end
+
+        def handler_tags(payload)
+          {
+            "handler" => payload[:handler],
+            "routing_key" => payload[:routing_key],
+            "attempts" => payload[:read_ct]
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "pgbus/integrations/appsignal/span_subscriber"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # The `<JobClass>#perform` transaction around pgbus.executor.execute
+      # (deserialize + perform + archive), and the fallback for an error
+      # pgbus.job_failed reports from outside it.
+      class JobSpan < SpanSubscriber
+        private
+
+        def frame_key = :pgbus_appsignal_job_span
+
+        def attached_key = :pgbus_appsignal_job_span_error
+
+        def describe(transaction, payload)
+          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] } } if payload.key?(:arguments)
+        end
+
+        def finished(payload, duration)
+          ::Appsignal.add_distribution_value(
+            "pgbus_job_duration_ms",
+            duration,
+            { queue: payload[:queue], job_class: payload[:job_class] }
+          )
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pgbus
+  module Integrations
+    module Appsignal
+      # The AppSignal transaction of one unit of work: a job (JobSpan, on
+      # pgbus.executor.execute) or an event handler (EventSpan, on
+      # pgbus.event_processed).
+      #
+      # An ActiveSupport::Notifications listener that responds to #start and
+      # #finish is called on both sides of the instrumented block (the Evented
+      # subscriber). A finish-only block subscriber runs after the block has
+      # returned, so the transaction it opened was never current while the job
+      # ran: job code had nothing to attach to, and pgbus.job_failed, fired
+      # later, found no transaction to put its error on (issue #552). Here
+      # #start opens the transaction before the block runs, so job and handler
+      # code, and the Rails error reporter, find it current; #finish records
+      # the exception the block raised (the instrumenter puts it in
+      # payload[:exception_object]) and completes the transaction.
+      #
+      # Like AppSignal's own ActiveJob hook, a transaction that is already
+      # current is reused and left to its owner to complete.
+      #
+      # The frame lives in Thread.current[], which is fiber-local, so start and
+      # finish pair up per job under execution_mode: :async, the same way
+      # AppSignal keeps its current transaction. A span opened inside another
+      # of its kind (a handler calling another handler's #process) keeps the
+      # enclosing frame and restores it at finish, so the outer span still
+      # completes its transaction. An instance holds no state of its own.
+      # Nothing an AppSignal call raises reaches the job: it is logged at warn
+      # level.
+      #
+      # Subclasses define #frame_key and #attached_key (the fiber-local slots),
+      # #describe(transaction, payload) (action, queue start, tags) and
+      # #finished(payload, duration_ms) (the span's metrics).
+      class SpanSubscriber
+        BACKGROUND_JOB = "background_job"
+
+        # owned: this span created the transaction, so it completes it.
+        # previous: the enclosing span's frame, restored at finish.
+        Frame = Struct.new(:started_at, :owned, :previous)
+
+        def start(_name, _id, payload)
+          frame = Thread.current[frame_key] = Frame.new(monotonic_now, false, Thread.current[frame_key])
+          guard do
+            frame.owned = !::Appsignal::Transaction.current?
+            transaction = frame.owned ? ::Appsignal::Transaction.create(BACKGROUND_JOB) : ::Appsignal::Transaction.current
+            describe(transaction, payload)
+          end
+        end
+
+        def finish(_name, _id, payload)
+          frame = Thread.current[frame_key]
+          guard do
+            Thread.current[attached_key] = attach(payload[:exception_object])
+            finished(payload, monotonic_now - frame.started_at)
+          end
+        ensure
+          guard do
+            Thread.current[frame_key] = frame.previous
+            ::Appsignal::Transaction.complete_current! if frame.owned
+          end
+        end
+
+        # pgbus.job_failed and pgbus.event_failed fire after #finish. An error
+        # the span recorded is already on its transaction. One raised before
+        # the span opened (a message body that is not JSON, an event that
+        # cannot be built, a dead-letter move that failed) had no transaction,
+        # so it is reported on one of its own, named and tagged like the span's
+        # (or added to a transaction that is current, which is left as it is).
+        def report_unattached(error, payload)
+          attached = Thread.current[attached_key]
+          Thread.current[attached_key] = nil
+          return if error.nil? || error.equal?(attached)
+          return ::Appsignal::Transaction.current.set_error(error) if ::Appsignal::Transaction.current?
+
+          ::Appsignal.report_error(error) do |transaction|
+            transaction.set_namespace(BACKGROUND_JOB)
+            describe(transaction, payload)
+          end
+        end
+
+        private
+
+        # Returns the exception it recorded, nil when there was none.
+        def attach(error)
+          return unless error && ::Appsignal::Transaction.current?
+
+          ::Appsignal::Transaction.current.set_error(error)
+          error
+        end
+
+        # 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 guard
+          yield
+        rescue StandardError => e
+          Pgbus.logger.warn { "[Pgbus::AppSignal] subscriber error: #{e.class}: #{e.message}" }
+        end
+
+        def monotonic_now
+          ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :float_millisecond)
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require "time"
+require "pgbus/integrations/appsignal/job_span"
+require "pgbus/integrations/appsignal/event_span"
 
 module Pgbus
   module Integrations
@@ -10,16 +11,23 @@ module Pgbus
       #
       # 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.
+      # action `<JobClass>#perform` or `<HandlerClass>#handle`. The transaction
+      # is opened when pgbus.executor.execute / pgbus.event_processed starts and
+      # completed when it finishes (JobSpan, EventSpan), so it is current while the
+      # job or handler runs and carries the error the execution raised. 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
+
+        # Built once, at load: a span keeps its state in a fiber-local frame,
+        # never in itself.
+        JOB_SPAN = JobSpan.new.freeze
+        EVENT_SPAN = EventSpan.new.freeze
+        private_constant :METRIC_PREFIX, :JOB_SPAN, :EVENT_SPAN
 
         # Tracked so we can detach in reset! (used by specs). Installed once
         # at boot (the engine's after_initialize); @install_lock makes the
@@ -54,11 +62,11 @@ module Pgbus
 
           def subscribe_all
             [
-              subscribe("pgbus.executor.execute") { |event| on_executor_execute(event) },
+              ActiveSupport::Notifications.subscribe("pgbus.executor.execute", JOB_SPAN),
               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) },
+              ActiveSupport::Notifications.subscribe("pgbus.event_processed", EVENT_SPAN),
               subscribe("pgbus.event_failed") { |event| on_event_failed(event) },
               subscribe("pgbus.event_dead_lettered") { |event| on_event_dead_lettered(event) },
               subscribe("pgbus.client.send_message") { |event| on_send_message(event) },
@@ -98,22 +106,6 @@ module Pgbus
 
           # ── 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(
@@ -123,15 +115,18 @@ module Pgbus
             )
           end
 
+          # The counter has its own guard so a raise there cannot keep the
+          # error from being reported.
           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)
+            safely do
+              ::Appsignal.increment_counter(
+                "#{METRIC_PREFIX}queue_job_count",
+                1,
+                { queue: payload[:queue], job_class: payload[:job_class], status: "failed" }
+              )
+            end
+            JOB_SPAN.report_unattached(payload[:exception_object], payload)
           end
 
           def on_job_dead_lettered(event)
@@ -145,40 +140,23 @@ module Pgbus
 
           # ── 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
-
+          # The counter has its own guard so a raise there cannot keep the
+          # error from being reported.
           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)
+            safely do
+              ::Appsignal.increment_counter(
+                "#{METRIC_PREFIX}event_count",
+                1,
+                { handler: payload[:handler], routing_key: payload[:routing_key], status: "failed" }
+              )
+            end
+            EVENT_SPAN.report_unattached(payload[:exception_object], payload)
           end
 
           # A counter only, like on_job_dead_lettered: nothing is raised at
-          # move time, and the handler's error already went out through
-          # pgbus.event_failed on the attempt that raised (issue #543). A body
+          # move time, and the handler's error already went out on the
+          # attempt that raised (issues #543, #552). A body
           # that is not JSON leaves handler and routing_key nil; compact drops
           # those tags, as Metrics::Subscriber does.
           def on_event_dead_lettered(event)
@@ -295,49 +273,6 @@ module Pgbus
               { reason: payload[:reason], kind: "consumer" }
             )
           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

data/lib/pgbus/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.19.3
+  version: 0.19.4
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -364,7 +364,10 @@ files:
 - 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/event_span.rb
+- lib/pgbus/integrations/appsignal/job_span.rb
 - lib/pgbus/integrations/appsignal/probe.rb
+- lib/pgbus/integrations/appsignal/span_subscriber.rb
 - lib/pgbus/integrations/appsignal/subscriber.rb
 - lib/pgbus/log_formatter.rb
 - lib/pgbus/mcp.rb