From 29d7292e7008282de4c9d7c9197b33d28b104f07 Mon Sep 17 00:00:00 2001
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Wed, 8 Nov 2023 16:02:22 -0500
Subject: [PATCH v1 9/9] Make opportunistic freezing heuristic configurable

For the purposes of development, add a guc, opp_freeze_algo, which
determines the heuristic used by vacuum when deciding whether or not to
freeze a page. We anticipate using the average error rate across recent
vacuums to determine whether we need to freeze more or less
aggressively, so add a function to calculate that as well.
---
 src/backend/access/heap/vacuumlazy.c          | 82 ++++++++++++++++++-
 src/backend/utils/activity/pgstat_relation.c  | 70 ++++++++++++++++
 src/backend/utils/init/globals.c              |  1 +
 src/backend/utils/misc/guc_tables.c           | 10 +++
 src/backend/utils/misc/postgresql.conf.sample |  1 +
 src/include/miscadmin.h                       |  1 +
 src/include/pgstat.h                          |  2 +
 7 files changed, 165 insertions(+), 2 deletions(-)

diff --git a/src/backend/access/heap/vacuumlazy.c b/src/backend/access/heap/vacuumlazy.c
index a74516003f..7b128eb3e8 100644
--- a/src/backend/access/heap/vacuumlazy.c
+++ b/src/backend/access/heap/vacuumlazy.c
@@ -203,6 +203,9 @@ static void update_vacuum_error_info(LVRelState *vacrel,
 static void restore_vacuum_error_info(LVRelState *vacrel,
 									  const LVSavedErrInfo *saved_vacrel);
 
+static bool vacuum_opp_freeze(LVRelState *vacrel,
+							  int64 page_age, bool all_visible_all_frozen,
+							  bool prune_emitted_fpi);
 
 /*
  *	heap_vacuum_rel() -- perform VACUUM for one heap relation
@@ -1750,8 +1753,9 @@ lazy_scan_prune(LVRelState *vacrel,
 	 * page all-frozen afterwards (might not happen until final heap pass).
 	 */
 	if (pagefrz.freeze_required || tuples_frozen == 0 ||
-		(prunestate->all_visible && prunestate->all_frozen &&
-		 fpi_before != pgWalUsage.wal_fpi))
+		vacuum_opp_freeze(vacrel, page_age,
+						  prunestate->all_visible && prunestate->all_frozen,
+						  fpi_before != pgWalUsage.wal_fpi))
 	{
 		/*
 		 * We're freezing the page.  Our final NewRelfrozenXid doesn't need to
@@ -3499,3 +3503,77 @@ restore_vacuum_error_info(LVRelState *vacrel,
 	vacrel->offnum = saved_vacrel->offnum;
 	vacrel->phase = saved_vacrel->phase;
 }
+
+#define VAC_FRZ_ERR_THRESHOLD 0.5
+
+/*
+ * Determine whether or not vacuum should opportunistically freeze a page.
+ * Given freeze statistics about the relation contained in LVRelState, whether
+ * or not the page will be able to be marked all visible and all frozen, and
+ * whether or not pruning emitted an FPI, return whether or not the page should
+ * be frozen. The LVRelState should not be modified.
+ */
+static bool
+vacuum_opp_freeze(LVRelState *vacrel,
+				  int64 page_age,
+				  bool all_visible_all_frozen,
+				  bool prune_emitted_fpi)
+{
+	if (opp_freeze_algo == 0)
+		return all_visible_all_frozen && prune_emitted_fpi;
+
+	if (opp_freeze_algo == 1)
+		return all_visible_all_frozen;
+
+	if (opp_freeze_algo == 2)
+	{
+		float		error_rate = 0;
+
+		/*
+		 * if the page LSN is the same as the approximate insert LSN, it was
+		 * modified very recently, so it isn't a good candidate for freezing
+		 */
+		if (page_age == 0)
+			return false;
+
+		/*
+		 * Calculate the average error rate for our past vacuums.
+		 */
+		error_rate = pgstat_frz_error_rate(RelationGetRelid(vacrel->rel));
+
+		/*
+		 * If the error rate is 0, either we don't have enough vacuums yet to
+		 * have data, we haven't frozen anything yet, or we have a perfect
+		 * track record. In all of these cases, freeze the page.
+		 */
+		if (error_rate == 0)
+			return true;
+
+		/*
+		 * Here it may be worth freezing the page if it is older than the
+		 * oldest page scanned so far and a certain number of pages have been
+		 * scanned. Similarly, we could check if the page is younger than the
+		 * youngest page scanned and a certain number of pages have been
+		 * scanned.
+		 */
+
+		/*
+		 * If we have frozen some pages, we can calculate the average page age
+		 * and use that to determine whether or not to freeze the page.
+		 */
+		if (vacrel->pages_frozen > 0)
+		{
+			float		avg_page_age = 0;
+
+			avg_page_age = (float) vacrel->sum_frozen_page_ages /
+				vacrel->pages_frozen;
+
+			if (error_rate > VAC_FRZ_ERR_THRESHOLD &&
+				page_age > avg_page_age)
+				return true;
+
+		}
+	}
+
+	return false;
+}
diff --git a/src/backend/utils/activity/pgstat_relation.c b/src/backend/utils/activity/pgstat_relation.c
index e985a6a514..3f2df583fe 100644
--- a/src/backend/utils/activity/pgstat_relation.c
+++ b/src/backend/utils/activity/pgstat_relation.c
@@ -367,6 +367,76 @@ pgstat_setup_vacuum_frz_stats(Oid tableoid, bool shared)
 	pgstat_flush_io(false);
 }
 
