Adding pg_stat_muiltixact view to allow membership usage telemetry

Author: andrew-j-metronome

doc/src/sgml/monitoring.sgml

@@ -278,8 +278,9 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
    shared memory statistics) in the views
    <structname>pg_stat_xact_all_tables</structname>,
    <structname>pg_stat_xact_sys_tables</structname>,
-   <structname>pg_stat_xact_user_tables</structname>, and
-   <structname>pg_stat_xact_user_functions</structname>.  These numbers do not act as
+   <structname>pg_stat_xact_user_tables</structname>,
+   <structname>pg_stat_xact_user_functions</structname> and
+   <structname>pg_stat_multixact</structname>.  These numbers do not act as
    stated above; instead they update continuously throughout the transaction.
   </para>
 
@@ -493,6 +494,14 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      </entry>
      </row>
 
+     <row>
+      <entry><structname>pg_stat_multixact</structname><indexterm><primary>pg_stat_multixact</primary></indexterm></entry>
+      <entry>One row only, showing statistics about multixact membership consumption. See
+       <link linkend="monitoring-pg-stat-multixact-view">
+       <structname>pg_stat_multixact</structname></link> for details.
+      </entry>
+     </row>
+
      <row>
       <entry><structname>pg_stat_replication_slots</structname><indexterm><primary>pg_stat_replication_slots</primary></indexterm></entry>
       <entry>One row per replication slot, showing statistics about the
@@ -3254,6 +3263,56 @@ description | Waiting for a newly initialized WAL file to reach durable storage
   </para>
  </sect2>
 
+ <sect2 id="monitoring-pg-stat-multixact-view">
+   <title><structname>pg_stat_multixact</structname></title>
+
+   <indexterm>
+     <primary>pg_stat_multixact</primary>
+   </indexterm>
+
+   <para>
+     The <structname>pg_stat_multixact</structname> view will always have
+     a single row, containing data about multixact membership consumption
+     of the cluster.
+   </para>
+
+   <table id="pg-stat-multixact-view" xreflabel="pg_stat_multixact">
+     <title><structname>pg_stat_multixact</structname> View</title>
+   <tgroup cols="1">
+    <thead>
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       Column Type
+      </para>
+      <para>
+       Description
+      </para></entry>
+     </row>
+    </thead>
+
+    <tbody>
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>update_timestamp</structfield> <type>timestamp with time zone</type>
+      </para>
+      <para>
+       Time at which the statistic was last updated.
+      </para></entry>
+     </row>
+
+     <row>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>members</structfield> <type>bigint</type>
+      </para>
+      <para>
+       Number of multixact members in use.
+      </para></entry>
+     </row>
+    </tbody>
+   </tgroup>
+   </table>
+ </sect2>
+
  <sect2 id="monitoring-pg-stat-wal-view">
    <title><structname>pg_stat_wal</structname></title>
 

src/backend/access/transam/multixact.c

@@ -1259,6 +1259,12 @@ GetNewMultiXactId(int nmembers, MultiXactOffset *offset)
 
 	MultiXactState->nextOffset += nmembers;
 
+	/*
+	 * Record multixact membership space telemetry while we have the lock. We
+	 * do not use the saved variables above because they are stale.
+	 */
+	pgstat_update_multixact_stats(MultiXactState->nextOffset - MultiXactState->oldestOffset);
+
 	LWLockRelease(MultiXactGenLock);
 
 	debug_elog4(DEBUG2, "GetNew: returning %u offset %u", result, *offset);
@@ -2927,6 +2933,9 @@ MultiXactMemberFreezeThreshold(void)
 	if (!ReadMultiXactCounts(&multixacts, &members))
 		return 0;
 
+	/* Record the number of multixact members. */
+	pgstat_update_multixact_stats(members);
+
 	/* If member space utilization is low, no special action is required. */
 	if (members <= MULTIXACT_MEMBER_SAFE_THRESHOLD)
 		return autovacuum_multixact_freeze_max_age;

