Fix test case added by commit f5fc2f5b.

In the new test after resetting the stats, we were not waiting for the
stats message to be delivered. Also, we need to decode the results for
the new test, otherwise, it will show the old stats.

In passing,
a. Change docs added by commit f5fc2f5b as per suggestion by
Justin Pryzby.
b. Bump the PGSTAT_FILE_FORMAT_ID as commit f5fc2f5b changes the file
format of stats.

Reported-by: Tom Lane based on buildfarm reports
Author: Vignesh C, Justin Pryzby
Reviewed-by: Amit Kapila
Discussion: https://postgr.es/m/20210319185247.ldebgpdaxsowiflw@alap3.anarazel.de

contrib/test_decoding/expected/stats.out

@@ -51,39 +51,34 @@ BEGIN
     extract(epoch from clock_timestamp() - start_time);
 END
 $$ LANGUAGE plpgsql;
--- spilling the xact
-BEGIN;
-INSERT INTO stats_test SELECT 'serialize-topbig--1:'||g.i FROM generate_series(1, 5000) g(i);
-COMMIT;
-SELECT count(*) FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL, 'skip-empty-xacts', '1');
+-- non-spilled xact
+INSERT INTO stats_test values(1);
+SELECT count(*) FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'skip-empty-xacts', '1');
  count 
 -------
-  5002
+     3
 (1 row)
 
--- Check stats, wait for the stats collector to update. We can't test the
--- exact stats count as that can vary if any background transaction (say by
--- autovacuum) happens in parallel to the main transaction.
-SELECT wait_for_decode_stats(false, true);
+SELECT wait_for_decode_stats(false, false);
  wait_for_decode_stats 
 -----------------------
  
 (1 row)
 
-SELECT slot_name, spill_txns > 0 AS spill_txns, spill_count > 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
+SELECT slot_name, spill_txns = 0 AS spill_txns, spill_count = 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
     slot_name    | spill_txns | spill_count | total_txns | total_bytes 
 -----------------+------------+-------------+------------+-------------
  regression_slot | t          | t           | t          | t
 (1 row)
 
--- reset the slot stats, and wait for stats collector to reset
+-- reset the slot stats, and wait for stats collector's total txn to reset
 SELECT pg_stat_reset_replication_slot('regression_slot');
  pg_stat_reset_replication_slot 
 --------------------------------
  
 (1 row)
 
-SELECT wait_for_decode_stats(true, true);
+SELECT wait_for_decode_stats(true, false);
  wait_for_decode_stats 
 -----------------------
  
@@ -95,13 +90,19 @@ SELECT slot_name, spill_txns, spill_count, total_txns, total_bytes FROM pg_stat_
  regression_slot |          0 |           0 |          0 |           0
 (1 row)
 
--- decode and check stats again.
+-- spilling the xact
+BEGIN;
+INSERT INTO stats_test SELECT 'serialize-topbig--1:'||g.i FROM generate_series(1, 5000) g(i);
+COMMIT;
 SELECT count(*) FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL, 'skip-empty-xacts', '1');
  count 
 -------
   5002
 (1 row)
 
+-- Check stats, wait for the stats collector to update. We can't test the
+-- exact stats count as that can vary if any background transaction (say by
+-- autovacuum) happens in parallel to the main transaction.
 SELECT wait_for_decode_stats(false, true);
  wait_for_decode_stats 
 -----------------------
@@ -114,24 +115,42 @@ SELECT slot_name, spill_txns > 0 AS spill_txns, spill_count > 0 AS spill_count,
  regression_slot | t          | t           | t          | t
 (1 row)
 
+-- reset the slot stats, and wait for stats collector to reset
 SELECT pg_stat_reset_replication_slot('regression_slot');
  pg_stat_reset_replication_slot 
 --------------------------------
  
 (1 row)
 
--- non-spilled xact
-INSERT INTO stats_test values(generate_series(1, 10));
-SELECT wait_for_decode_stats(false, false);
+SELECT wait_for_decode_stats(true, true);
  wait_for_decode_stats 
 -----------------------
  
 (1 row)
 
-SELECT slot_name, spill_txns = 0 AS spill_txns, spill_count = 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
+SELECT slot_name, spill_txns, spill_count, total_txns, total_bytes FROM pg_stat_replication_slots;
     slot_name    | spill_txns | spill_count | total_txns | total_bytes 
 -----------------+------------+-------------+------------+-------------
