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