pgbus 0.13.2 → 0.13.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 295404bb7b5b6d289a2bfd4f10d9e5bc6df442f8d949454cf1dd78adf620a25f
-  data.tar.gz: 2ee9c8e2c40f47bb900e10d2ef4c55b5e21e3cd4d997c614c628b696ac759183
+  metadata.gz: 2e9af048ef1aa2d0fecab62f5471ca9ab6c3e2595353c7eb1a13cde57c37564a
+  data.tar.gz: 29a35e789733ac394136eaea8fc2b7f2e709617ceee818dd2b2752d9b017d45d
 SHA512:
-  metadata.gz: 184484168fd458dbdb09b98d12ae5d906ebb510a05abc626fd3812ee4cfebb5cd575c090b8014b9524a9aa19f65e99d1737df50b191ce79367e77858f72c5024
-  data.tar.gz: 92170d5077128d507968989f8d9d789bdc9afa7b4ccf92ecdc3b39b357a82608de39a83b4e9f2f899078466714bfb30f3f0c357a9dc977f35c9c21254c8b7dbd
+  metadata.gz: 392a67ed233feb5ffe0a98cf597efe3962b9e7c81d07a7e351f6c4e8aab8c03b3edc8e55204c3f0d0a4b82287b7f523cada5ca79e0684752f50c8f3272c9bdc0
+  data.tar.gz: 95b48a0ae66aaa239da08fa3c235a412241ddcfacea8384d84a66ca298308678062dc0192592b07484596fe12e27145a71474d5547b5046370bfca2785ae0f03

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+### Fixed
+
+- **Queue-age metrics no longer count vt-parked (scheduled/retrying) messages — one delayed job stops reading as a degraded queue (issue #389).** ⚠️ **Behavior change on the AppSignal `pgbus_queue_latency` gauge.** pgmq's `oldest_msg_age_sec` is computed from `enqueued_at` and ignores `vt`, but a job enqueued with `wait:` or parked on a long retry backoff lives in the queue table with a future `vt` — that *is* the delayed-delivery mechanism. So a single parked message made the age metric grow at wall-clock rate for hours on an otherwise drained queue, and any latency alert thresholding on it fired continuously ("oldest message is 17045s old" on a healthy queue with depth 1, `read_ct` 0). Every metrics surface now also exposes **`oldest_claimable_age_sec`** — `now() - min(vt)` over rows with `vt <= now()`, i.e. the age of the oldest message actually *eligible for pickup*: an immediately-enqueued message contributes from enqueue time (matching the old number on a plain backlog), a scheduled/backoff-parked message contributes nothing until due, an in-flight message (vt pushed forward) is excluded, and nil means "no claimable backlog" even when the table is non-empty. Surfaces: `Web::DataSource` (dashboard, JSON API, MCP `pgbus_queues` tool), a new Prometheus gauge `pgbus_queue_oldest_claimable_age_seconds`, a new AppSignal gauge `pgbus_queue_oldest_claimable_age_seconds`, `Pgbus::Client#oldest_claimable_ages` (raw-SQL reader, since pgmq's `metrics_result` type is frozen upstream), and a CLAIMABLE column in `pgbus queues`. The AppSignal **`pgbus_queue_latency` gauge now derives from the claimable age** and always emits — `(claimable_age || 0) * 1000`, 0 = no claimable backlog — so existing latency alerts stop false-firing with no dashboard changes; the raw `pgbus_queue_oldest_message_age_seconds` gauge keeps its enqueue-time semantics everywhere. The dashboard queue tables additionally split depth into **Parked** (`depth − visible`) and show the claimable age in place of the raw age, so a queue holding only backoff retries reads visibly healthy. Refs #389.
+
 ### Added
 
 - **Health-checked rolling restarts for the job container (issue #386).** ⚠️ **Behavior change on the standalone `/readyz`.** The supervisor's `health_port` server previously answered `/readyz` with the cluster-wide HealthAnalyzer verdict — so during a rolling deploy a freshly-booted container could pass an orchestrator's health gate on the strength of the *old* container's still-heartbeating workers, and the old container (with all its capacity) was stopped before the new one had forked a single child. The standalone `/readyz` is now **container-local**: 200 only when *this* supervisor verified its connection, bootstrapped queues, forked every configured child, and all of them are currently alive — with 503 bodies `BOOTING` (pre-boot), `DEGRADED` (a child died and is waiting out crash-restart backoff — precisely the state a deploy gate must fail on, keeping the old container running), and `DRAINING` (stop signal received). No database access on the probe path; the supervisor publishes an immutable snapshot per monitor pass and the accept thread reads it. The Rails-mounted `Pgbus::Web::HealthApp` keeps the cluster-wide verdict unchanged. Alongside it: **`pgbus-health`**, a shipped executable probe for docker `HEALTHCHECK` blocks (plain Ruby + stdlib sockets, loads neither Bundler nor the gem — cheap at 1–5s intervals, works in curl-less images; exit 0/1/2 = healthy/unhealthy/usage), and a README "Rolling restarts (Kamal, docker)" guide covering the healthcheck block, stop-timeout alignment, overlap-window duplicate-supervisor safety, and the `read_ct`-vs-deploy-kill DLQ caveat. Refs #386.

data/README.md

@@ -991,6 +991,7 @@ When `config.metrics_enabled = true` (default), the dashboard exposes Prometheus
 
 | Metric | Description |
 |--------|-------------|
+| `pgbus_queue_oldest_claimable_age_seconds` | Age of the oldest message eligible for pickup (visibility timeout elapsed) — safe to alert on: scheduled/backoff-parked messages don't count until due; the series is omitted entirely when no claimable backlog exists (while the raw `pgbus_queue_oldest_message_age_seconds` gauge may still report a parked message's age) |
 | `pgbus_table_dead_tuples` | Dead tuple count per PGMQ table |
 | `pgbus_table_live_tuples` | Live tuple count per PGMQ table |
 | `pgbus_table_bloat_ratio` | Dead / (dead + live) per table |

data/app/views/pgbus/dashboard/_queues_table.html.erb

@@ -12,7 +12,8 @@
             <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.queue") %></th>
             <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.depth") %></th>
             <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.visible") %></th>
-            <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.oldest") %></th>
+            <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.parked") %></th>
+            <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.oldest_claimable") %></th>
             <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.dashboard.queues_table.headers.total") %></th>
           </tr>
         </thead>
@@ -25,12 +26,13 @@
               </td>
               <td data-label="Depth" class="px-4 py-3 text-sm text-right text-gray-700"><%= pgbus_number(q[:queue_length]) %></td>
               <td data-label="Visible" class="px-4 py-3 text-sm text-right text-gray-700"><%= pgbus_number(q[:queue_visible_length]) %></td>
-              <td data-label="Oldest" class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:oldest_msg_age_sec] || "—" %></td>
+              <td data-label="Parked" class="px-4 py-3 text-sm text-right text-gray-500"><%= pgbus_number(q[:parked_length]) %></td>
+              <td data-label="Oldest claimable" class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:oldest_claimable_age_sec] || "—" %></td>
               <td data-label="Total" class="px-4 py-3 text-sm text-right text-gray-500"><%= pgbus_number(q[:total_messages]) %></td>
             </tr>
           <% end %>
           <% if @queues.empty? %>
