v1-0001-doc-clarify-pg_stat_lock.fastpath_exceeded-scope.patch

From 466f9722650f74d8c1eb747e5254464554a6586f Mon Sep 17 00:00:00 2001
From: TatsuyaKawata <kawatatatsuya0913@gmail.com>
Date: Sat, 13 Jun 2026 12:21:58 +0900
Subject: [PATCH v1] doc: clarify pg_stat_lock.fastpath_exceeded scope

Fast-path locking only applies to relation locks acquired in the weak
modes (AccessShareLock, RowShareLock, RowExclusiveLock), so
fastpath_exceeded is structurally always zero for other lock types
(e.g. transactionid, virtualxid, advisory).  Without this note, users
inspecting the view with SELECT * FROM pg_stat_lock can be confused by
non-relation rows that show fastpath_exceeded = 0 next to non-zero
waits, and wonder whether the counter is broken.
---
 doc/src/sgml/monitoring.sgml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 08d5b824552..2416351507d 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3378,6 +3378,10 @@ description | Waiting for a newly initialized WAL file to reach durable storage
         Number of times a lock of this type could not be acquired via fast path
         because the fast path slot limit was exceeded. Increasing
         <xref linkend="guc-max-locks-per-transaction"/> can reduce this number.
+        Only relation locks acquired in the weak modes
+        (<literal>AccessShareLock</literal>, <literal>RowShareLock</literal>,
+        <literal>RowExclusiveLock</literal>) are eligible for the fast path,
+        so this counter is always zero for other lock types.
        </para>
       </entry>
      </row>
-- 
2.34.1