From 20fbb711ef43ef70093378ff5efdf1b6e8cc10d8 Mon Sep 17 00:00:00 2001
From: Peter Geoghegan <pg@bowt.ie>
Date: Fri, 10 Apr 2020 17:44:08 -0700
Subject: [PATCH] Add contrib/amcheck debug message.

Add a DEBUG1 message indicating that verification of the index structure
is underway.  Also reduce the severity level of the existing "tree
level" debug message to DEBUG1.  It should never have been made DEBUG2.
Any B-Tree index with more than a couple of levels will generally also
have so many pages that the per-page DEBUG2 messages will become
completely unmanageable.

In passing, add a new "Tip" to the docs that advises users that run into
corruption that the debug messages might provide useful additional
context.
---
 contrib/amcheck/verify_nbtree.c |  9 ++++++++-
 doc/src/sgml/amcheck.sgml       | 21 +++++++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/contrib/amcheck/verify_nbtree.c b/contrib/amcheck/verify_nbtree.c
index ceaaa27168..7792b08b5f 100644
--- a/contrib/amcheck/verify_nbtree.c
+++ b/contrib/amcheck/verify_nbtree.c
@@ -411,6 +411,13 @@ bt_check_every_level(Relation rel, Relation heaprel, bool heapkeyspace,
 	BtreeLevel	current;
 	Snapshot	snapshot = SnapshotAny;
 
+	if (!readonly)
+		elog(DEBUG1, "verifying consistency of tree structure for index \"%s\"",
+			 RelationGetRelationName(rel));
+	else
+		elog(DEBUG1, "verifying consistency of tree structure for index \"%s\" with cross-level checks",
+			 RelationGetRelationName(rel));
+
 	/*
 	 * RecentGlobalXmin assertion matches index_getnext_tid().  See note on
 	 * RecentGlobalXmin/B-Tree page deletion.
@@ -654,7 +661,7 @@ bt_check_level_from_leftmost(BtreeCheckState *state, BtreeLevel level)
 	/* Use page-level context for duration of this call */
 	oldcontext = MemoryContextSwitchTo(state->targetcontext);
 
-	elog(DEBUG2, "verifying level %u%s", level.level,
+	elog(DEBUG1, "verifying level %u%s", level.level,
 		 level.istruerootlevel ?
 		 " (true root level)" : level.level == 0 ? " (leaf level)" : "");
 
diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml
index c912d2aa89..58b163a3d9 100644
--- a/doc/src/sgml/amcheck.sgml
+++ b/doc/src/sgml/amcheck.sgml
@@ -166,6 +166,27 @@ ORDER BY c.relpages DESC LIMIT 10;
     </listitem>
    </varlistentry>
   </variablelist>
+  <tip>
+   <para>
+    <function>bt_index_parent_check</function> and
+    <function>bt_index_parent_check</function> both output log
+    messages about the verification process at
+    <literal>DEBUG1</literal> and <literal>DEBUG2</literal> severity
+    levels.  These messages provide detailed information about the
+    verification process that may be of interest to
+    <productname>PostgreSQL</productname> developers.  Advanced users
+    may also find this information helpful, since it provides
+    additional context should verification actually detect an
+    inconsistency.  Running:
+<programlisting>
+SET client_min_messages = DEBUG1;
+</programlisting>
+    in an interactive <application>psql</application> session before
+    running a verification query will display messages about the
+    progress of verification with a manageable level of detail.
+   </para>
+  </tip>
+
  </sect2>
 
  <sect2>
-- 
2.39.5