src/backend/catalog/system_views.sql

@@ -1209,6 +1209,11 @@ CREATE VIEW pg_stat_wal AS
         w.stats_reset
     FROM pg_stat_get_wal() w;
 
+CREATE VIEW pg_stat_multixact AS
+    SELECT
+        pg_stat_get_multixact_update_timestamp() AS update_timestamp,
+        pg_stat_get_multixact_members() AS members;
+
 CREATE VIEW pg_stat_progress_analyze AS
     SELECT
         S.pid AS pid, S.datid AS datid, D.datname AS datname,

src/backend/utils/activity/Makefile

@@ -26,6 +26,7 @@ OBJS = \
 	pgstat_database.o \
 	pgstat_function.o \
 	pgstat_io.o \
+	pgstat_multixact.o \
 	pgstat_relation.o \
 	pgstat_replslot.o \
 	pgstat_shmem.o \

src/backend/utils/activity/meson.build

@@ -11,6 +11,7 @@ backend_sources += files(
   'pgstat_database.c',
   'pgstat_function.c',
   'pgstat_io.c',
+  'pgstat_multixact.c',
   'pgstat_relation.c',
   'pgstat_replslot.c',
   'pgstat_shmem.c',

src/backend/utils/activity/pgstat.c

@@ -480,6 +480,24 @@ static const PgStat_KindInfo pgstat_kind_builtin_infos[PGSTAT_KIND_BUILTIN_SIZE]
 		.reset_all_cb = pgstat_wal_reset_all_cb,
 		.snapshot_cb = pgstat_wal_snapshot_cb,
 	},