-            <tr><td colspan="5" class="px-4 py-8 text-center text-sm text-gray-400"><%= t("pgbus.dashboard.queues_table.empty") %></td></tr>
+            <tr><td colspan="6" class="px-4 py-8 text-center text-sm text-gray-400"><%= t("pgbus.dashboard.queues_table.empty") %></td></tr>
           <% end %>
         </tbody>
       </table>

data/app/views/pgbus/queues/_queues_list.html.erb

@@ -6,7 +6,8 @@
           <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.queue") %></th>
           <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.depth") %></th>
           <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.visible") %></th>
-          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.oldest") %></th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.parked") %></th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.oldest_claimable") %></th>
           <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.newest") %></th>
           <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.total_ever") %></th>
           <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500"><%= t("pgbus.queues.queues_list.headers.actions") %></th>
@@ -24,7 +25,8 @@
             </td>
             <td data-label="Depth" class="px-4 py-3 text-sm text-right font-mono text-gray-700"><%= pgbus_number(q[:queue_length]) %></td>
             <td data-label="Visible" class="px-4 py-3 text-sm text-right font-mono text-gray-700"><%= pgbus_number(q[:queue_visible_length]) %></td>
-            <td data-label="Oldest" class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:oldest_msg_age_sec] || "—" %></td>
+            <td data-label="Parked" class="px-4 py-3 text-sm text-right font-mono text-gray-500"><%= pgbus_number(q[:parked_length]) %></td>
+            <td data-label="Oldest claimable" class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:oldest_claimable_age_sec] || "—" %></td>
             <td data-label="Newest" class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:newest_msg_age_sec] || "—" %></td>
             <td data-label="Total" class="px-4 py-3 text-sm text-right text-gray-500"><%= pgbus_number(q[:total_messages]) %></td>
             <td data-label="Actions" class="px-4 py-3 text-sm text-right space-x-2">
