Address review_6.md issue #9: drop speculative consumer naming in docs/comments

review_6.md issue #9 flagged that documentation comments
over-reference "future ASH/AWR/10046-style background workers"
as justification for the cross-backend trace surface.  On
-hackers this reads as speculative -- naming hypothetical
consumers to motivate present code.  PG style prefers factual
statements about what the code does, with neutral framing for
consumers ("any extension that reads via the snapshot pattern").

The framing is also now doubly stale: since review_6 was
written we landed pg_get_wait_event_trace (review_6.md issue
#1) as the in-tree cross-backend consumer.  The "future" tense
is wrong as well as speculative.

Sweep through wait_event_timing.h, wait_event_timing.c, and
monitoring.sgml.  In each speculative reference replace the
"future ASH/AWR/10046-style background workers" phrasing with
neutral framing that:

  * names the in-tree consumer (pg_get_wait_event_trace) where
    that is what callers should use today,
  * refers to "extensions following the snapshot pattern
    documented on WaitEventTraceControl" for the
    direct-shared-memory case,
  * drops the speculative consumer enumeration entirely.

References to "10046-style trace" as a descriptive label for
the technique (e.g. "Per-session wait event trace ring buffer
(10046-style)" on WaitEventTraceState) are retained -- that is
a recognised term for the per-session-event-trace
profiling style, used here as a descriptor of the design, not
as a forward-looking promise about a particular consumer.

Files touched:

  * doc/src/sgml/monitoring.sgml: pg_backend_wait_event_trace
    cross-backend-tools paragraph, pg_get_wait_event_trace
    description, and pg_stat_clear_orphaned_wait_event_rings
    description.
  * src/include/utils/wait_event_timing.h: slot-lifecycle
    comment block (3 spots).
  * src/backend/utils/activity/wait_event_timing.c:
    wait_event_trace_before_shmem_exit doc, the
    pg_backend_wait_event_trace SRF doc, the
    pg_get_wait_event_trace SRF doc, and the
    pg_stat_clear_orphaned_wait_event_rings doc.

No code change.  Pure documentation rewrite.

Builds clean in both --enable-wait-event-timing and stub
configurations.  Main regress (249 tests) and
test_wait_event_stress TAP (15 subtests) pass on the timing
build; main regress (249 tests) passes on the stub build.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: DmitryNFomin

doc/src/sgml/monitoring.sgml

@@ -4128,16 +4128,19 @@ ORDER  BY b.bucket_idx;
   </para>
 
   <para>
-   Cross-backend monitoring tools &mdash; future Active Session
-   History, Automatic Workload Repository, or 10046-style
-   trace-replay background workers that read wait events losslessly
-   from every backend's ring &mdash; should <emphasis>not</emphasis>
-   consume through this view.  The underlying SQL function returns only the
-   calling backend's own ring; a background worker invoking
+   Cross-backend monitoring tools &mdash; extensions and background
+   workers that read wait events losslessly from every backend's
+   ring &mdash; should <emphasis>not</emphasis> consume through this
+   view.  The in-tree cross-backend reader is
+   <function>pg_get_wait_event_trace</function>
+   (see <xref linkend="monitoring-stats-funcs"/>); the underlying
+   per-session SQL function returns only the calling backend's own
+   ring, so a background worker invoking
    <command>SELECT * FROM pg_backend_wait_event_trace</command> via
    SPI would receive only its own (typically empty) ring, not the
-   target backend's data.  Such tools must instead use the
-   shared-memory snapshot pattern documented on
+   target backend's data.  External tools that need cross-backend
+   access without going through SQL use the shared-memory snapshot
+   pattern documented on
    <structname>WaitEventTraceControl</structname> in
    <filename>src/include/utils/wait_event_timing.h</filename>:
    snapshot <structfield>trace_slots[procNumber].generation</structfield>,
@@ -4168,9 +4171,9 @@ ORDER  BY b.bucket_idx;
    procnumbers.  The lifecycle change matters for short-lived
    backends that exit before any monitoring tool has read their
    data: parallel workers in particular exit in milliseconds at
-   end-of-parallel-query, well below typical sampling cadences,
-   and without orphan-persistence their final waits would be
-   lost.  Orphaned rings are reclaimed automatically when a new
+   end-of-parallel-query, well below typical reader polling
+   intervals, and without orphan-persistence their final waits
+   would be lost.  Orphaned rings are reclaimed automatically when a new
    backend takes over the same <literal>procNumber</literal>
    slot, and the DBA can force a sweep at any time via
    <function>pg_stat_clear_orphaned_wait_event_rings</function>.
@@ -6405,10 +6408,10 @@ ORDER  BY b.bucket_idx;
        </para>
        <para>
         This is the canonical cross-backend reader.  External
-        monitoring background workers (ASH/AWR/10046-style ring
-        readers) should follow the same snapshot pattern documented
-        on <structname>WaitEventTraceControl</structname> in
-        <filename>src/include/utils/wait_event_timing.h</filename>;
+        monitoring extensions that need cross-backend access without
+        going through SQL should follow the same snapshot pattern
+        documented on <structname>WaitEventTraceControl</structname>
+        in <filename>src/include/utils/wait_event_timing.h</filename>;
         this function serves as both the reference implementation and
         a DBA-facing diagnostic tool.  The
         <parameter>procnumber</parameter> argument can be obtained
@@ -6524,8 +6527,10 @@ SELECT * FROM pg_get_wait_event_trace(
         When a backend that had <varname>wait_event_capture</varname> =
         <literal>trace</literal> exits, its ~4 MB trace ring is
         intentionally <emphasis>not</emphasis> freed at exit so that
-        cross-backend monitoring tools (ASH/AWR/10046-style background
-        workers) can still read the dying backend's final waits.  The
+        cross-backend consumers
+        (<function>pg_get_wait_event_trace</function> and extensions
+        following the snapshot pattern) can still read the dying
+        backend's final waits.  The
         memory is reclaimed lazily: in the common case, the ring is
         freed automatically when a new backend takes over the same
         <literal>procNumber</literal> slot.  This function is the

src/backend/utils/activity/wait_event_timing.c

@@ -1111,12 +1111,14 @@ wait_event_trace_ensure_dsa(void)
  * dsm_backend_shutdown() detaches the DSA.
  *
  * Crucially, we do NOT free the ring here.  The ring stays allocated in
- * DSA so that cross-backend consumers (ASH/AWR/10046-style monitoring
- * background workers, future or external) can read the dying backend's
- * final waits -- the original "free at exit" design lost data the
- * instant a worker terminated, which was particularly bad for parallel
- * workers exiting in milliseconds at end-of-parallel-query.  See the
- * lifecycle comment on WaitEventTraceControl for the full design
+ * DSA so that cross-backend consumers -- the in-tree
+ * pg_get_wait_event_trace SRF and any extension following the
+ * snapshot pattern documented on WaitEventTraceControl -- can read
+ * the dying backend's final waits.  The original "free at exit"
+ * design lost data the instant a worker terminated, which was
+ * particularly bad for parallel workers exiting in milliseconds at
+ * end-of-parallel-query.  See the lifecycle comment on
+ * WaitEventTraceControl for the full design
  * rationale and the bounded-memory cost we accept in exchange.
  *
  * The ORPHANED slot is reclaimed in one of two ways:
@@ -2215,9 +2217,11 @@ pg_stat_get_wait_event_timing(PG_FUNCTION_ARGS)
  * own-session diagnostics from psql.
  *
  * This SRF is NOT the path for cross-backend monitoring tools --
- * cross-backend readers (ASH/AWR/10046-style background workers that
- * consume the per-backend trace rings) should NOT call this function
- * via SPI.
+ * cross-backend readers should use pg_get_wait_event_trace for SQL
+ * access, or follow the shared-memory snapshot pattern documented
+ * on WaitEventTraceControl in wait_event_timing.h to consume the
+ * per-backend trace rings directly.  They should NOT call this
+ * function via SPI.
  * It is hard-coded to return only the calling backend's own ring,
  * so a bgworker calling SELECT * FROM pg_backend_wait_event_trace
  * would get only the bgworker's own (typically empty) ring, not the
@@ -2738,8 +2742,8 @@ emit_wait_event_trace_for_procnumber(int procNumber, ReturnSetInfo *rsinfo)
  * ring allocated in DSA in ORPHANED state, and this function reads it
  * until either a new backend takes over the same procNumber or the
  * DBA calls pg_stat_clear_orphaned_wait_event_rings().  External
- * monitoring background workers (ASH/AWR/10046-style readers) follow
- * the same snapshot pattern documented on WaitEventTraceControl in
+ * extensions that need cross-backend access follow the same
+ * snapshot pattern documented on WaitEventTraceControl in
  * wait_event_timing.h; this function serves as both the reference
  * implementation and a DBA-facing diagnostic tool.
  *
@@ -3075,8 +3079,10 @@ pg_stat_reset_wait_event_timing_all(PG_FUNCTION_ARGS)
  * Why this exists.  When a backend that had wait_event_capture = trace
  * exits, we deliberately do NOT free its ~4 MB trace ring (see the
  * lifecycle discussion on WaitEventTraceControl): the data must remain
- * readable by cross-backend consumers (ASH/AWR/10046-style monitoring
- * background workers), and an exit-time dsa_free would defeat that.
+ * readable by cross-backend consumers -- the in-tree
+ * pg_get_wait_event_trace SRF and any extension following the
+ * snapshot pattern on WaitEventTraceControl -- and an exit-time
+ * dsa_free would defeat that.
  * The reclaim instead happens lazily in two places:
  *
  *   (a) wait_event_trace_clear_orphan_at_init(): when a new backend

src/include/utils/wait_event_timing.h

@@ -361,8 +361,10 @@ typedef struct WaitEventTraceState
  * backend exits we deliberately do NOT free its ring.  Instead we
  * transition the slot to ORPHANED and leave the ring allocated in DSA.
  * That preserves trace data past backend exit so it remains readable by
- * cross-backend consumers (ASH/AWR/10046-style monitoring background
- * workers) -- the original per-backend-ring design lost data the
+ * cross-backend consumers: the in-tree pg_get_wait_event_trace SRF and
+ * any extension that follows the snapshot pattern documented on
+ * WaitEventTraceControl below.  The original per-backend-ring design
+ * lost data the
  * instant a parallel worker (or any short-lived backend) terminated,
  * because the worker's before_shmem_exit callback ran dsa_free before
  * any consumer could observe the final waits.  See "Slot lifecycle and
@@ -414,8 +416,9 @@ typedef enum WaitEventTraceSlotState
  * lifecycle plus admin cleanups).
  *
  * state is pg_atomic_uint32 only for cheap unlocked "is this slot
- * worth visiting" probes (e.g. an ASH reader iterating MaxBackends
- * slots and skipping FREE ones without taking the lock).  Authoritative
+ * worth visiting" probes (e.g. an iterating reader that walks all
+ * MaxBackends slots and skips FREE ones without taking the lock).
+ * Authoritative
  * reads of state-and-ring_ptr together MUST be done under
  * WaitEventTraceCtl->lock in LW_SHARED, paired with the
  * generation-snapshot retry loop above.  Writers always hold the lock
