wait_event_timing: reviewable patch series (stats / DSA / trace)

.github/workflows/pg-ci.yml

@@ -499,10 +499,17 @@ jobs:
 
       - name: Configure
         shell: *su_postgres_shell
+        # --enable-wait-event-timing is added on this one task so the
+        # wait-event-timing build path -- including the expected output at
+        # src/test/regress/expected/wait_event_timing.out -- is exercised by
+        # CI on every push.  The other tasks build without the flag, so the
+        # stub path and its alternate output wait_event_timing_1.out stay
+        # covered as well.
         run: |
           ./configure \
             --enable-cassert --enable-injection-points --enable-debug \
             --enable-tap-tests --enable-nls \
+            --enable-wait-event-timing \
             --with-segsize-blocks=6 \
             --with-libnuma \
             --with-liburing \

configure

@@ -850,6 +850,7 @@ enable_debug
 enable_profiling
 enable_coverage
 enable_dtrace
+enable_wait_event_timing
 enable_tap_tests
 enable_injection_points
 with_blocksize
@@ -1551,6 +1552,8 @@ Optional Features:
   --enable-profiling      build with profiling enabled
   --enable-coverage       build with coverage testing instrumentation
   --enable-dtrace         build with DTrace support
+  --enable-wait-event-timing
+                          build with wait event timing instrumentation
   --enable-tap-tests      enable TAP tests (requires Perl and IPC::Run)
   --enable-injection-points
                           enable injection points (for testing)
@@ -3633,6 +3636,35 @@ fi
 
 
 
+#
+# --enable-wait-event-timing adds wait event timing instrumentation
+#
+
+
+# Check whether --enable-wait-event-timing was given.
+if test "${enable_wait_event_timing+set}" = set; then :
+  enableval=$enable_wait_event_timing;
+  case $enableval in
+    yes)
+
+$as_echo "#define USE_WAIT_EVENT_TIMING 1" >>confdefs.h
+
+      ;;
+    no)
+      :
+      ;;
+    *)
+      as_fn_error $? "no argument expected for --enable-wait-event-timing option" "$LINENO" 5
+      ;;
+  esac
+
+else
+  enable_wait_event_timing=no
+
+fi
+
+
+
 #
 # TAP tests
 #

configure.ac

@@ -225,6 +225,14 @@ fi
 AC_SUBST(DTRACEFLAGS)])
 AC_SUBST(enable_dtrace)
 
+#
+# --enable-wait-event-timing adds wait event timing instrumentation
+#
+PGAC_ARG_BOOL(enable, wait-event-timing, no,
+              [build with wait event timing instrumentation],
+              [AC_DEFINE([USE_WAIT_EVENT_TIMING], 1,
+                         [Define to 1 to build with wait event timing. (--enable-wait-event-timing)])])
+
 #
 # TAP tests
 #

contrib/test_decoding/expected/twophase.out

@@ -227,6 +227,31 @@ SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'inc
  COMMIT PREPARED 'test_toast_table_access'
 (1 row)
 
+-- Test that an empty prepared transaction should not be decoded, whether it
+-- is committed or rolled back.
+BEGIN;
+SELECT * FROM test_prepared1 WHERE id = 1 FOR SHARE;
+ id | data 
+----+------
+  1 | 
+(1 row)
+
+PREPARE TRANSACTION 'test_empty_transaction';
+COMMIT PREPARED 'test_empty_transaction';
+BEGIN;
+SELECT * FROM test_prepared1 WHERE id = 1 FOR SHARE;
+ id | data 
+----+------
+  1 | 
+(1 row)
+
+PREPARE TRANSACTION 'test_empty_transaction';
+ROLLBACK PREPARED 'test_empty_transaction';
+SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'include-xids', '0', 'skip-empty-xacts', '1');
+ data 
+------
+(0 rows)
+
 -- Test 8:
 -- cleanup and make sure results are also empty
 DROP TABLE test_prepared1;

contrib/test_decoding/sql/twophase.sql

@@ -125,6 +125,18 @@ COMMIT PREPARED 'test_toast_table_access';
 -- consume commit prepared
 SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'include-xids', '0', 'skip-empty-xacts', '1', 'stream-changes', '1');
 