@@ -51,7 +53,7 @@
           </tr>
         <% end %>
         <% if @queues.empty? %>
-          <tr><td colspan="7" class="px-4 py-8 text-center text-sm text-gray-400"><%= t("pgbus.queues.queues_list.empty") %></td></tr>
+          <tr><td colspan="8" class="px-4 py-8 text-center text-sm text-gray-400"><%= t("pgbus.queues.queues_list.empty") %></td></tr>
         <% end %>
       </tbody>
     </table>

data/app/views/pgbus/queues/show.html.erb

@@ -13,6 +13,9 @@
       <p class="text-sm text-gray-500 mt-1">
         <%= t("pgbus.queues.show.depth") %> <span class="font-mono"><%= @queue[:queue_length] %></span> |
         <%= t("pgbus.queues.show.visible") %> <span class="font-mono"><%= @queue[:queue_visible_length] %></span> |
+        <%= t("pgbus.queues.show.parked") %> <span class="font-mono"><%= @queue[:parked_length] %></span> |
+        <%= t("pgbus.queues.show.oldest") %> <span class="font-mono"><%= @queue[:oldest_msg_age_sec] || "—" %></span> |
+        <%= t("pgbus.queues.show.oldest_claimable") %> <span class="font-mono"><%= @queue[:oldest_claimable_age_sec] || "—" %></span> |
         <%= t("pgbus.queues.show.total") %> <span class="font-mono"><%= pgbus_number(@queue[:total_messages]) %></span>
       </p>
     <% end %>

data/config/locales/da.yml

@@ -65,7 +65,8 @@ da:
         empty: Ingen køer fundet
         headers:
           depth: Dybde
-          oldest: Ældste (s)
+          oldest_claimable: Ældste tilgængelig (s)
+          parked: Parkeret
           queue: Kø
           total: Total
           visible: Synlig
@@ -475,7 +476,8 @@ da:
           actions: Handlinger
           depth: Dybde
           newest: Nyeste (s)
-          oldest: Ældste (s)
+          oldest_claimable: Ældste tilgængelig (s)
+          parked: Parkeret
           queue: Kø
           total_ever: Total nogensinde
           visible: Synlig
@@ -516,6 +518,9 @@ da:
           scheduled: 'Planlagt:'
           timezone: 'Tidszone:'
           visible_at: 'Synlig fra:'
+        oldest: 'Ældste:'
+        oldest_claimable: 'Ældste tilgængelig:'
+        parked: 'Parkeret:'
         pause: Pause
         pause_confirm: Pause behandling?
         purge_confirm: Rens alle beskeder?

data/config/locales/de.yml

@@ -65,7 +65,8 @@ de:
         empty: Keine Warteschlangen gefunden
         headers:
           depth: Tiefe
-          oldest: Älteste (s)
+          oldest_claimable: Älteste verfügbar (s)
+          parked: Geparkt
           queue: Warteschlange
           total: Gesamt
           visible: Sichtbar
@@ -475,7 +476,8 @@ de:
           actions: Aktionen
           depth: Tiefe
           newest: Neueste (s)
-          oldest: Älteste (s)
+          oldest_claimable: Älteste verfügbar (s)
+          parked: Geparkt
           queue: Warteschlange
           total_ever: Insgesamt jemals
           visible: Sichtbar
@@ -516,6 +518,9 @@ de:
           scheduled: 'Geplant:'
           timezone: 'Zeitzone:'
           visible_at: 'Sichtbar ab:'