+
+	[PGSTAT_KIND_MULTIXACT] = {
+		.name = "multixact",
+
+		.fixed_amount = true,
+		.write_to_file = true,
+
+		.snapshot_ctl_off = offsetof(PgStat_Snapshot, multixact),
+		.shared_ctl_off = offsetof(PgStat_ShmemControl, multixact),
+		.shared_data_off = offsetof(PgStatShared_MultiXact, stats),
+		.shared_data_len = sizeof(((PgStatShared_MultiXact *) 0)->stats),
+
+		.init_shmem_cb = pgstat_multixact_init_shmem_cb,
+		.flush_static_cb = pgstat_flush_multixact_cb,
+		.have_static_pending_cb = pgstat_multixact_have_pending_cb,
+		.reset_all_cb = pgstat_multixact_reset_all_cb,
+		.snapshot_cb = pgstat_multixact_snapshot_cb,
+	},
 };
 
 /*

src/backend/utils/activity/pgstat_multixact.c

@@ -0,0 +1,133 @@
+/* -------------------------------------------------------------------------
+ *
+ * pgstat_multixact.c
+ *	  Implementation of multixact statistics.
+ *
+ * This file contains the implementation of multixact statistics. It is kept
+ * separate from pgstat.c to enforce the line between the statistics access /
+ * storage implementation and the details about individual types of
+ * statistics.
+ *
+ * Copyright (c) 2001-2025, PostgreSQL Global Development Group
+ *
+ * IDENTIFICATION
+ *	  src/backend/utils/activity/pgstat_multixact.c
+ * -------------------------------------------------------------------------
+ */
+
+#include "postgres.h"
+#include "utils/pgstat_internal.h"
+#include "utils/timestamp.h"
+
+static bool have_multixact_stats = false;
+
+/*
+ * pgstat_fetch_stat_multixact()
+ *
+ * Support function for the SQL-callable pgstat* functions. Returns
+ * a pointer to the multixact statistics struct.
+ */
+PgStat_MultiXactStats *
+pgstat_fetch_stat_multixact(void)
+{
+	pgstat_snapshot_fixed(PGSTAT_KIND_MULTIXACT);
+
+	return &pgStatLocal.snapshot.multixact;
+}
+
+bool
+pgstat_multixact_have_pending_cb(void)
+{
+	return have_multixact_stats;
+}
+
+void
+pgstat_update_multixact_stats(uint32 nmembers)
+{
+	PgStat_MultiXactStats * local_stats;
+	TimestampTz now;
+
+	now = GetCurrentTimestamp();
+	local_stats = &pgStatLocal.snapshot.multixact;
+	local_stats->num_members_used = nmembers;
+	local_stats->stat_update_timestamp = now;
+	have_multixact_stats = true;
+}
+
+/*
+ * Report multixact statistics. If nowait is true, then this function
+ * will return if the lock is currently being held.
+ *
+ * This function returns true if the lock could not be acquired. Otherwise, false.
+ */
+bool
+pgstat_flush_multixact_cb(bool nowait)
+{
+	PgStatShared_MultiXact	*stats_shmem;
+	LWLock					*shared_lock;
+
+	stats_shmem = &pgStatLocal.shmem->multixact;
+	shared_lock = &pgStatLocal.shmem->multixact.lock;
+
+	// Since this statistic is a gauge, we have to check timestamps
+	// of the shared statistic and the local statistic. If ours is
+	// larger, then we can overwrite the shared statistic.
+	if (!nowait)
+		LWLockAcquire(shared_lock, LW_EXCLUSIVE);
+	else if (!LWLockConditionalAcquire(shared_lock, LW_EXCLUSIVE))
+		return true;
+
+	if (pgStatLocal.snapshot.multixact.stat_update_timestamp <= stats_shmem->stats.stat_update_timestamp)
+	{
+		// Return if our stats are <= the latest update.
+		LWLockRelease(shared_lock);
+		have_multixact_stats = false;
+		return false;
+	}
+
+	// Update multixact member usage and latest timestamp.
+	stats_shmem->stats.num_members_used = pgStatLocal.snapshot.multixact.num_members_used;
+	stats_shmem->stats.stat_update_timestamp = pgStatLocal.snapshot.multixact.stat_update_timestamp;
+	have_multixact_stats = false;
+
+	LWLockRelease(shared_lock);
+	return false;
+}
+
+void
+pgstat_multixact_init_shmem_cb(void *stats)
+{
+	PgStatShared_MultiXact *stats_shmem;
+
+	stats_shmem = (PgStatShared_MultiXact *) stats;
+	LWLockInitialize(&stats_shmem->lock, LWTRANCHE_PGSTATS_DATA);
+}
+
+void
+pgstat_multixact_snapshot_cb(void)
+{
+	PgStat_MultiXactStats *local_snapshot;
+	PgStatShared_MultiXact *stats_shmem;
+
+	local_snapshot = &pgStatLocal.snapshot.multixact;
+	stats_shmem = &pgStatLocal.shmem->multixact;
+
+	LWLockAcquire(&stats_shmem->lock, LW_SHARED);
+	if (local_snapshot->stat_update_timestamp < stats_shmem->stats.stat_update_timestamp)
+	{
+		local_snapshot->stat_update_timestamp = stats_shmem->stats.stat_update_timestamp;
+		local_snapshot->num_members_used = stats_shmem->stats.num_members_used;
+	}
+	LWLockRelease(&stats_shmem->lock);
+}
+
+void
+pgstat_multixact_reset_all_cb(TimestampTz ts)
+{
+	PgStatShared_MultiXact *stats_shmem;
+
+	stats_shmem = &pgStatLocal.shmem->multixact;
+	LWLockAcquire(&stats_shmem->lock, LW_EXCLUSIVE);
+	memset(&stats_shmem->stats, 0, sizeof(stats_shmem->stats));
+	LWLockRelease(&stats_shmem->lock);
+}

src/backend/utils/adt/pgstatfuncs.c

@@ -1304,6 +1304,18 @@ pg_stat_get_buf_alloc(PG_FUNCTION_ARGS)
 	PG_RETURN_INT64(pgstat_fetch_stat_bgwriter()->buf_alloc);
 }
 
