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.

Author: petergeoghegan

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)" : "");
 

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>