+        oldest: 'Älteste:'
+        oldest_claimable: 'Älteste verfügbar:'
+        parked: 'Geparkt:'
         pause: Pause
         pause_confirm: Verarbeitung pausieren?
         purge_confirm: Alle Nachrichten löschen?

data/config/locales/en.yml

@@ -65,7 +65,8 @@ en:
         empty: No queues found
         headers:
           depth: Depth
-          oldest: Oldest (s)
+          oldest_claimable: Oldest claimable (s)
+          parked: Parked
           queue: Queue
           total: Total
           visible: Visible
@@ -475,7 +476,8 @@ en:
           actions: Actions
           depth: Depth
           newest: Newest (s)
-          oldest: Oldest (s)
+          oldest_claimable: Oldest claimable (s)
+          parked: Parked
           queue: Queue
           total_ever: Total Ever
           visible: Visible
@@ -516,6 +518,9 @@ en:
           scheduled: 'Scheduled at:'
           timezone: 'Timezone:'
           visible_at: 'Visible at:'
+        oldest: 'Oldest:'
+        oldest_claimable: 'Oldest claimable:'
+        parked: 'Parked:'
         pause: Pause
         pause_confirm: Pause processing?
         purge_confirm: Purge all messages?

data/config/locales/es.yml

@@ -65,7 +65,8 @@ es:
         empty: No se encontraron colas
         headers:
           depth: Profundidad
-          oldest: El más antiguo (s)
+          oldest_claimable: Más antiguo disponible (s)
+          parked: Aparcados
           queue: Cola
           total: Total
           visible: Visible
@@ -475,7 +476,8 @@ es:
           actions: Acciones
           depth: Profundidad
           newest: Más nuevo (s)
-          oldest: Más antiguo (s)
+          oldest_claimable: Más antiguo disponible (s)
+          parked: Aparcados
           queue: Cola
           total_ever: Total acumulado
           visible: Visible
@@ -516,6 +518,9 @@ es:
           scheduled: 'Programado:'
           timezone: 'Zona horaria:'
           visible_at: 'Visible en:'
+        oldest: 'Más antiguo:'
+        oldest_claimable: 'Más antiguo disponible:'
+        parked: 'Aparcados:'
         pause: Pausar
         pause_confirm: "¿Pausar el procesamiento?"
         purge_confirm: "¿Purgar todos los mensajes?"

data/config/locales/fi.yml

@@ -65,7 +65,8 @@ fi:
         empty: Jonot eivät löytyneet
         headers:
           depth: Syvyys
-          oldest: Vanhin (s)
+          oldest_claimable: Vanhin saatavilla (s)
+          parked: Pysäköidyt
           queue: Jono
           total: Yhteensä
           visible: Näkyvissä
@@ -475,7 +476,8 @@ fi:
           actions: Toiminnot
           depth: Syvyys
           newest: Uusimmat (s)
-          oldest: Vanhimmat (s)
+          oldest_claimable: Vanhin saatavilla (s)
+          parked: Pysäköidyt
           queue: Jono
           total_ever: Yhteensä koskaan
           visible: Näkyvissä
@@ -516,6 +518,9 @@ fi:
           scheduled: 'Aikataulutettu:'
           timezone: 'Aikavyöhyke:'
           visible_at: 'Näkyvissä:'
+        oldest: 'Vanhin:'
+        oldest_claimable: 'Vanhin saatavilla:'
+        parked: 'Pysäköidyt:'
         pause: Tauko
         pause_confirm: Keskeytetäänkö käsittely?
         purge_confirm: Tyhjennetäänkö kaikki viestit?

data/config/locales/fr.yml

@@ -65,7 +65,8 @@ fr:
         empty: Aucune file d'attente trouvée
         headers:
           depth: Profondeur
-          oldest: Le plus ancien (s)
+          oldest_claimable: Plus ancien disponible (s)
+          parked: Différés
           queue: File d'attente
           total: Total
           visible: Visible
@@ -475,7 +476,8 @@ fr:
           actions: Actions
           depth: Profondeur
           newest: Le plus récent (s)
-          oldest: Le plus ancien (s)
+          oldest_claimable: Plus ancien disponible (s)
+          parked: Différés
           queue: File d'attente
           total_ever: Total jamais
           visible: Visible