@@ -465,10 +468,10 @@ typedef struct WaitEventTraceSlot
  * older design that called dsa_free in the backend's
  * before_shmem_exit callback.  That older design lost trace data the
  * instant a backend exited, because the data was gone before any
- * cross-backend reader (e.g. an ASH/AWR-style ring reader) could observe
- * it.  This was particularly acute for parallel workers, which exit
- * in milliseconds at end-of-parallel-query; a sampler running at
- * 1 Hz would never see their waits.
+ * cross-backend reader could observe it.  This was particularly
+ * acute for parallel workers, which exit in milliseconds at
+ * end-of-parallel-query; a reader polling at 1 Hz would never
+ * observe their waits before the data was freed.
  *
  * Persisting the ring past backend exit pays a bounded memory cost:
  * up to NUM_WAIT_EVENT_TIMING_SLOTS orphaned rings can simultaneously
@@ -495,9 +498,9 @@ typedef struct WaitEventTraceSlot
  * (parallel workers, autovacuum, walsender, all transient backends
  * preserve their data), DSA's lazy-allocation property is preserved
  * (capture=off pays zero memory), and the cross-backend reader
- * pattern below works for the future ASH/AWR/10046 background worker
- * with no further plumbing.  See review_5.md issue #26 for the
- * design discussion.
+ * pattern below is what pg_get_wait_event_trace uses; extensions
+ * implementing similar tools follow the same pattern with no further
+ * plumbing.  See review_5.md issue #26 for the design discussion.
  *
  * External reader pattern (cross-backend consumers)
  * -------------------------------------------------