+/*
+ * Calculate the average error rate for recorded freeze periods.
+ *
+ *  MTODO: should this be done in the cached backend local copy or the copy in
+ *  shared memory.
+ */
+float
+pgstat_frz_error_rate(Oid tableoid)
+{
+	PgStat_StatTabEntry *tabentry;
+	int64		early_unfreezes = 0;
+	int64		freezes = 0;
+	bool		skip_oldest;
+	int			i;
+
+	if ((tabentry = pgstat_fetch_stat_tabentry(tableoid)) == NULL)
+		return 0;
+
+	if (tabentry->frz_nbuckets_used == 0)
+		return 0;
+
+	/*
+	 * When calculating the freeze error rate, once we have used all available
+	 * buckets, we restrict the calculation to exclude the oldest period to
+	 * avoid a feedback loop where a high error rate causes us to freeze less
+	 * and then because we freeze less we have less new data causing the old
+	 * data to be over-represented. This could be done with a weighted average
+	 * but, for now, simply exclude the oldest entry.
+	 */
+	skip_oldest = tabentry->frz_nbuckets_used >= VAC_FRZ_STATS_MAX_NBUCKETS;
+
+	for (i = skip_oldest; i < tabentry->frz_nbuckets_used; i++)
+	{
+		PgStat_Frz *frz;
+
+		frz = &tabentry->frz_buckets[(tabentry->frz_oldest + i) % VAC_FRZ_STATS_MAX_NBUCKETS];
+
+		/*
+		 * We don't include the current freeze period in our error rate rate
+		 * calculation, as we have yet to see the consequences of those freeze
+		 * decisions and including it will skew the numbers.
+		 */
+		if (frz->start_lsn == InvalidXLogRecPtr ||
+			frz->end_lsn == InvalidXLogRecPtr)
+			continue;
+
+		/*
+		 * We use vm_page_freezes, even though those are not all subject to
+		 * the opportunistic freezing algorithm (and thus not in our power to
+		 * decide whether or not to freeze) because we cannot distinguish
+		 * between an unfreeze of a page that was opportunistically frozen and
+		 * one that was marked frozen in the VM because it happened to qualify
+		 * as all frozen.
+		 */
+		freezes += frz->vm_page_freezes;
+
+		/*
+		 * We care only about early_unfreezes, those pages which were unfrozen
+		 * before target_page_freeze_duration had elapsed.
+		 */
+		early_unfreezes += frz->early_unfreezes;
+	}
+
+	Assert(early_unfreezes <= freezes);
+
+	if (freezes == 0)
+		return 0;
+
+	return (float) early_unfreezes / freezes;
+}
 
 /*
  * When a frozen page from a table with oid tableoid is modified, the page LSN
diff --git a/src/backend/utils/init/globals.c b/src/backend/utils/init/globals.c
index 43212ea55c..ab296da86c 100644
--- a/src/backend/utils/init/globals.c
+++ b/src/backend/utils/init/globals.c
@@ -149,6 +149,7 @@ int			VacuumCostPageMiss = 2;
 int			VacuumCostPageDirty = 20;
 int			VacuumCostLimit = 200;
 double		VacuumCostDelay = 0;
+int			opp_freeze_algo = 0;
 int			target_page_freeze_duration = 1;
 
 int64		VacuumPageHit = 0;
diff --git a/src/backend/utils/misc/guc_tables.c b/src/backend/utils/misc/guc_tables.c
index 710f7f8a7d..99b909ac74 100644
--- a/src/backend/utils/misc/guc_tables.c
+++ b/src/backend/utils/misc/guc_tables.c
@@ -2465,6 +2465,16 @@ struct config_int ConfigureNamesInt[] =
 		NULL, NULL, NULL
 	},
 
+	{
+		{"opp_freeze_algo", PGC_USERSET, AUTOVACUUM,
+			gettext_noop("algorithm used to determine whether or not to freeze a page during vacuum"),
+			NULL
+		},
+		&opp_freeze_algo,
+		0, 0, 10000,
+		NULL, NULL, NULL
+	},
+
 	{
 		{"target_page_freeze_duration", PGC_USERSET, AUTOVACUUM,
 			gettext_noop("minimum amount of time in seconds that a page should stay frozen."),
diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
index 9966746c4e..16cc0eab22 100644
--- a/src/backend/utils/misc/postgresql.conf.sample
+++ b/src/backend/utils/misc/postgresql.conf.sample
@@ -661,6 +661,7 @@
 #autovacuum_vacuum_cost_limit = -1	# default vacuum cost limit for
 					# autovacuum, -1 means use
 					# vacuum_cost_limit
+#opp_freeze_algo = 0 # default opp_freeze_algo is 0 which means master
 #target_page_freeze_duration = 1 # desired time for page to stay frozen in seconds
 
 
diff --git a/src/include/miscadmin.h b/src/include/miscadmin.h
index bd04ff2899..40f7ad3372 100644
--- a/src/include/miscadmin.h
+++ b/src/include/miscadmin.h
@@ -279,6 +279,7 @@ extern PGDLLIMPORT int VacuumCostPageMiss;
 extern PGDLLIMPORT int VacuumCostPageDirty;
 extern PGDLLIMPORT int VacuumCostLimit;
 extern PGDLLIMPORT double VacuumCostDelay;
+extern PGDLLIMPORT int opp_freeze_algo;
 extern PGDLLIMPORT int target_page_freeze_duration;
 
 extern PGDLLIMPORT int64 VacuumPageHit;
diff --git a/src/include/pgstat.h b/src/include/pgstat.h
index e273b3aaee..8965211e3d 100644
--- a/src/include/pgstat.h
+++ b/src/include/pgstat.h
@@ -729,6 +729,8 @@ extern void pgstat_setup_vacuum_frz_stats(Oid tableoid, bool shared);
 extern void pgstat_count_page_unfreeze(Oid tableoid, bool shared,
 									   XLogRecPtr page_lsn, XLogRecPtr insert_lsn);
 
+extern float pgstat_frz_error_rate(Oid tableoid);
+
 extern void pgstat_count_page_freeze(Oid tableoid, bool shared, int64 page_age);
 
 extern void pgstat_report_analyze(Relation rel,
-- 
2.37.2