@@ -516,6 +518,9 @@ fr:
           scheduled: 'Planifié :'
           timezone: 'Fuseau horaire :'
           visible_at: 'Visible à :'
+        oldest: 'Plus ancien :'
+        oldest_claimable: 'Plus ancien disponible :'
+        parked: 'Différés :'
         pause: Pause
         pause_confirm: Mettre en pause le traitement ?
         purge_confirm: Purger tous les messages ?

data/config/locales/it.yml

@@ -65,7 +65,8 @@ it:
         empty: Nessuna coda trovata
         headers:
           depth: Profondità
-          oldest: Più vecchio (s)
+          oldest_claimable: Più vecchio disponibile (s)
+          parked: Posticipati
           queue: Coda
           total: Totale
           visible: Visibile
@@ -475,7 +476,8 @@ it:
           actions: Azioni
           depth: Profondità
           newest: Più recente (s)
-          oldest: Più vecchio (s)
+          oldest_claimable: Più vecchio disponibile (s)
+          parked: Posticipati
           queue: Coda
           total_ever: Totale mai
           visible: Visibile
@@ -516,6 +518,9 @@ it:
           scheduled: 'Programmato:'
           timezone: 'Fuso orario:'
           visible_at: 'Visibile alle:'
+        oldest: 'Più vecchio:'
+        oldest_claimable: 'Più vecchio disponibile:'
+        parked: 'Posticipati:'
         pause: Pausa
         pause_confirm: Mettere in pausa l'elaborazione?
         purge_confirm: Eliminare tutti i messaggi?

data/config/locales/ja.yml

@@ -65,7 +65,8 @@ ja:
         empty: キューが見つかりません
         headers:
           depth: 深さ
-          oldest: 最古 (秒)
+          oldest_claimable: 取得可能な最古 (秒)
+          parked: 待機中
           queue: キュー
           total: 合計
           visible: 表示中
@@ -475,7 +476,8 @@ ja:
           actions: アクション
           depth: 深さ
           newest: 最新 (秒)
-          oldest: 最古 (秒)
+          oldest_claimable: 取得可能な最古 (秒)
+          parked: 待機中
           queue: キュー
           total_ever: 合計数
           visible: 表示中
@@ -516,6 +518,9 @@ ja:
           scheduled: スケジュール済み：
           timezone: タイムゾーン：
           visible_at: 表示可能日時：
+        oldest: '最古:'
+        oldest_claimable: '取得可能な最古:'
+        parked: '待機中:'
         pause: 一時停止
         pause_confirm: 処理を一時停止しますか？
         purge_confirm: すべてのメッセージを削除しますか？

data/config/locales/nb.yml

@@ -65,7 +65,8 @@ nb:
         empty: Ingen køer funnet
         headers:
           depth: Dybde
-          oldest: Eldste (s)
+          oldest_claimable: Eldste tilgjengelig (s)
+          parked: Parkert
           queue: Kø
           total: Totalt
           visible: Synlig
@@ -475,7 +476,8 @@ nb:
           actions: Handlinger
           depth: Dybde
           newest: Nyeste (s)
-          oldest: Eldste (s)
+          oldest_claimable: Eldste tilgjengelig (s)
+          parked: Parkert
           queue: Kø
           total_ever: Totalt noensinne
           visible: Synlig
@@ -516,6 +518,9 @@ nb:
           scheduled: 'Planlagt:'
           timezone: 'Tidssone:'
           visible_at: 'Synlig fra:'
+        oldest: 'Eldste:'
+        oldest_claimable: 'Eldste tilgjengelig:'
+        parked: 'Parkert:'
         pause: Pause
         pause_confirm: Pause behandling?
         purge_confirm: Rens alle meldinger?

data/config/locales/nl.yml

@@ -65,7 +65,8 @@ nl:
         empty: Geen wachtrijen gevonden
         headers:
           depth: Diepte
-          oldest: Oudste (s)
+          oldest_claimable: Oudste beschikbaar (s)
+          parked: Geparkeerd
           queue: Wachtrij
           total: Totaal
           visible: Zichtbaar
@@ -475,7 +476,8 @@ nl:
           actions: Acties
           depth: Diepte
           newest: Nieuwste (s)
