[Alex Friedman <alexf01@gmail.com>]

Hi,

This small doc change patch is following up on a past discussion about 
discrepancies between state and wait_event in pg_stat_activity:

https://www.postgresql.org/message-id/flat/ab1c0a7d-e789-5ef5-1180-42708ac6fe2d%40postgrespro.ru


As this kind of question is raised by PG users from time to time, the goal is to 
clarify that such discrepancies are to be expected. The attached patch reuses 
Robert Haas's eloquent wording from his response in the above thread. I've tried 
to keep it short and to the point, but it can be made more verbose if needed.


Best regards,

Alex Friedman

Attachments:

v1-0001-Clarify-possibility-of-ephemeral-discrepancies-be.patch (text/plain, 1.2K) download
From 3cab620d67d200ff4ccb1870f63cbf75a50d0df6 Mon Sep 17 00:00:00 2001
From: Alex Friedman <alexf01@gmail.com>
Date: Wed, 26 Feb 2025 19:59:59 +0200
Subject: [PATCH v1] Clarify possibility of ephemeral discrepancies between
 state and wait_event in pg_stat_activity.

---
 doc/src/sgml/monitoring.sgml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 9178f1d34ef..57fcd8ab52b 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1016,7 +1016,9 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
     it may or may not be <literal>waiting</literal> on some event.  If the state
     is <literal>active</literal> and <structfield>wait_event</structfield> is non-null, it
     means that a query is being executed, but is being blocked somewhere
-    in the system.
+    in the system. To keep the reporting low-overhead, the system uses very lightweight
+    synchronization. As a result, ephemeral discrepancies between <structfield>wait_event</structfield>
+    and <structfield>state</structfield> are possible by nature.
    </para>
   </note>
 
-- 
2.41.0