From fbbfc623e16ed97176c0ccf0ebc534d118e9f252 Mon Sep 17 00:00:00 2001
From: Alex Friedman <alexf01@gmail.com>
Date: Wed, 26 Feb 2025 19:59:59 +0200
Subject: [PATCH v2] Clarify possibility of ephemeral discrepancies between
 state and wait_event in pg_stat_activity.

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

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 9178f1d34ef..de49769d407 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1016,7 +1016,11 @@ 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 the view's columns,
+    for example between <structfield>wait_event</structfield> and
+    <structfield>state</structfield>, or between <structfield>state</structfield> and
+    <structfield>query_id</structfield>, are possible by nature.
    </para>
   </note>
 
-- 
2.41.0