Skip to content

Commit c16dc1a

Browse files
robertmhaasrobertmhaas
committed
Add simple VACUUM progress reporting.
There's a lot more that could be done here yet - in particular, this reports only very coarse-grained information about the index vacuuming phase - but even as it stands, the new pg_stat_progress_vacuum can tell you quite a bit about what a long-running vacuum is actually doing. Amit Langote and Robert Haas, based on earlier work by Vinayak Pokale and Rahila Syed.
1 parent 0e9b899 commit c16dc1a

File tree

8 files changed

+394
-1
lines changed

8 files changed

+394
-1
lines changed

‎doc/src/sgml/monitoring.sgml‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -507,6 +507,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
507507
yet included in <structname>pg_stat_user_functions</>).</entry>
508508
</row>
509509

510+
<row>
511+
<entry><structname>pg_stat_progress_vacuum</><indexterm><primary>pg_stat_progress_vacuum</primary></indexterm></entry>
512+
<entry>One row for each backend (including autovacuum worker processes) running
513+
<command>VACUUM</>, showing current progress.
514+
See <xref linkend='vacuum-progress-reporting'>.</entry>
515+
</row>
510516
</tbody>
511517
</tgroup>
512518
</table>
@@ -2490,6 +2496,207 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
24902496
</para>
24912497
</sect1>
24922498

2499+
<sect1 id="progress-reporting">
2500+
<title>Progress Reporting</title>
2501+
2502+
<para>
2503+
<productname>PostgreSQL</> has the ability to report the progress of
2504+
certain commands during command execution. Currently, the only command
2505+
which supports progress reporting is <command>VACUUM</>. This may be
2506+
expanded in the future.
2507+
</para>
2508+
2509+
<sect2 id="vacuum-progress-reporting">
2510+
<title>VACUUM Progress Reporting</title>
2511+
2512+
<para>
2513+
Whenever <command>VACUUM</> is running, the
2514+
<structname>pg_stat_progress_vacuum</structname> view will contain
2515+
one row for each backend (including autovacuum worker processes) that is
2516+
currently vacuuming. The tables below describe the information
2517+
that will be reported and provide information about how to interpret it.
2518+
Progress reporting is not currently supported for <command>VACUUM FULL</>
2519+
and backends running <command>VACUUM FULL</> will not be listed in this
2520+
view.
2521+
</para>
2522+
2523+
<table id="pg-stat-progress-vacuum" xreflabel="pg_stat_progress_vacuum">
2524+
<title><structname>pg_stat_progress_vacuum</structname> View</title>
2525+
<tgroup cols="3">
2526+
<thead>
2527+
<row>
2528+
<entry>Column</entry>
2529+
<entry>Type</entry>
2530+
<entry>Description</entry>
2531+
</row>
2532+
</thead>
2533+
2534+
<tbody>
2535+
<row>
2536+
<entry><structfield>pid</></entry>
2537+
<entry><type>integer</></entry>
2538+
<entry>Process ID of backend.</entry>
2539+
</row>
2540+
<row>
2541+
<entry><structfield>datid</></entry>
2542+
<entry><type>oid</></entry>
2543+
<entry>OID of the database to which this backend is connected.</entry>
2544+
</row>
2545+
<row>
2546+
<entry><structfield>datname</></entry>
2547+
<entry><type>name</></entry>
2548+
<entry>Name of the database to which this backend is connected.</entry>
2549+
</row>
2550+
<row>
2551+
<entry><structfield>relid</></entry>
2552+
<entry><type>oid</></entry>
2553+
<entry>OID of the table being vacuumed.</entry>
2554+
</row>
2555+
<row>
2556+
<entry><structfield>phase</></entry>
2557+
<entry><type>text</></entry>
2558+
<entry>
2559+
Current processing phase of vacuum. See <xref linkend='vacuum-phases'>.
2560+
</entry>
2561+
</row>
2562+
<row>
2563+
<entry><structfield>heap_blks_total</></entry>
2564+
<entry><type>bigint</></entry>
2565+
<entry>
2566+
Total number of heap blocks in the table. This number is reported
2567+
as of the beginning of the scan; blocks added later will not be (and
2568+
need not be) visited by this <command>VACUUM</>.
2569+
</entry>
2570+
</row>
2571+
<row>
2572+
<entry><structfield>heap_blks_scanned</></entry>
2573+
<entry><type>bigint</></entry>
2574+
<entry>
2575+
Number of heap blocks scanned. Because the
2576+
<link linkend="storage-vm">visibility map</> is used to optimize scans,
2577+
some blocks will be skipped without inspection; skipped blocks are
2578+
included this total, so that this number will eventually become
2579+
equal to <structfield>heap_blks_total</> when the vacuum is complete.
2580+
This counter only advances when the phase is <literal>scanning heap</>.
2581+
</entry>
2582+
</row>
2583+
<row>
2584+
<entry><structfield>heap_blks_vacuumed</></entry>
2585+
<entry><type>bigint</></entry>
2586+
<entry>
2587+
Number of heap blocks vacuumed. Unless the table has no indexes, this
2588+
counter only advances when the phase is <literal>vacuuming heap</>.
2589+
Blocks that contain no dead tuples are skipped, so the counter may
2590+
sometimes skip forward in large increments.
2591+
</entry>
2592+
</row>
2593+
<row>
2594+
<entry><structfield>index_vacuum_count</></entry>
2595+
<entry><type>bigint</></entry>
2596+
<entry>
2597+
Number of completed index vacuums cycles.
2598+
</entry>
2599+
</row>
2600+
<row>
2601+
<entry><structfield>max_dead_tuples</></entry>
2602+
<entry><type>bigint</></entry>
2603+
<entry>
2604+
Number of dead tuples that we can store before needing to perform
2605+
an index vacuum cycle, based on
2606+
<xref linkend="guc-maintenance-work-mem">.
2607+
</entry>
2608+
</row>
2609+
<row>
2610+
<entry><structfield>num_dead_tuples</></entry>
2611+
<entry><type>bigint</></entry>
2612+
<entry>
2613+
Number of dead tuples collected since the last index vacuum cycle.
2614+
</entry>
2615+
</row>
2616+
</tbody>
2617+
</tgroup>
2618+
</table>
2619+
2620+
<table id="vacuum-phases" xreflabel="VACUUM phases">
2621+
<title>VACUUM phases</title>
2622+
<tgroup cols="2">
2623+
<thead>
2624+
<row>
2625+
<entry>Phase</entry>
2626+
<entry>Description</entry>
2627+
</row>
2628+
</thead>
2629+
2630+
<tbody>
2631+
<row>
2632+
<entry><literal>initializing</literal></entry>
2633+
<entry>
2634+
<command>VACUUM</> is preparing to begin scanning the heap. This
2635+
phase is expected to be very brief.
2636+
</entry>
2637+
</row>
2638+
<row>
2639+
<entry><literal>scanning heap</literal></entry>
2640+
<entry>
2641+
<command>VACUUM</> is currently scanning the heap. It will prune and
2642+
defragment each page if required, and possibly perform freezing
2643+
activity. The <structfield>heap_blks_scanned</> column can be used
2644+
to monitor the progress of the scan.
2645+
</entry>
2646+
</row>
2647+
<row>
2648+
<entry><literal>vacuuming indexes</literal></entry>
2649+
<entry>
2650+
<command>VACUUM</> is currently vacuuming the indexes. If a table has
2651+
any indexes, this will happen at least once per vacuum, after the heap
2652+
has been completely scanned. It may happen multiple times per vacuum
2653+
if <xref linkend="guc-maintenance-work-mem"> is insufficient to
2654+
store the number of dead tuples found.
2655+
</entry>
2656+
</row>
2657+
<row>
2658+
<entry><literal>vacuuming heap</literal></entry>
2659+
<entry>
2660+
<command>VACUUM</> is currently vacuuming the heap. Vacuuming the heap
2661+
is distinct from scanning the heap, and occurs after each instance of
2662+
vacuuming indexes. If <structfield>heap_blks_scanned</> is less than
2663+
<structfield>heap_blks_total</>, the system will return to scanning
2664+
the heap after this phase is completed; otherwise, it will begin
2665+
cleaning up indexes after this phase is completed.
2666+
</entry>
2667+
</row>
2668+
<row>
2669+
<entry><literal>cleaning up indexes</literal></entry>
2670+
<entry>
2671+
<command>VACUUM</> is currently cleaning up indexes. This occurs after
2672+
the heap has been completely scanned and all vacuuming of the indexes
2673+
and the heap has been completed.
2674+
</entry>
2675+
</row>
2676+
<row>
2677+
<entry><literal>truncating heap</literal></entry>
2678+
<entry>
2679+
<command>VACUUM</> is currently truncating the heap so as to return
2680+
empty pages at the end of the relation to the operating system. This
2681+
occurs after cleaning up indexes.
2682+
</entry>
2683+
</row>
2684+
<row>
2685+
<entry><literal>performing final cleanup</literal></entry>
2686+
<entry>
2687+
<command>VACUUM</> is performing final cleanup. During this phase,
2688+
<command>VACUUM</> will vacuum the free space map, update statistics
2689+
in <literal>pg_class</>, and report statistics to the statistics
2690+
collector. When this phase is completed, <command>VACUUM</> will end.
2691+
</entry>
2692+
</row>
2693+
</tbody>
2694+
</tgroup>
2695+
</table>
2696+
2697+
</sect2>
2698+
</sect1>
2699+
24932700
<sect1 id="dynamic-trace">
24942701
<title>Dynamic Tracing</title>
24952702