- regression_slot | f          | f           | t          | t
+ regression_slot |          0 |           0 |          0 |           0
+(1 row)
+
+-- decode and check stats again.
+SELECT count(*) FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL, 'skip-empty-xacts', '1');
+ count 
+-------
+  5002
+(1 row)
+
+SELECT wait_for_decode_stats(false, true);
+ wait_for_decode_stats 
+-----------------------
+ 
+(1 row)
+
+SELECT slot_name, spill_txns > 0 AS spill_txns, spill_count > 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
+    slot_name    | spill_txns | spill_count | total_txns | total_bytes 
+-----------------+------------+-------------+------------+-------------
+ regression_slot | t          | t           | t          | t
 (1 row)
 
 -- Ensure stats can be repeatedly accessed using the same stats snapshot. See

contrib/test_decoding/sql/stats.sql

@@ -50,6 +50,17 @@ BEGIN
 END
 $$ LANGUAGE plpgsql;
 
+-- non-spilled xact
+INSERT INTO stats_test values(1);
+SELECT count(*) FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'skip-empty-xacts', '1');
+SELECT wait_for_decode_stats(false, false);
+SELECT slot_name, spill_txns = 0 AS spill_txns, spill_count = 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
+
+-- reset the slot stats, and wait for stats collector's total txn to reset
+SELECT pg_stat_reset_replication_slot('regression_slot');
+SELECT wait_for_decode_stats(true, false);
+SELECT slot_name, spill_txns, spill_count, total_txns, total_bytes FROM pg_stat_replication_slots;
+
 -- spilling the xact
 BEGIN;
 INSERT INTO stats_test SELECT 'serialize-topbig--1:'||g.i FROM generate_series(1, 5000) g(i);
@@ -72,13 +83,6 @@ SELECT count(*) FROM pg_logical_slot_peek_changes('regression_slot', NULL, NULL,
 SELECT wait_for_decode_stats(false, true);
 SELECT slot_name, spill_txns > 0 AS spill_txns, spill_count > 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
 
-SELECT pg_stat_reset_replication_slot('regression_slot');
-
--- non-spilled xact
-INSERT INTO stats_test values(generate_series(1, 10));
-SELECT wait_for_decode_stats(false, false);
-SELECT slot_name, spill_txns = 0 AS spill_txns, spill_count = 0 AS spill_count, total_txns > 0 AS total_txns, total_bytes > 0 AS total_bytes FROM pg_stat_replication_slots;
-
 -- Ensure stats can be repeatedly accessed using the same stats snapshot. See
 -- https://postgr.es/m/20210317230447.c7uc4g3vbs4wi32i%40alap3.anarazel.de
 BEGIN;

doc/src/sgml/monitoring.sgml

@@ -2722,9 +2722,9 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
        </para>
        <para>
         Number of decoded transactions sent to the decoding output plugin for
-        this slot. This counter is used to maintain the top level transactions,
-        so the counter is not incremented for subtransactions. Note that this
-        includes the transactions that are streamed and/or spilled.
+        this slot. This counts toplevel transactions only, and is not incremented
+        for subtransactions. Note that this includes the transactions that are
+        streamed and/or spilled.
        </para></entry>
      </row>
 
@@ -2733,10 +2733,10 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
         <structfield>total_bytes</structfield><type>bigint</type>
        </para>
        <para>
-        Amount of decoded transactions data sent to the decoding output plugin
+        Amount of decoded transaction data sent to the decoding output plugin
         while decoding the changes from WAL for this slot. This can be used to
         gauge the total amount of data sent during logical decoding. Note that
-        this includes the data that is streamed and/or spilled.
+        this includes data that is streamed and/or spilled.
        </para>
       </entry>
      </row>

src/include/pgstat.h

@@ -744,7 +744,7 @@ typedef union PgStat_Msg
  * ------------------------------------------------------------
  */
 
-#define PGSTAT_FILE_FORMAT_ID	0x01A5BCA1
+#define PGSTAT_FILE_FORMAT_ID	0x01A5BCA2
 
 /* ----------
  * PgStat_StatDBEntry			The collector's data per database