-          oldest: Oudste (s)
+          oldest_claimable: Oudste beschikbaar (s)
+          parked: Geparkeerd
           queue: Wachtrij
           total_ever: Totaal ooit
           visible: Zichtbaar
@@ -516,6 +518,9 @@ nl:
           scheduled: 'Gepland:'
           timezone: 'Tijdzone:'
           visible_at: 'Zichtbaar op:'
+        oldest: 'Oudste:'
+        oldest_claimable: 'Oudste beschikbaar:'
+        parked: 'Geparkeerd:'
         pause: Pauzeren
         pause_confirm: Verwerking pauzeren?
         purge_confirm: Alle berichten verwijderen?

data/config/locales/pt.yml

@@ -65,7 +65,8 @@ pt:
         empty: Nenhuma fila encontrada
         headers:
           depth: Profundidade
-          oldest: Mais antigo (s)
+          oldest_claimable: Mais antigo disponível (s)
+          parked: Adiados
           queue: Fila
           total: Total
           visible: Visível
@@ -475,7 +476,8 @@ pt:
           actions: Ações
           depth: Profundidade
           newest: Mais novo (s)
-          oldest: Mais antigo (s)
+          oldest_claimable: Mais antigo disponível (s)
+          parked: Adiados
           queue: Fila
           total_ever: Total de todos os tempos
           visible: Visível
@@ -516,6 +518,9 @@ pt:
           scheduled: 'Agendado:'
           timezone: 'Fuso horário:'
           visible_at: 'Visível em:'
+        oldest: 'Mais antigo:'
+        oldest_claimable: 'Mais antigo disponível:'
+        parked: 'Adiados:'
         pause: Pausar
         pause_confirm: Pausar processamento?
         purge_confirm: Limpar todas as mensagens?

data/config/locales/sv.yml

@@ -65,7 +65,8 @@ sv:
         empty: Inga köer hittades
         headers:
           depth: Djup
-          oldest: Äldst (s)
+          oldest_claimable: Äldsta tillgänglig (s)
+          parked: Parkerade
           queue: Kö
           total: Totalt
           visible: Synliga
@@ -475,7 +476,8 @@ sv:
           actions: Åtgärder
           depth: Djup
           newest: Nyaste (s)
-          oldest: Äldsta (s)
+          oldest_claimable: Äldsta tillgänglig (s)
+          parked: Parkerade
           queue: Kö
           total_ever: Totalt någonsin
           visible: Synliga
@@ -516,6 +518,9 @@ sv:
           scheduled: 'Schemalagt:'
           timezone: 'Tidszon:'
           visible_at: 'Synlig vid:'
+        oldest: 'Äldsta:'
+        oldest_claimable: 'Äldsta tillgänglig:'
+        parked: 'Parkerade:'
         pause: Pausa
         pause_confirm: Pausa bearbetning?
         purge_confirm: Rensa alla meddelanden?

data/lib/pgbus/cli.rb

@@ -177,14 +177,16 @@ module Pgbus
     def list_queues
       Pgbus.client.list_queues
       metrics = Pgbus.client.metrics
+      claimable_ages = Pgbus.client.oldest_claimable_ages
 
-      puts "QUEUE                                    DEPTH      VISIBLE    OLDEST (s)      TOTAL          "
-      puts "-" * 95
+      puts "QUEUE                                    DEPTH      VISIBLE    OLDEST (s)      CLAIMABLE (s)   TOTAL          "
+      puts "-" * 111
 
       Array(metrics).each do |m|
-        puts format("%-40s %-10s %-10s %-15s %-15s",
+        puts format("%-40s %-10s %-10s %-15s %-15s %-15s",
                     m.queue_name, m.queue_length, m.queue_visible_length,
-                    m.oldest_msg_age_sec || "-", m.total_messages)
+                    m.oldest_msg_age_sec || "-", claimable_ages[m.queue_name] || "-",
+                    m.total_messages)
       end
     end
 

data/lib/pgbus/client.rb

@@ -543,6 +543,38 @@ module Pgbus
       end
     end
 