‎src/backend/catalog/system_views.sql‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,24 @@ CREATE VIEW pg_stat_bgwriter AS
796796
pg_stat_get_buf_alloc() AS buffers_alloc,
797797
pg_stat_get_bgwriter_stat_reset_time() AS stats_reset;
798798

799+
CREATE VIEW pg_stat_progress_vacuum AS
800+
SELECT
801+
S.pid AS pid, S.datid AS datid, D.datname AS datname,
802+
S.relid AS relid,
803+
CASE S.param1 WHEN 0 THEN 'initializing'
804+
WHEN 1 THEN 'scanning heap'
805+
WHEN 2 THEN 'vacuuming indexes'
806+
WHEN 3 THEN 'vacuuming heap'
807+
WHEN 4 THEN 'cleaning up indexes'
808+
WHEN 5 THEN 'truncating heap'
809+
WHEN 6 THEN 'performing final cleanup'
810+
END AS phase,
811+
S.param2 AS heap_blks_total, S.param3 AS heap_blks_scanned,
812+
S.param4 AS heap_blks_vacuumed, S.param5 AS index_vacuum_count,
813+
S.param6 AS max_dead_tuples, S.param7 AS num_dead_tuples
814+
FROM pg_stat_get_progress_info('VACUUM') AS S
815+
JOIN pg_database D ON S.datid = D.oid;
816+
799817
CREATE VIEW pg_user_mappings AS
800818
SELECT
801819
U.oid AS umid,

0 commit comments

Comments
 (0)