+-- Test that an empty prepared transaction should not be decoded, whether it
+-- is committed or rolled back.
+BEGIN;
+SELECT * FROM test_prepared1 WHERE id = 1 FOR SHARE;
+PREPARE TRANSACTION 'test_empty_transaction';
+COMMIT PREPARED 'test_empty_transaction';
+BEGIN;
+SELECT * FROM test_prepared1 WHERE id = 1 FOR SHARE;
+PREPARE TRANSACTION 'test_empty_transaction';
+ROLLBACK PREPARED 'test_empty_transaction';
+SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'include-xids', '0', 'skip-empty-xacts', '1');
+
 -- Test 8:
 -- cleanup and make sure results are also empty
 DROP TABLE test_prepared1;

doc/src/sgml/catalogs.sgml

@@ -8893,7 +8893,11 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <para>
        Remote LSN of the state change used for synchronization coordination
        when in <literal>s</literal> or <literal>r</literal> states,
-       otherwise null
+       otherwise null. For sequences, this instead holds the publisher
+       sequence's page LSN as of the last synchronization, which does not
+       track replication progress the way it does for tables; see
+       <xref linkend="sequences-out-of-sync"/> for how it is used to detect
+       out-of-sync sequences.
       </para></entry>
      </row>
     </tbody>

doc/src/sgml/config.sgml

@@ -9154,6 +9154,112 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-wait-event-capture" xreflabel="wait_event_capture">
+      <term><varname>wait_event_capture</varname> (<type>enum</type>)
+      <indexterm>
+       <primary><varname>wait_event_capture</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Controls collection of wait event timing instrumentation.  Requires
+        the server to be compiled with
+        <option>--enable-wait-event-timing</option>.  Possible values are
+        <literal>off</literal> (the default), <literal>stats</literal>, and
+        <literal>trace</literal>; each level is a strict superset of the
+        previous one.
+       </para>
+       <para>
+        At <literal>stats</literal>, the server records per-backend wait
+        event statistics &mdash; counts, total and average durations, and a
+        log2 duration histogram &mdash; visible in the
+        <link linkend="monitoring-pg-stat-wait-event-timing-view">
+        <structname>pg_stat_wait_event_timing</structname></link> view.
+        Two <function>clock_gettime()</function>-grade timestamps are taken
+        around every wait event transition, costing roughly
+        40&ndash;100&nbsp;ns each on modern hardware; while
+        <varname>wait_event_capture</varname> is <literal>off</literal> the
+        hot path adds only a single predictable branch.
+       </para>
+       <para>
+        At <literal>trace</literal>, the server additionally records every
+        individual wait event, together with query-attribution markers,
+        into a per-session ring buffer exposed via the
+        <link linkend="monitoring-pg-backend-wait-event-trace-view">
+        <structname>pg_backend_wait_event_trace</structname></link> view.
+        The ring is allocated lazily from dynamic shared memory on first
+        use (default 4&nbsp;MB per backend; see
+        <xref linkend="guc-wait-event-trace-ring-size"/>), so only
+        sessions that enable trace pay the per-ring memory cost.  Query
+        attribution &mdash; matching each wait to the query that incurred
+        it &mdash; requires both <xref linkend="guc-track-activities"/> and
+        <xref linkend="guc-compute-query-id"/>; a warning is logged if
+        either is missing when trace is enabled.
+       </para>
+       <para>
+        Only superusers and users with the appropriate <literal>SET</literal>
+        privilege can change this setting.  Read access to the resulting
+        statistics is controlled separately by membership in the
+        <link linkend="predefined-roles"><literal>pg_read_all_stats</literal></link>
+        role (which the <literal>pg_monitor</literal> role inherits).  To
+        delegate the ability to change the setting to a monitoring role,
+        use <command>GRANT SET ON PARAMETER</command>:
+<programlisting>
+GRANT SET ON PARAMETER wait_event_capture TO pg_monitor;
+</programlisting>
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-wait-event-timing-max-tranches" xreflabel="wait_event_timing_max_tranches">
+      <term><varname>wait_event_timing_max_tranches</varname> (<type>integer</type>)
+      <indexterm>
+       <primary><varname>wait_event_timing_max_tranches</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Sets the maximum number of distinct LWLock tranches whose timing is
+        recorded individually per backend.  PostgreSQL maintains a
+        per-backend hash table mapping each tranche the backend encounters
+        to its histogram; once the table fills, further tranches are
+        counted against <structfield>lwlock_overflow_count</structfield> in
+        <link linkend="monitoring-pg-stat-wait-event-timing-overflow-view">
+        <structname>pg_stat_wait_event_timing_overflow</structname></link>
+        and not individually timed.  Sized at server start; this parameter
+        has no effect on builds compiled without
+        <option>--enable-wait-event-timing</option>.  The default is
+        <literal>192</literal>; raise it if your installation loads many
+        extensions that register their own LWLock tranches and you observe
+        a non-zero <structfield>lwlock_overflow_count</structfield>.  This
+        parameter can only be set at server start.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-wait-event-trace-ring-size" xreflabel="wait_event_trace_ring_size">
+      <term><varname>wait_event_trace_ring_size</varname> (<type>integer</type>)
+      <indexterm>
+       <primary><varname>wait_event_trace_ring_size</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Sets the size of the per-backend ring buffer used at the
+        <literal>trace</literal> level of
+        <xref linkend="guc-wait-event-capture"/>.  Each backend that enables
+        trace allocates a ring of this size from a cluster-wide dynamic
+        shared memory area.  The value must be a power of two; larger rings
+        retain a longer history of wait events before wrapping.  If this
+        parameter is specified without units, it is taken as kilobytes.  The
+        default is <literal>4096</literal> (4&nbsp;MB).  This parameter has
+        no effect on builds compiled without
+        <option>--enable-wait-event-timing</option>, and can only be set at
+        server start.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-track-functions" xreflabel="track_functions">
       <term><varname>track_functions</varname> (<type>enum</type>)
       <indexterm>