+    # Age (seconds) of the oldest message actually eligible for pickup, i.e.
+    # whose visibility timeout has elapsed. Unlike pgmq's oldest_msg_age_sec
+    # (computed from enqueued_at), a scheduled or backoff-parked message —
+    # future vt — contributes nothing until it comes due, so a queue holding
+    # only parked messages reads nil ("no claimable backlog") instead of an
+    # age growing at wall-clock rate (issue #389). pgmq's metrics_result type
+    # is frozen upstream, so this lives here rather than in the SQL function.
+    #
+    # With a queue name: the age for that (prefixed) queue, or nil.
+    # Without: a hash of every physical queue in pgmq.meta to its age.
+    #
+    # Routes through the pooled @pgmq.with_connection (health-checked, bounded
+    # by the statement/socket timeouts applied at Client#initialize) rather
+    # than a fresh unbounded PG.connect per call — same rationale as
+    # notify_trigger_current?. synchronized: on the shared-Proc path @pgmq
+    # rides the AR raw connection, so the query must serialize against
+    # concurrent PGMQ operations. One checkout spans all per-queue queries;
+    # nothing nests inside it, so the shared pool_size=1 path is safe.
+    def oldest_claimable_ages(queue_name = nil)
+      synchronized do
+        @pgmq.with_connection do |conn|
+          if queue_name
+            claimable_age_for(conn, config.queue_name(queue_name))
+          else
+            names = conn.exec("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+                        .map { |row| row["queue_name"] }
+            names.to_h { |name| [name, claimable_age_for(conn, name)] }
+          end
+        end
+      end
+    end
+
     # Snapshot of the PGMQ connection pool: {size:, available:, pool_timeout:}.
     #
     # Reads pgmq-ruby's own pool counters (@pgmq.stats -> {size:, available:})
@@ -948,6 +980,18 @@ module Pgbus
       end
     end
 
+    # queue_name is a physical (already prefixed) queue name; sanitized to a
+    # bare identifier before interpolation, same as the dashboard's DataSource.
+    def claimable_age_for(conn, queue_name)
+      qtable = "q_#{QueueNameValidator.sanitize!(queue_name)}"
+      row = conn.exec(<<~SQL).first
+        SELECT EXTRACT(epoch FROM (NOW() - min(vt)))::int AS age_sec
+        FROM pgmq.#{qtable}
+        WHERE vt <= NOW()
+      SQL
+      row && row["age_sec"]&.to_i
+    end
+
     def with_raw_connection
       opts = config.connection_options
       owned = false

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

@@ -85,10 +85,14 @@ module Pgbus
               gauge "queue_visible_depth", q[:queue_visible_length], tags
               gauge "queue_paused", q[:paused] ? 1 : 0, tags
               age = q[:oldest_msg_age_sec]
-              if age
-                gauge "queue_oldest_message_age_seconds", age, tags
-                gauge "queue_latency", age * 1_000, tags
-              end
+              gauge "queue_oldest_message_age_seconds", age, tags if age
+              claimable_age = q[:oldest_claimable_age_sec]
+              gauge "queue_oldest_claimable_age_seconds", claimable_age, tags if claimable_age
+              # Latency = time the oldest *claimable* message has waited for
+              # pickup; a queue holding only vt-parked (scheduled/backoff)
+              # messages is healthy, so 0 — not the raw enqueued_at age, which
+              # grows at wall-clock rate on a parked message (issue #389).
+              gauge "queue_latency", (claimable_age || 0) * 1_000, tags
             end
           rescue StandardError => e
             log_failure("queue metrics", e)

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

@@ -14,6 +14,12 @@ module Pgbus
           (messages whose visibility timeout has expired and are ready to be
           claimed), oldest/newest message age in seconds, lifetime total, and
           paused state. Use this to answer "are any queues backed up?".
+          oldest_claimable_age_sec is the age of the oldest message actually
+          eligible for pickup — nil means no message is currently claimable:
+          every remaining message is scheduled, backoff-parked, or in flight
+          with a future visibility timeout. A queue whose oldest_msg_age_sec
+          keeps growing while oldest_claimable_age_sec stays nil has no
+          starving backlog — nothing is waiting for a worker.
         DESC
 
         input_schema(properties: {}, required: [])

data/lib/pgbus/version.rb

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

data/lib/pgbus/web/data_source.rb

@@ -1177,7 +1177,8 @@ module Pgbus
               (SELECT EXTRACT(epoch FROM (NOW() - min(enqueued_at)))::int FROM pgmq.#{qtable}) AS oldest_msg_age_sec,
               (SELECT CASE WHEN is_called THEN last_value ELSE 0 END FROM pgmq.#{seq_name}) AS total_messages,
               (SELECT max(read_ct) FROM pgmq.#{qtable}) AS max_read_ct,
-              (SELECT count(*) FROM pgmq.#{qtable} WHERE vt <= NOW() AND read_ct = 0) AS visible_unread_length
+              (SELECT count(*) FROM pgmq.#{qtable} WHERE vt <= NOW() AND read_ct = 0) AS visible_unread_length,
+              (SELECT EXTRACT(epoch FROM (NOW() - min(vt)))::int FROM pgmq.#{qtable} WHERE vt <= NOW()) AS oldest_claimable_age_sec
           SQL
         rescue StandardError => e
           Pgbus.logger.debug { "[Pgbus::Web] Skipping queue metrics for #{name}: #{e.message}" }
@@ -1193,7 +1194,9 @@ module Pgbus
             name: row["queue_name"],
             queue_length: row["queue_length"].to_i,
             queue_visible_length: row["queue_visible_length"].to_i,
+            parked_length: row["queue_length"].to_i - row["queue_visible_length"].to_i,
             oldest_msg_age_sec: row["oldest_msg_age_sec"]&.to_i,
+            oldest_claimable_age_sec: row["oldest_claimable_age_sec"]&.to_i,
             newest_msg_age_sec: row["newest_msg_age_sec"]&.to_i,
             total_messages: row["total_messages"].to_i,
             max_read_ct: row["max_read_ct"]&.to_i,
@@ -1216,6 +1219,7 @@ module Pgbus
               count(CASE WHEN vt <= NOW() THEN 1 END) AS queue_visible_length,
               EXTRACT(epoch FROM (NOW() - max(enqueued_at)))::int AS newest_msg_age_sec,
               EXTRACT(epoch FROM (NOW() - min(enqueued_at)))::int AS oldest_msg_age_sec,
+              EXTRACT(epoch FROM (NOW() - min(vt) FILTER (WHERE vt <= NOW())))::int AS oldest_claimable_age_sec,
               max(read_ct) AS max_read_ct,
               count(CASE WHEN vt <= NOW() AND read_ct = 0 THEN 1 END) AS visible_unread_length
             FROM pgmq.#{qtable}
@@ -1229,6 +1233,7 @@ module Pgbus
             q_summary.queue_visible_length,
             q_summary.newest_msg_age_sec,
             q_summary.oldest_msg_age_sec,
+            q_summary.oldest_claimable_age_sec,
             q_summary.max_read_ct,
             q_summary.visible_unread_length,
             all_metrics.total_messages
@@ -1241,7 +1246,9 @@ module Pgbus
           name: queue_name,
           queue_length: row["queue_length"].to_i,
           queue_visible_length: row["queue_visible_length"].to_i,
+          parked_length: row["queue_length"].to_i - row["queue_visible_length"].to_i,
           oldest_msg_age_sec: row["oldest_msg_age_sec"]&.to_i,
+          oldest_claimable_age_sec: row["oldest_claimable_age_sec"]&.to_i,
           newest_msg_age_sec: row["newest_msg_age_sec"]&.to_i,
           total_messages: row["total_messages"].to_i,
           max_read_ct: row["max_read_ct"]&.to_i,

data/lib/pgbus/web/metrics_serializer.rb

@@ -54,6 +54,15 @@ module Pgbus
           end
         end
 
+        gauge(lines, "pgbus_queue_oldest_claimable_age_seconds",
+              "Age of the oldest message eligible for pickup (visibility timeout elapsed)") do
+          queues.filter_map do |q|
+            next unless q[:oldest_claimable_age_sec]
+
+            [q[:oldest_claimable_age_sec], { queue: q[:name] }]
+          end
+        end
+
         gauge(lines, "pgbus_queue_paused", "Whether the queue is paused (1) or active (0)") do
           queues.map { |q| [q[:paused] ? 1 : 0, { queue: q[:name] }] }
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.13.3
 platform: ruby
 authors:
 - Mikael Henriksson