+Datum
+pg_stat_get_multixact_members(PG_FUNCTION_ARGS)
+{
+	PG_RETURN_INT64(pgstat_fetch_stat_multixact()->num_members_used);
+}
+
+Datum
+pg_stat_get_multixact_update_timestamp(PG_FUNCTION_ARGS)
+{
+	PG_RETURN_TIMESTAMPTZ(pgstat_fetch_stat_multixact()->stat_update_timestamp);
+}
+
 /*
 * When adding a new column to the pg_stat_io view and the
 * pg_stat_get_backend_io() function, add a new enum value here above
@@ -1883,6 +1895,7 @@ pg_stat_reset_shared(PG_FUNCTION_ARGS)
 		XLogPrefetchResetStats();
 		pgstat_reset_of_kind(PGSTAT_KIND_SLRU);
 		pgstat_reset_of_kind(PGSTAT_KIND_WAL);
+		pgstat_reset_of_kind(PGSTAT_KIND_MULTIXACT);
 
 		PG_RETURN_VOID();
 	}
@@ -1903,6 +1916,8 @@ pg_stat_reset_shared(PG_FUNCTION_ARGS)
 		pgstat_reset_of_kind(PGSTAT_KIND_SLRU);
 	else if (strcmp(target, "wal") == 0)
 		pgstat_reset_of_kind(PGSTAT_KIND_WAL);
+	else if (strcmp(target, "multixact") == 0)
+		pgstat_reset_of_kind(PGSTAT_KIND_MULTIXACT);
 	else
 		ereport(ERROR,
 				(errcode(ERRCODE_INVALID_PARAMETER_VALUE),

src/include/catalog/pg_proc.dat

@@ -5992,6 +5992,14 @@
   proname => 'pg_stat_get_buf_alloc', provolatile => 's', proparallel => 'r',
   prorettype => 'int8', proargtypes => '', prosrc => 'pg_stat_get_buf_alloc' },
 
+{ oid => '9999', descr => 'statistics: number of multixact members in use',
+  proname => 'pg_stat_get_multixact_members', provolatile => 's', proparallel => 'r',
+  prorettype => 'int8', proargtypes => '', prosrc => 'pg_stat_get_multixact_members' },
+{ oid => '9998', descr => 'statistics: timestamp of the last time the multixact members count was updated',
+  proname => 'pg_stat_get_multixact_update_timestamp', provolatile => 's',
+  proparallel => 'r', prorettype => 'timestamptz', proargtypes => '',
+  prosrc => 'pg_stat_get_multixact_update_timestamp' },
+
 { oid => '6214', descr => 'statistics: per backend type IO statistics',
   proname => 'pg_stat_get_io', prorows => '30', proretset => 't',
   provolatile => 'v', proparallel => 'r', prorettype => 'record',

src/include/pgstat.h

@@ -265,6 +265,19 @@ typedef struct PgStat_CheckpointerStats
 	TimestampTz stat_reset_timestamp;
 } PgStat_CheckpointerStats;
 
+/* --------
+ * PgStat_MultiXactStats		MultiXact stats
+ *
+ * This struct should contain only actual event counters, because we make use
+ * of pg_memory_is_all_zeros() to detect whether there are any stats updates
+ * to apply.
+ * ---------
+ */
+typedef struct PgStat_MultiXactStats
+{
+	PgStat_Counter num_members_used;
+	TimestampTz stat_update_timestamp;
+} PgStat_MultiXactStats;
 
 /*
  * Types related to counting IO operations
@@ -579,6 +592,12 @@ extern void pgstat_report_checkpointer(void);
 extern PgStat_CheckpointerStats *pgstat_fetch_stat_checkpointer(void);
 
 
+/*
+ * Functions in pgstat_multixact.c
+ */
+extern PgStat_MultiXactStats *pgstat_fetch_stat_multixact(void);
+extern void pgstat_update_multixact_stats(uint32 nmembers);
+
 /*
  * Functions in pgstat_io.c
  */