doc/src/sgml/func/func-string.sgml

@@ -753,6 +753,23 @@
        </para></entry>
       </row>
 
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>getdatabaseencoding</primary>
+        </indexterm>
+        <function>getdatabaseencoding</function> ( )
+        <returnvalue>name</returnvalue>
+       </para>
+       <para>
+        Returns current database encoding name.
+       </para>
+       <para>
+        <literal>getdatabaseencoding()</literal>
+        <returnvalue>UTF8</returnvalue>
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>

doc/src/sgml/high-availability.sgml

@@ -920,7 +920,10 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
      <structname>pg_stat_wal_receiver</structname></link> view.  A large
      difference between <function>pg_last_wal_replay_lsn</function> and the
      view's <literal>flushed_lsn</literal> indicates that WAL is being
-     received faster than it can be replayed.
+     received faster than it can be replayed.  Recovery state and replay
+     progress can also be monitored via the
+     <link linkend="monitoring-pg-stat-recovery-view">
+     <structname>pg_stat_recovery</structname></link> view.
     </para>
    </sect3>
   </sect2>
@@ -1801,9 +1804,11 @@ postgres=# WAIT FOR LSN '0/306EE20';
     (In server versions before 14, the <varname>in_hot_standby</varname>
     parameter did not exist; a workable substitute method for older servers
     is <command>SHOW transaction_read_only</command>.)  In addition, a set of
-    functions (<xref linkend="functions-recovery-info-table"/>) allow users to
-    access information about the standby server. These allow you to write
-    programs that are aware of the current state of the database. These
+    functions (<xref linkend="functions-recovery-info-table"/>) and the
+    <link linkend="monitoring-pg-stat-recovery-view">
+    <structname>pg_stat_recovery</structname></link> view allow users to
+    access information about the standby server. These facilities allow you to
+    write programs that are aware of the current state of the database. They
     can be used to monitor the progress of recovery, or to allow you to
     write complex programs that restore the database to particular states.
    </para>

doc/src/sgml/logical-replication.sgml

@@ -1818,6 +1818,13 @@ Included in publications:
    configuration.
   </para>
 
+  <note>
+   <para>
+    Sequence synchronization requires the publisher to be running
+    <productname>PostgreSQL</productname> 19 or later.
+   </para>
+  </note>
+
   <sect2 id="sequence-definition-mismatches">
    <title>Sequence Definition Mismatches</title>
    <para>
@@ -2368,7 +2375,16 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
      <command>ALTER SUBSCRIPTION ... REFRESH SEQUENCES</command></link>
      or by copying the current data from the publisher (perhaps using
      <command>pg_dump</command>) or by determining a sufficiently high value
-     from the tables themselves.
+     from the tables themselves.  Note that
+     <link linkend="sql-altersubscription-params-refresh-sequences">
+     <command>ALTER SUBSCRIPTION ... REFRESH SEQUENCES</command></link> only
+     re-synchronizes sequences that are already known to the subscription
+     (see <xref linkend="logical-replication-sequences"/>); in particular, it
+     requires the publisher to be running <productname>PostgreSQL</productname>
+     19 or later. Before relying on it to prepare for a switchover or
+     failover, confirm that the publisher's version supports sequence
+     replication and that the sequences of interest are already known to the
+     subscription.
     </para>
    </listitem>