Generate automatically code and documentation related to wait events
[pgsql.git] / doc / src / sgml / monitoring.sgml
blob506aeaa87999349be717180da69a5482c35e4686
1 <!-- doc/src/sgml/monitoring.sgml -->
3 <chapter id="monitoring">
4 <title>Monitoring Database Activity</title>
6 <indexterm zone="monitoring">
7 <primary>monitoring</primary>
8 <secondary>database activity</secondary>
9 </indexterm>
11 <indexterm zone="monitoring">
12 <primary>database activity</primary>
13 <secondary>monitoring</secondary>
14 </indexterm>
16 <para>
17 A database administrator frequently wonders, <quote>What is the system
18 doing right now?</quote>
19 This chapter discusses how to find that out.
20 </para>
22 <para>
23 Several tools are available for monitoring database activity and
24 analyzing performance. Most of this chapter is devoted to describing
25 <productname>PostgreSQL</productname>'s cumulative statistics system,
26 but one should not neglect regular Unix monitoring programs such as
27 <command>ps</command>, <command>top</command>, <command>iostat</command>, and <command>vmstat</command>.
28 Also, once one has identified a
29 poorly-performing query, further investigation might be needed using
30 <productname>PostgreSQL</productname>'s <link linkend="sql-explain"><command>EXPLAIN</command></link> command.
31 <xref linkend="using-explain"/> discusses <command>EXPLAIN</command>
32 and other methods for understanding the behavior of an individual
33 query.
34 </para>
36 <sect1 id="monitoring-ps">
37 <title>Standard Unix Tools</title>
39 <indexterm zone="monitoring-ps">
40 <primary>ps</primary>
41 <secondary>to monitor activity</secondary>
42 </indexterm>
44 <para>
45 On most Unix platforms, <productname>PostgreSQL</productname> modifies its
46 command title as reported by <command>ps</command>, so that individual server
47 processes can readily be identified. A sample display is
49 <screen>
50 $ ps auxww | grep ^postgres
51 postgres 15551 0.0 0.1 57536 7132 pts/0 S 18:02 0:00 postgres -i
52 postgres 15554 0.0 0.0 57536 1184 ? Ss 18:02 0:00 postgres: background writer
53 postgres 15555 0.0 0.0 57536 916 ? Ss 18:02 0:00 postgres: checkpointer
54 postgres 15556 0.0 0.0 57536 916 ? Ss 18:02 0:00 postgres: walwriter
55 postgres 15557 0.0 0.0 58504 2244 ? Ss 18:02 0:00 postgres: autovacuum launcher
56 postgres 15582 0.0 0.0 58772 3080 ? Ss 18:04 0:00 postgres: joe runbug 127.0.0.1 idle
57 postgres 15606 0.0 0.0 58772 3052 ? Ss 18:07 0:00 postgres: tgl regression [local] SELECT waiting
58 postgres 15610 0.0 0.0 58772 3056 ? Ss 18:07 0:00 postgres: tgl regression [local] idle in transaction
59 </screen>
61 (The appropriate invocation of <command>ps</command> varies across different
62 platforms, as do the details of what is shown. This example is from a
63 recent Linux system.) The first process listed here is the
64 primary server process. The command arguments
65 shown for it are the same ones used when it was launched. The next four
66 processes are background worker processes automatically launched by the
67 primary process. (The <quote>autovacuum launcher</quote> process will not
68 be present if you have set the system not to run autovacuum.)
69 Each of the remaining
70 processes is a server process handling one client connection. Each such
71 process sets its command line display in the form
73 <screen>
74 postgres: <replaceable>user</replaceable> <replaceable>database</replaceable> <replaceable>host</replaceable> <replaceable>activity</replaceable>
75 </screen>
77 The user, database, and (client) host items remain the same for
78 the life of the client connection, but the activity indicator changes.
79 The activity can be <literal>idle</literal> (i.e., waiting for a client command),
80 <literal>idle in transaction</literal> (waiting for client inside a <command>BEGIN</command> block),
81 or a command type name such as <literal>SELECT</literal>. Also,
82 <literal>waiting</literal> is appended if the server process is presently waiting
83 on a lock held by another session. In the above example we can infer
84 that process 15606 is waiting for process 15610 to complete its transaction
85 and thereby release some lock. (Process 15610 must be the blocker, because
86 there is no other active session. In more complicated cases it would be
87 necessary to look into the
88 <link linkend="view-pg-locks"><structname>pg_locks</structname></link>
89 system view to determine who is blocking whom.)
90 </para>
92 <para>
93 If <xref linkend="guc-cluster-name"/> has been configured the
94 cluster name will also be shown in <command>ps</command> output:
95 <screen>
96 $ psql -c 'SHOW cluster_name'
97 cluster_name
98 --------------
99 server1
100 (1 row)
102 $ ps aux|grep server1
103 postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: server1: background writer
105 </screen>
106 </para>
108 <para>
109 If you have turned off <xref linkend="guc-update-process-title"/> then the
110 activity indicator is not updated; the process title is set only once
111 when a new process is launched. On some platforms this saves a measurable
112 amount of per-command overhead; on others it's insignificant.
113 </para>
115 <tip>
116 <para>
117 <productname>Solaris</productname> requires special handling. You must
118 use <command>/usr/ucb/ps</command>, rather than
119 <command>/bin/ps</command>. You also must use two <option>w</option>
120 flags, not just one. In addition, your original invocation of the
121 <command>postgres</command> command must have a shorter
122 <command>ps</command> status display than that provided by each
123 server process. If you fail to do all three things, the <command>ps</command>
124 output for each server process will be the original <command>postgres</command>
125 command line.
126 </para>
127 </tip>
128 </sect1>
130 <sect1 id="monitoring-stats">
131 <title>The Cumulative Statistics System</title>
133 <indexterm zone="monitoring-stats">
134 <primary>statistics</primary>
135 </indexterm>
137 <para>
138 <productname>PostgreSQL</productname>'s <firstterm>cumulative statistics
139 system</firstterm> supports collection and reporting of information about
140 server activity. Presently, accesses to tables and indexes in both
141 disk-block and individual-row terms are counted. The total number of rows
142 in each table, and information about vacuum and analyze actions for each
143 table are also counted. If enabled, calls to user-defined functions and
144 the total time spent in each one are counted as well.
145 </para>
147 <para>
148 <productname>PostgreSQL</productname> also supports reporting dynamic
149 information about exactly what is going on in the system right now, such as
150 the exact command currently being executed by other server processes, and
151 which other connections exist in the system. This facility is independent
152 of the cumulative statistics system.
153 </para>
155 <sect2 id="monitoring-stats-setup">
156 <title>Statistics Collection Configuration</title>
158 <para>
159 Since collection of statistics adds some overhead to query execution,
160 the system can be configured to collect or not collect information.
161 This is controlled by configuration parameters that are normally set in
162 <filename>postgresql.conf</filename>. (See <xref linkend="runtime-config"/> for
163 details about setting configuration parameters.)
164 </para>
166 <para>
167 The parameter <xref linkend="guc-track-activities"/> enables monitoring
168 of the current command being executed by any server process.
169 </para>
171 <para>
172 The parameter <xref linkend="guc-track-counts"/> controls whether
173 cumulative statistics are collected about table and index accesses.
174 </para>
176 <para>
177 The parameter <xref linkend="guc-track-functions"/> enables tracking of
178 usage of user-defined functions.
179 </para>
181 <para>
182 The parameter <xref linkend="guc-track-io-timing"/> enables monitoring
183 of block read and write times.
184 </para>
186 <para>
187 The parameter <xref linkend="guc-track-wal-io-timing"/> enables monitoring
188 of WAL write times.
189 </para>
191 <para>
192 Normally these parameters are set in <filename>postgresql.conf</filename> so
193 that they apply to all server processes, but it is possible to turn
194 them on or off in individual sessions using the <xref
195 linkend="sql-set"/> command. (To prevent
196 ordinary users from hiding their activity from the administrator,
197 only superusers are allowed to change these parameters with
198 <command>SET</command>.)
199 </para>
201 <para>
202 Cumulative statistics are collected in shared memory. Every
203 <productname>PostgreSQL</productname> process collects statistics locally,
204 then updates the shared data at appropriate intervals. When a server,
205 including a physical replica, shuts down cleanly, a permanent copy of the
206 statistics data is stored in the <filename>pg_stat</filename> subdirectory,
207 so that statistics can be retained across server restarts. In contrast,
208 when starting from an unclean shutdown (e.g., after an immediate shutdown,
209 a server crash, starting from a base backup, and point-in-time recovery),
210 all statistics counters are reset.
211 </para>
213 </sect2>
215 <sect2 id="monitoring-stats-views">
216 <title>Viewing Statistics</title>
218 <para>
219 Several predefined views, listed in <xref
220 linkend="monitoring-stats-dynamic-views-table"/>, are available to show
221 the current state of the system. There are also several other
222 views, listed in <xref
223 linkend="monitoring-stats-views-table"/>, available to show the accumulated
224 statistics. Alternatively, one can
225 build custom views using the underlying cumulative statistics functions, as
226 discussed in <xref linkend="monitoring-stats-functions"/>.
227 </para>
229 <para>
230 When using the cumulative statistics views and functions to monitor
231 collected data, it is important to realize that the information does not
232 update instantaneously. Each individual server process flushes out
233 accumulated statistics to shared memory just before going idle, but not
234 more frequently than once per <varname>PGSTAT_MIN_INTERVAL</varname>
235 milliseconds (1 second unless altered while building the server); so a
236 query or transaction still in progress does not affect the displayed totals
237 and the displayed information lags behind actual activity. However,
238 current-query information collected by <varname>track_activities</varname>
239 is always up-to-date.
240 </para>
242 <para>
243 Another important point is that when a server process is asked to display
244 any of the accumulated statistics, accessed values are cached until the end
245 of its current transaction in the default configuration. So the statistics
246 will show static information as long as you continue the current
247 transaction. Similarly, information about the current queries of all
248 sessions is collected when any such information is first requested within a
249 transaction, and the same information will be displayed throughout the
250 transaction. This is a feature, not a bug, because it allows you to perform
251 several queries on the statistics and correlate the results without
252 worrying that the numbers are changing underneath you.
254 When analyzing statistics interactively, or with expensive queries, the
255 time delta between accesses to individual statistics can lead to
256 significant skew in the cached statistics. To minimize skew,
257 <varname>stats_fetch_consistency</varname> can be set to
258 <literal>snapshot</literal>, at the price of increased memory usage for
259 caching not-needed statistics data. Conversely, if it's known that
260 statistics are only accessed once, caching accessed statistics is
261 unnecessary and can be avoided by setting
262 <varname>stats_fetch_consistency</varname> to <literal>none</literal>.
264 You can invoke <function>pg_stat_clear_snapshot</function>() to discard the
265 current transaction's statistics snapshot or cached values (if any). The
266 next use of statistical information will (when in snapshot mode) cause a
267 new snapshot to be built or (when in cache mode) accessed statistics to be
268 cached.
269 </para>
271 <para>
272 A transaction can also see its own statistics (not yet flushed out to the
273 shared memory statistics) in the views
274 <structname>pg_stat_xact_all_tables</structname>,
275 <structname>pg_stat_xact_sys_tables</structname>,
276 <structname>pg_stat_xact_user_tables</structname>, and
277 <structname>pg_stat_xact_user_functions</structname>. These numbers do not act as
278 stated above; instead they update continuously throughout the transaction.
279 </para>
281 <para>
282 Some of the information in the dynamic statistics views shown in <xref
283 linkend="monitoring-stats-dynamic-views-table"/> is security restricted.
284 Ordinary users can only see all the information about their own sessions
285 (sessions belonging to a role that they are a member of). In rows about
286 other sessions, many columns will be null. Note, however, that the
287 existence of a session and its general properties such as its sessions user
288 and database are visible to all users. Superusers and roles with privileges of
289 built-in role <literal>pg_read_all_stats</literal> (see also <xref
290 linkend="predefined-roles"/>) can see all the information about all sessions.
291 </para>
293 <table id="monitoring-stats-dynamic-views-table">
294 <title>Dynamic Statistics Views</title>
296 <tgroup cols="2">
297 <thead>
298 <row>
299 <entry>View Name</entry>
300 <entry>Description</entry>
301 </row>
302 </thead>
304 <tbody>
305 <row>
306 <entry>
307 <structname>pg_stat_activity</structname>
308 <indexterm><primary>pg_stat_activity</primary></indexterm>
309 </entry>
310 <entry>
311 One row per server process, showing information related to
312 the current activity of that process, such as state and current query.
313 See <link linkend="monitoring-pg-stat-activity-view">
314 <structname>pg_stat_activity</structname></link> for details.
315 </entry>
316 </row>
318 <row>
319 <entry><structname>pg_stat_replication</structname><indexterm><primary>pg_stat_replication</primary></indexterm></entry>
320 <entry>One row per WAL sender process, showing statistics about
321 replication to that sender's connected standby server.
322 See <link linkend="monitoring-pg-stat-replication-view">
323 <structname>pg_stat_replication</structname></link> for details.
324 </entry>
325 </row>
327 <row>
328 <entry><structname>pg_stat_wal_receiver</structname><indexterm><primary>pg_stat_wal_receiver</primary></indexterm></entry>
329 <entry>Only one row, showing statistics about the WAL receiver from
330 that receiver's connected server.
331 See <link linkend="monitoring-pg-stat-wal-receiver-view">
332 <structname>pg_stat_wal_receiver</structname></link> for details.
333 </entry>
334 </row>
336 <row>
337 <entry><structname>pg_stat_recovery_prefetch</structname><indexterm><primary>pg_stat_recovery_prefetch</primary></indexterm></entry>
338 <entry>Only one row, showing statistics about blocks prefetched during recovery.
339 See <link linkend="monitoring-pg-stat-recovery-prefetch">
340 <structname>pg_stat_recovery_prefetch</structname></link> for details.
341 </entry>
342 </row>
344 <row>
345 <entry><structname>pg_stat_subscription</structname><indexterm><primary>pg_stat_subscription</primary></indexterm></entry>
346 <entry>At least one row per subscription, showing information about
347 the subscription workers.
348 See <link linkend="monitoring-pg-stat-subscription">
349 <structname>pg_stat_subscription</structname></link> for details.
350 </entry>
351 </row>
353 <row>
354 <entry><structname>pg_stat_ssl</structname><indexterm><primary>pg_stat_ssl</primary></indexterm></entry>
355 <entry>One row per connection (regular and replication), showing information about
356 SSL used on this connection.
357 See <link linkend="monitoring-pg-stat-ssl-view">
358 <structname>pg_stat_ssl</structname></link> for details.
359 </entry>
360 </row>
362 <row>
363 <entry><structname>pg_stat_gssapi</structname><indexterm><primary>pg_stat_gssapi</primary></indexterm></entry>
364 <entry>One row per connection (regular and replication), showing information about
365 GSSAPI authentication and encryption used on this connection.
366 See <link linkend="monitoring-pg-stat-gssapi-view">
367 <structname>pg_stat_gssapi</structname></link> for details.
368 </entry>
369 </row>
371 <row>
372 <entry><structname>pg_stat_progress_analyze</structname><indexterm><primary>pg_stat_progress_analyze</primary></indexterm></entry>
373 <entry>One row for each backend (including autovacuum worker processes) running
374 <command>ANALYZE</command>, showing current progress.
375 See <xref linkend="analyze-progress-reporting"/>.
376 </entry>
377 </row>
379 <row>
380 <entry><structname>pg_stat_progress_create_index</structname><indexterm><primary>pg_stat_progress_create_index</primary></indexterm></entry>
381 <entry>One row for each backend running <command>CREATE INDEX</command> or <command>REINDEX</command>, showing
382 current progress.
383 See <xref linkend="create-index-progress-reporting"/>.
384 </entry>
385 </row>
387 <row>
388 <entry><structname>pg_stat_progress_vacuum</structname><indexterm><primary>pg_stat_progress_vacuum</primary></indexterm></entry>
389 <entry>One row for each backend (including autovacuum worker processes) running
390 <command>VACUUM</command>, showing current progress.
391 See <xref linkend="vacuum-progress-reporting"/>.
392 </entry>
393 </row>
395 <row>
396 <entry><structname>pg_stat_progress_cluster</structname><indexterm><primary>pg_stat_progress_cluster</primary></indexterm></entry>
397 <entry>One row for each backend running
398 <command>CLUSTER</command> or <command>VACUUM FULL</command>, showing current progress.
399 See <xref linkend="cluster-progress-reporting"/>.
400 </entry>
401 </row>
403 <row>
404 <entry><structname>pg_stat_progress_basebackup</structname><indexterm><primary>pg_stat_progress_basebackup</primary></indexterm></entry>
405 <entry>One row for each WAL sender process streaming a base backup,
406 showing current progress.
407 See <xref linkend="basebackup-progress-reporting"/>.
408 </entry>
409 </row>
411 <row>
412 <entry><structname>pg_stat_progress_copy</structname><indexterm><primary>pg_stat_progress_copy</primary></indexterm></entry>
413 <entry>One row for each backend running <command>COPY</command>, showing current progress.
414 See <xref linkend="copy-progress-reporting"/>.
415 </entry>
416 </row>
417 </tbody>
418 </tgroup>
419 </table>
421 <table id="monitoring-stats-views-table">
422 <title>Collected Statistics Views</title>
424 <tgroup cols="2">
425 <thead>
426 <row>
427 <entry>View Name</entry>
428 <entry>Description</entry>
429 </row>
430 </thead>
432 <tbody>
434 <!-- everything related to global objects, alphabetically -->
436 <row>
437 <entry><structname>pg_stat_archiver</structname><indexterm><primary>pg_stat_archiver</primary></indexterm></entry>
438 <entry>One row only, showing statistics about the
439 WAL archiver process's activity. See
440 <link linkend="monitoring-pg-stat-archiver-view">
441 <structname>pg_stat_archiver</structname></link> for details.
442 </entry>
443 </row>
445 <row>
446 <entry><structname>pg_stat_bgwriter</structname><indexterm><primary>pg_stat_bgwriter</primary></indexterm></entry>
447 <entry>One row only, showing statistics about the
448 background writer process's activity. See
449 <link linkend="monitoring-pg-stat-bgwriter-view">
450 <structname>pg_stat_bgwriter</structname></link> for details.
451 </entry>
452 </row>
454 <row>
455 <entry><structname>pg_stat_database</structname><indexterm><primary>pg_stat_database</primary></indexterm></entry>
456 <entry>One row per database, showing database-wide statistics. See
457 <link linkend="monitoring-pg-stat-database-view">
458 <structname>pg_stat_database</structname></link> for details.
459 </entry>
460 </row>
462 <row>
463 <entry><structname>pg_stat_database_conflicts</structname><indexterm><primary>pg_stat_database_conflicts</primary></indexterm></entry>
464 <entry>
465 One row per database, showing database-wide statistics about
466 query cancels due to conflict with recovery on standby servers.
467 See <link linkend="monitoring-pg-stat-database-conflicts-view">
468 <structname>pg_stat_database_conflicts</structname></link> for details.
469 </entry>
470 </row>
472 <row>
473 <entry><structname>pg_stat_io</structname><indexterm><primary>pg_stat_io</primary></indexterm></entry>
474 <entry>
475 One row for each combination of backend type, context, and target object
476 containing cluster-wide I/O statistics.
477 See <link linkend="monitoring-pg-stat-io-view">
478 <structname>pg_stat_io</structname></link> for details.
479 </entry>
480 </row>
482 <row>
483 <entry><structname>pg_stat_replication_slots</structname><indexterm><primary>pg_stat_replication_slots</primary></indexterm></entry>
484 <entry>One row per replication slot, showing statistics about the
485 replication slot's usage. See
486 <link linkend="monitoring-pg-stat-replication-slots-view">
487 <structname>pg_stat_replication_slots</structname></link> for details.
488 </entry>
489 </row>
491 <row>
492 <entry><structname>pg_stat_slru</structname><indexterm><primary>pg_stat_slru</primary></indexterm></entry>
493 <entry>One row per SLRU, showing statistics of operations. See
494 <link linkend="monitoring-pg-stat-slru-view">
495 <structname>pg_stat_slru</structname></link> for details.
496 </entry>
497 </row>
499 <row>
500 <entry><structname>pg_stat_subscription_stats</structname><indexterm><primary>pg_stat_subscription_stats</primary></indexterm></entry>
501 <entry>One row per subscription, showing statistics about errors.
502 See <link linkend="monitoring-pg-stat-subscription-stats">
503 <structname>pg_stat_subscription_stats</structname></link> for details.
504 </entry>
505 </row>
507 <row>
508 <entry><structname>pg_stat_wal</structname><indexterm><primary>pg_stat_wal</primary></indexterm></entry>
509 <entry>One row only, showing statistics about WAL activity. See
510 <link linkend="monitoring-pg-stat-wal-view">
511 <structname>pg_stat_wal</structname></link> for details.
512 </entry>
513 </row>
515 <!-- all "stat" for schema objects, by "importance" -->
517 <row>
518 <entry><structname>pg_stat_all_tables</structname><indexterm><primary>pg_stat_all_tables</primary></indexterm></entry>
519 <entry>
520 One row for each table in the current database, showing statistics
521 about accesses to that specific table.
522 See <link linkend="monitoring-pg-stat-all-tables-view">
523 <structname>pg_stat_all_tables</structname></link> for details.
524 </entry>
525 </row>
527 <row>
528 <entry><structname>pg_stat_sys_tables</structname><indexterm><primary>pg_stat_sys_tables</primary></indexterm></entry>
529 <entry>Same as <structname>pg_stat_all_tables</structname>, except that only
530 system tables are shown.</entry>
531 </row>
533 <row>
534 <entry><structname>pg_stat_user_tables</structname><indexterm><primary>pg_stat_user_tables</primary></indexterm></entry>
535 <entry>Same as <structname>pg_stat_all_tables</structname>, except that only user
536 tables are shown.</entry>
537 </row>
539 <row>
540 <entry><structname>pg_stat_xact_all_tables</structname><indexterm><primary>pg_stat_xact_all_tables</primary></indexterm></entry>
541 <entry>Similar to <structname>pg_stat_all_tables</structname>, but counts actions
542 taken so far within the current transaction (which are <emphasis>not</emphasis>
543 yet included in <structname>pg_stat_all_tables</structname> and related views).
544 The columns for numbers of live and dead rows and vacuum and
545 analyze actions are not present in this view.</entry>
546 </row>
548 <row>
549 <entry><structname>pg_stat_xact_sys_tables</structname><indexterm><primary>pg_stat_xact_sys_tables</primary></indexterm></entry>
550 <entry>Same as <structname>pg_stat_xact_all_tables</structname>, except that only
551 system tables are shown.</entry>
552 </row>
554 <row>
555 <entry><structname>pg_stat_xact_user_tables</structname><indexterm><primary>pg_stat_xact_user_tables</primary></indexterm></entry>
556 <entry>Same as <structname>pg_stat_xact_all_tables</structname>, except that only
557 user tables are shown.</entry>
558 </row>
560 <row>
561 <entry><structname>pg_stat_all_indexes</structname><indexterm><primary>pg_stat_all_indexes</primary></indexterm></entry>
562 <entry>
563 One row for each index in the current database, showing statistics
564 about accesses to that specific index.
565 See <link linkend="monitoring-pg-stat-all-indexes-view">
566 <structname>pg_stat_all_indexes</structname></link> for details.
567 </entry>
568 </row>
570 <row>
571 <entry><structname>pg_stat_sys_indexes</structname><indexterm><primary>pg_stat_sys_indexes</primary></indexterm></entry>
572 <entry>Same as <structname>pg_stat_all_indexes</structname>, except that only
573 indexes on system tables are shown.</entry>
574 </row>
576 <row>
577 <entry><structname>pg_stat_user_indexes</structname><indexterm><primary>pg_stat_user_indexes</primary></indexterm></entry>
578 <entry>Same as <structname>pg_stat_all_indexes</structname>, except that only
579 indexes on user tables are shown.</entry>
580 </row>
582 <row>
583 <entry><structname>pg_stat_user_functions</structname><indexterm><primary>pg_stat_user_functions</primary></indexterm></entry>
584 <entry>
585 One row for each tracked function, showing statistics
586 about executions of that function. See
587 <link linkend="monitoring-pg-stat-user-functions-view">
588 <structname>pg_stat_user_functions</structname></link> for details.
589 </entry>
590 </row>
592 <row>
593 <entry><structname>pg_stat_xact_user_functions</structname><indexterm><primary>pg_stat_xact_user_functions</primary></indexterm></entry>
594 <entry>Similar to <structname>pg_stat_user_functions</structname>, but counts only
595 calls during the current transaction (which are <emphasis>not</emphasis>
596 yet included in <structname>pg_stat_user_functions</structname>).</entry>
597 </row>
599 <!-- all "statio" for schema objects, by "importance" -->
601 <row>
602 <entry><structname>pg_statio_all_tables</structname><indexterm><primary>pg_statio_all_tables</primary></indexterm></entry>
603 <entry>
604 One row for each table in the current database, showing statistics
605 about I/O on that specific table.
606 See <link linkend="monitoring-pg-statio-all-tables-view">
607 <structname>pg_statio_all_tables</structname></link> for details.
608 </entry>
609 </row>
611 <row>
612 <entry><structname>pg_statio_sys_tables</structname><indexterm><primary>pg_statio_sys_tables</primary></indexterm></entry>
613 <entry>Same as <structname>pg_statio_all_tables</structname>, except that only
614 system tables are shown.</entry>
615 </row>
617 <row>
618 <entry><structname>pg_statio_user_tables</structname><indexterm><primary>pg_statio_user_tables</primary></indexterm></entry>
619 <entry>Same as <structname>pg_statio_all_tables</structname>, except that only
620 user tables are shown.</entry>
621 </row>
623 <row>
624 <entry><structname>pg_statio_all_indexes</structname><indexterm><primary>pg_statio_all_indexes</primary></indexterm></entry>
625 <entry>
626 One row for each index in the current database,
627 showing statistics about I/O on that specific index.
628 See <link linkend="monitoring-pg-statio-all-indexes-view">
629 <structname>pg_statio_all_indexes</structname></link> for details.
630 </entry>
631 </row>
633 <row>
634 <entry><structname>pg_statio_sys_indexes</structname><indexterm><primary>pg_statio_sys_indexes</primary></indexterm></entry>
635 <entry>Same as <structname>pg_statio_all_indexes</structname>, except that only
636 indexes on system tables are shown.</entry>
637 </row>
639 <row>
640 <entry><structname>pg_statio_user_indexes</structname><indexterm><primary>pg_statio_user_indexes</primary></indexterm></entry>
641 <entry>Same as <structname>pg_statio_all_indexes</structname>, except that only
642 indexes on user tables are shown.</entry>
643 </row>
645 <row>
646 <entry><structname>pg_statio_all_sequences</structname><indexterm><primary>pg_statio_all_sequences</primary></indexterm></entry>
647 <entry>
648 One row for each sequence in the current database,
649 showing statistics about I/O on that specific sequence.
650 See <link linkend="monitoring-pg-statio-all-sequences-view">
651 <structname>pg_statio_all_sequences</structname></link> for details.
652 </entry>
653 </row>
655 <row>
656 <entry><structname>pg_statio_sys_sequences</structname><indexterm><primary>pg_statio_sys_sequences</primary></indexterm></entry>
657 <entry>Same as <structname>pg_statio_all_sequences</structname>, except that only
658 system sequences are shown. (Presently, no system sequences are defined,
659 so this view is always empty.)</entry>
660 </row>
662 <row>
663 <entry><structname>pg_statio_user_sequences</structname><indexterm><primary>pg_statio_user_sequences</primary></indexterm></entry>
664 <entry>Same as <structname>pg_statio_all_sequences</structname>, except that only
665 user sequences are shown.</entry>
666 </row>
668 </tbody>
669 </tgroup>
670 </table>
672 <para>
673 The per-index statistics are particularly useful to determine which
674 indexes are being used and how effective they are.
675 </para>
677 <para>
678 The <structname>pg_stat_io</structname> and
679 <structname>pg_statio_</structname> set of views are useful for determining
680 the effectiveness of the buffer cache. They can be used to calculate a cache
681 hit ratio. Note that while <productname>PostgreSQL</productname>'s I/O
682 statistics capture most instances in which the kernel was invoked in order
683 to perform I/O, they do not differentiate between data which had to be
684 fetched from disk and that which already resided in the kernel page cache.
685 Users are advised to use the <productname>PostgreSQL</productname>
686 statistics views in combination with operating system utilities for a more
687 complete picture of their database's I/O performance.
688 </para>
690 </sect2>
692 <sect2 id="monitoring-pg-stat-activity-view">
693 <title><structname>pg_stat_activity</structname></title>
695 <indexterm>
696 <primary>pg_stat_activity</primary>
697 </indexterm>
699 <para>
700 The <structname>pg_stat_activity</structname> view will have one row
701 per server process, showing information related to
702 the current activity of that process.
703 </para>
705 <table id="pg-stat-activity-view" xreflabel="pg_stat_activity">
706 <title><structname>pg_stat_activity</structname> View</title>
707 <tgroup cols="1">
708 <thead>
709 <row>
710 <entry role="catalog_table_entry"><para role="column_definition">
711 Column Type
712 </para>
713 <para>
714 Description
715 </para></entry>
716 </row>
717 </thead>
719 <tbody>
720 <row>
721 <entry role="catalog_table_entry"><para role="column_definition">
722 <structfield>datid</structfield> <type>oid</type>
723 </para>
724 <para>
725 OID of the database this backend is connected to
726 </para></entry>
727 </row>
729 <row>
730 <entry role="catalog_table_entry"><para role="column_definition">
731 <structfield>datname</structfield> <type>name</type>
732 </para>
733 <para>
734 Name of the database this backend is connected to
735 </para></entry>
736 </row>
738 <row>
739 <entry role="catalog_table_entry"><para role="column_definition">
740 <structfield>pid</structfield> <type>integer</type>
741 </para>
742 <para>
743 Process ID of this backend
744 </para></entry>
745 </row>
747 <row>
748 <entry role="catalog_table_entry"><para role="column_definition">
749 <structfield>leader_pid</structfield> <type>integer</type>
750 </para>
751 <para>
752 Process ID of the parallel group leader if this process is a parallel
753 query worker, or process ID of the leader apply worker if this process
754 is a parallel apply worker. <literal>NULL</literal> indicates that this
755 process is a parallel group leader or leader apply worker, or does not
756 participate in any parallel operation.
757 </para></entry>
758 </row>
760 <row>
761 <entry role="catalog_table_entry"><para role="column_definition">
762 <structfield>usesysid</structfield> <type>oid</type>
763 </para>
764 <para>
765 OID of the user logged into this backend
766 </para></entry>
767 </row>
769 <row>
770 <entry role="catalog_table_entry"><para role="column_definition">
771 <structfield>usename</structfield> <type>name</type>
772 </para>
773 <para>
774 Name of the user logged into this backend
775 </para></entry>
776 </row>
778 <row>
779 <entry role="catalog_table_entry"><para role="column_definition">
780 <structfield>application_name</structfield> <type>text</type>
781 </para>
782 <para>
783 Name of the application that is connected
784 to this backend
785 </para></entry>
786 </row>
788 <row>
789 <entry role="catalog_table_entry"><para role="column_definition">
790 <structfield>client_addr</structfield> <type>inet</type>
791 </para>
792 <para>
793 IP address of the client connected to this backend.
794 If this field is null, it indicates either that the client is
795 connected via a Unix socket on the server machine or that this is an
796 internal process such as autovacuum.
797 </para></entry>
798 </row>
800 <row>
801 <entry role="catalog_table_entry"><para role="column_definition">
802 <structfield>client_hostname</structfield> <type>text</type>
803 </para>
804 <para>
805 Host name of the connected client, as reported by a
806 reverse DNS lookup of <structfield>client_addr</structfield>. This field will
807 only be non-null for IP connections, and only when <xref linkend="guc-log-hostname"/> is enabled.
808 </para></entry>
809 </row>
811 <row>
812 <entry role="catalog_table_entry"><para role="column_definition">
813 <structfield>client_port</structfield> <type>integer</type>
814 </para>
815 <para>
816 TCP port number that the client is using for communication
817 with this backend, or <literal>-1</literal> if a Unix socket is used.
818 If this field is null, it indicates that this is an internal server process.
819 </para></entry>
820 </row>
822 <row>
823 <entry role="catalog_table_entry"><para role="column_definition">
824 <structfield>backend_start</structfield> <type>timestamp with time zone</type>
825 </para>
826 <para>
827 Time when this process was started. For client backends,
828 this is the time the client connected to the server.
829 </para></entry>
830 </row>
832 <row>
833 <entry role="catalog_table_entry"><para role="column_definition">
834 <structfield>xact_start</structfield> <type>timestamp with time zone</type>
835 </para>
836 <para>
837 Time when this process' current transaction was started, or null
838 if no transaction is active. If the current
839 query is the first of its transaction, this column is equal to the
840 <structfield>query_start</structfield> column.
841 </para></entry>
842 </row>
844 <row>
845 <entry role="catalog_table_entry"><para role="column_definition">
846 <structfield>query_start</structfield> <type>timestamp with time zone</type>
847 </para>
848 <para>
849 Time when the currently active query was started, or if
850 <structfield>state</structfield> is not <literal>active</literal>, when the last query
851 was started
852 </para></entry>
853 </row>
855 <row>
856 <entry role="catalog_table_entry"><para role="column_definition">
857 <structfield>state_change</structfield> <type>timestamp with time zone</type>
858 </para>
859 <para>
860 Time when the <structfield>state</structfield> was last changed
861 </para></entry>
862 </row>
864 <row>
865 <entry role="catalog_table_entry"><para role="column_definition">
866 <structfield>wait_event_type</structfield> <type>text</type>
867 </para>
868 <para>
869 The type of event for which the backend is waiting, if any;
870 otherwise NULL. See <xref linkend="wait-event-table"/>.
871 </para></entry>
872 </row>
874 <row>
875 <entry role="catalog_table_entry"><para role="column_definition">
876 <structfield>wait_event</structfield> <type>text</type>
877 </para>
878 <para>
879 Wait event name if backend is currently waiting, otherwise NULL.
880 See <xref linkend="wait-event-activity-table"/> through
881 <xref linkend="wait-event-timeout-table"/>.
882 </para></entry>
883 </row>
885 <row>
886 <entry role="catalog_table_entry"><para role="column_definition">
887 <structfield>state</structfield> <type>text</type>
888 </para>
889 <para>
890 Current overall state of this backend.
891 Possible values are:
892 <itemizedlist>
893 <listitem>
894 <para>
895 <literal>active</literal>: The backend is executing a query.
896 </para>
897 </listitem>
898 <listitem>
899 <para>
900 <literal>idle</literal>: The backend is waiting for a new client command.
901 </para>
902 </listitem>
903 <listitem>
904 <para>
905 <literal>idle in transaction</literal>: The backend is in a transaction,
906 but is not currently executing a query.
907 </para>
908 </listitem>
909 <listitem>
910 <para>
911 <literal>idle in transaction (aborted)</literal>: This state is similar to
912 <literal>idle in transaction</literal>, except one of the statements in
913 the transaction caused an error.
914 </para>
915 </listitem>
916 <listitem>
917 <para>
918 <literal>fastpath function call</literal>: The backend is executing a
919 fast-path function.
920 </para>
921 </listitem>
922 <listitem>
923 <para>
924 <literal>disabled</literal>: This state is reported if <xref linkend="guc-track-activities"/> is disabled in this backend.
925 </para>
926 </listitem>
927 </itemizedlist>
928 </para></entry>
929 </row>
931 <row>
932 <entry role="catalog_table_entry"><para role="column_definition">
933 <structfield>backend_xid</structfield> <type>xid</type>
934 </para>
935 <para>
936 Top-level transaction identifier of this backend, if any; see
937 <xref linkend="transaction-id"/>.
938 </para></entry>
939 </row>
941 <row>
942 <entry role="catalog_table_entry"><para role="column_definition">
943 <structfield>backend_xmin</structfield> <type>xid</type>
944 </para>
945 <para>
946 The current backend's <literal>xmin</literal> horizon.
947 </para></entry>
948 </row>
950 <row>
951 <entry role="catalog_table_entry"><para role="column_definition">
952 <structfield>query_id</structfield> <type>bigint</type>
953 </para>
954 <para>
955 Identifier of this backend's most recent query. If
956 <structfield>state</structfield> is <literal>active</literal> this
957 field shows the identifier of the currently executing query. In
958 all other states, it shows the identifier of last query that was
959 executed. Query identifiers are not computed by default so this
960 field will be null unless <xref linkend="guc-compute-query-id"/>
961 parameter is enabled or a third-party module that computes query
962 identifiers is configured.
963 </para></entry>
964 </row>
966 <row>
967 <entry role="catalog_table_entry"><para role="column_definition">
968 <structfield>query</structfield> <type>text</type>
969 </para>
970 <para>
971 Text of this backend's most recent query. If
972 <structfield>state</structfield> is <literal>active</literal> this field shows the
973 currently executing query. In all other states, it shows the last query
974 that was executed. By default the query text is truncated at 1024
975 bytes; this value can be changed via the parameter
976 <xref linkend="guc-track-activity-query-size"/>.
977 </para></entry>
978 </row>
980 <row>
981 <entry role="catalog_table_entry"><para role="column_definition">
982 <structfield>backend_type</structfield> <type>text</type>
983 </para>
984 <para>
985 Type of current backend. Possible types are
986 <literal>autovacuum launcher</literal>, <literal>autovacuum worker</literal>,
987 <literal>logical replication launcher</literal>,
988 <literal>logical replication worker</literal>,
989 <literal>parallel worker</literal>, <literal>background writer</literal>,
990 <literal>client backend</literal>, <literal>checkpointer</literal>,
991 <literal>archiver</literal>, <literal>standalone backend</literal>,
992 <literal>startup</literal>, <literal>walreceiver</literal>,
993 <literal>walsender</literal> and <literal>walwriter</literal>.
994 In addition, background workers registered by extensions may have
995 additional types.
996 </para></entry>
997 </row>
998 </tbody>
999 </tgroup>
1000 </table>
1002 <note>
1003 <para>
1004 The <structfield>wait_event</structfield> and <structfield>state</structfield> columns are
1005 independent. If a backend is in the <literal>active</literal> state,
1006 it may or may not be <literal>waiting</literal> on some event. If the state
1007 is <literal>active</literal> and <structfield>wait_event</structfield> is non-null, it
1008 means that a query is being executed, but is being blocked somewhere
1009 in the system.
1010 </para>
1011 </note>
1013 <table id="wait-event-table">
1014 <title>Wait Event Types</title>
1015 <tgroup cols="2">
1016 <thead>
1017 <row>
1018 <entry>Wait Event Type</entry>
1019 <entry>Description</entry>
1020 </row>
1021 </thead>
1023 <tbody>
1024 <row>
1025 <entry><literal>Activity</literal></entry>
1026 <entry>The server process is idle. This event type indicates a process
1027 waiting for activity in its main processing loop.
1028 <literal>wait_event</literal> will identify the specific wait point;
1029 see <xref linkend="wait-event-activity-table"/>.
1030 </entry>
1031 </row>
1032 <row>
1033 <entry><literal>BufferPin</literal></entry>
1034 <entry>The server process is waiting for exclusive access to
1035 a data buffer. Buffer pin waits can be protracted if
1036 another process holds an open cursor that last read data from the
1037 buffer in question. See <xref linkend="wait-event-bufferpin-table"/>.
1038 </entry>
1039 </row>
1040 <row>
1041 <entry><literal>Client</literal></entry>
1042 <entry>The server process is waiting for activity on a socket
1043 connected to a user application. Thus, the server expects something
1044 to happen that is independent of its internal processes.
1045 <literal>wait_event</literal> will identify the specific wait point;
1046 see <xref linkend="wait-event-client-table"/>.
1047 </entry>
1048 </row>
1049 <row>
1050 <entry><literal>Extension</literal></entry>
1051 <entry>The server process is waiting for some condition defined by an
1052 extension module.
1053 See <xref linkend="wait-event-extension-table"/>.
1054 </entry>
1055 </row>
1056 <row>
1057 <entry><literal>IO</literal></entry>
1058 <entry>The server process is waiting for an I/O operation to complete.
1059 <literal>wait_event</literal> will identify the specific wait point;
1060 see <xref linkend="wait-event-io-table"/>.
1061 </entry>
1062 </row>
1063 <row>
1064 <entry><literal>IPC</literal></entry>
1065 <entry>The server process is waiting for some interaction with
1066 another server process. <literal>wait_event</literal> will
1067 identify the specific wait point;
1068 see <xref linkend="wait-event-ipc-table"/>.
1069 </entry>
1070 </row>
1071 <row>
1072 <entry><literal>Lock</literal></entry>
1073 <entry>The server process is waiting for a heavyweight lock.
1074 Heavyweight locks, also known as lock manager locks or simply locks,
1075 primarily protect SQL-visible objects such as tables. However,
1076 they are also used to ensure mutual exclusion for certain internal
1077 operations such as relation extension. <literal>wait_event</literal>
1078 will identify the type of lock awaited;
1079 see <xref linkend="wait-event-lock-table"/>.
1080 </entry>
1081 </row>
1082 <row>
1083 <entry><literal>LWLock</literal></entry>
1084 <entry> The server process is waiting for a lightweight lock.
1085 Most such locks protect a particular data structure in shared memory.
1086 <literal>wait_event</literal> will contain a name identifying the purpose
1087 of the lightweight lock. (Some locks have specific names; others
1088 are part of a group of locks each with a similar purpose.)
1089 See <xref linkend="wait-event-lwlock-table"/>.
1090 </entry>
1091 </row>
1092 <row>
1093 <entry><literal>Timeout</literal></entry>
1094 <entry>The server process is waiting for a timeout
1095 to expire. <literal>wait_event</literal> will identify the specific wait
1096 point; see <xref linkend="wait-event-timeout-table"/>.
1097 </entry>
1098 </row>
1099 </tbody>
1100 </tgroup>
1101 </table>
1103 &wait_event_types;
1105 <para>
1106 Here is an example of how wait events can be viewed:
1108 <programlisting>
1109 SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event is NOT NULL;
1110 pid | wait_event_type | wait_event
1111 ------+-----------------+------------
1112 2540 | Lock | relation
1113 6644 | LWLock | ProcArray
1114 (2 rows)
1115 </programlisting>
1116 </para>
1118 <note>
1119 <para>
1120 Extensions can add <literal>LWLock</literal> types to the list shown in
1121 <xref linkend="wait-event-lwlock-table"/>. In some cases, the name
1122 assigned by an extension will not be available in all server processes;
1123 so an <literal>LWLock</literal> wait event might be reported as
1124 just <quote><literal>extension</literal></quote> rather than the
1125 extension-assigned name.
1126 </para>
1127 </note>
1128 </sect2>
1130 <sect2 id="monitoring-pg-stat-replication-view">
1131 <title><structname>pg_stat_replication</structname></title>
1133 <indexterm>
1134 <primary>pg_stat_replication</primary>
1135 </indexterm>
1137 <para>
1138 The <structname>pg_stat_replication</structname> view will contain one row
1139 per WAL sender process, showing statistics about replication to that
1140 sender's connected standby server. Only directly connected standbys are
1141 listed; no information is available about downstream standby servers.
1142 </para>
1144 <table id="pg-stat-replication-view" xreflabel="pg_stat_replication">
1145 <title><structname>pg_stat_replication</structname> View</title>
1146 <tgroup cols="1">
1147 <thead>
1148 <row>
1149 <entry role="catalog_table_entry"><para role="column_definition">
1150 Column Type
1151 </para>
1152 <para>
1153 Description
1154 </para></entry>
1155 </row>
1156 </thead>
1158 <tbody>
1159 <row>
1160 <entry role="catalog_table_entry"><para role="column_definition">
1161 <structfield>pid</structfield> <type>integer</type>
1162 </para>
1163 <para>
1164 Process ID of a WAL sender process
1165 </para></entry>
1166 </row>
1168 <row>
1169 <entry role="catalog_table_entry"><para role="column_definition">
1170 <structfield>usesysid</structfield> <type>oid</type>
1171 </para>
1172 <para>
1173 OID of the user logged into this WAL sender process
1174 </para></entry>
1175 </row>
1177 <row>
1178 <entry role="catalog_table_entry"><para role="column_definition">
1179 <structfield>usename</structfield> <type>name</type>
1180 </para>
1181 <para>
1182 Name of the user logged into this WAL sender process
1183 </para></entry>
1184 </row>
1186 <row>
1187 <entry role="catalog_table_entry"><para role="column_definition">
1188 <structfield>application_name</structfield> <type>text</type>
1189 </para>
1190 <para>
1191 Name of the application that is connected
1192 to this WAL sender
1193 </para></entry>
1194 </row>
1196 <row>
1197 <entry role="catalog_table_entry"><para role="column_definition">
1198 <structfield>client_addr</structfield> <type>inet</type>
1199 </para>
1200 <para>
1201 IP address of the client connected to this WAL sender.
1202 If this field is null, it indicates that the client is
1203 connected via a Unix socket on the server machine.
1204 </para></entry>
1205 </row>
1207 <row>
1208 <entry role="catalog_table_entry"><para role="column_definition">
1209 <structfield>client_hostname</structfield> <type>text</type>
1210 </para>
1211 <para>
1212 Host name of the connected client, as reported by a
1213 reverse DNS lookup of <structfield>client_addr</structfield>. This field will
1214 only be non-null for IP connections, and only when <xref linkend="guc-log-hostname"/> is enabled.
1215 </para></entry>
1216 </row>
1218 <row>
1219 <entry role="catalog_table_entry"><para role="column_definition">
1220 <structfield>client_port</structfield> <type>integer</type>
1221 </para>
1222 <para>
1223 TCP port number that the client is using for communication
1224 with this WAL sender, or <literal>-1</literal> if a Unix socket is used
1225 </para></entry>
1226 </row>
1228 <row>
1229 <entry role="catalog_table_entry"><para role="column_definition">
1230 <structfield>backend_start</structfield> <type>timestamp with time zone</type>
1231 </para>
1232 <para>
1233 Time when this process was started, i.e., when the
1234 client connected to this WAL sender
1235 </para></entry>
1236 </row>
1238 <row>
1239 <entry role="catalog_table_entry"><para role="column_definition">
1240 <structfield>backend_xmin</structfield> <type>xid</type>
1241 </para>
1242 <para>
1243 This standby's <literal>xmin</literal> horizon reported
1244 by <xref linkend="guc-hot-standby-feedback"/>.
1245 </para></entry>
1246 </row>
1248 <row>
1249 <entry role="catalog_table_entry"><para role="column_definition">
1250 <structfield>state</structfield> <type>text</type>
1251 </para>
1252 <para>
1253 Current WAL sender state.
1254 Possible values are:
1255 <itemizedlist>
1256 <listitem>
1257 <para>
1258 <literal>startup</literal>: This WAL sender is starting up.
1259 </para>
1260 </listitem>
1261 <listitem>
1262 <para>
1263 <literal>catchup</literal>: This WAL sender's connected standby is
1264 catching up with the primary.
1265 </para>
1266 </listitem>
1267 <listitem>
1268 <para>
1269 <literal>streaming</literal>: This WAL sender is streaming changes
1270 after its connected standby server has caught up with the primary.
1271 </para>
1272 </listitem>
1273 <listitem>
1274 <para>
1275 <literal>backup</literal>: This WAL sender is sending a backup.
1276 </para>
1277 </listitem>
1278 <listitem>
1279 <para>
1280 <literal>stopping</literal>: This WAL sender is stopping.
1281 </para>
1282 </listitem>
1283 </itemizedlist>
1284 </para></entry>
1285 </row>
1287 <row>
1288 <entry role="catalog_table_entry"><para role="column_definition">
1289 <structfield>sent_lsn</structfield> <type>pg_lsn</type>
1290 </para>
1291 <para>
1292 Last write-ahead log location sent on this connection
1293 </para></entry>
1294 </row>
1296 <row>
1297 <entry role="catalog_table_entry"><para role="column_definition">
1298 <structfield>write_lsn</structfield> <type>pg_lsn</type>
1299 </para>
1300 <para>
1301 Last write-ahead log location written to disk by this standby
1302 server
1303 </para></entry>
1304 </row>
1306 <row>
1307 <entry role="catalog_table_entry"><para role="column_definition">
1308 <structfield>flush_lsn</structfield> <type>pg_lsn</type>
1309 </para>
1310 <para>
1311 Last write-ahead log location flushed to disk by this standby
1312 server
1313 </para></entry>
1314 </row>
1316 <row>
1317 <entry role="catalog_table_entry"><para role="column_definition">
1318 <structfield>replay_lsn</structfield> <type>pg_lsn</type>
1319 </para>
1320 <para>
1321 Last write-ahead log location replayed into the database on this
1322 standby server
1323 </para></entry>
1324 </row>
1326 <row>
1327 <entry role="catalog_table_entry"><para role="column_definition">
1328 <structfield>write_lag</structfield> <type>interval</type>
1329 </para>
1330 <para>
1331 Time elapsed between flushing recent WAL locally and receiving
1332 notification that this standby server has written it (but not yet
1333 flushed it or applied it). This can be used to gauge the delay that
1334 <literal>synchronous_commit</literal> level
1335 <literal>remote_write</literal> incurred while committing if this
1336 server was configured as a synchronous standby.
1337 </para></entry>
1338 </row>
1340 <row>
1341 <entry role="catalog_table_entry"><para role="column_definition">
1342 <structfield>flush_lag</structfield> <type>interval</type>
1343 </para>
1344 <para>
1345 Time elapsed between flushing recent WAL locally and receiving
1346 notification that this standby server has written and flushed it
1347 (but not yet applied it). This can be used to gauge the delay that
1348 <literal>synchronous_commit</literal> level
1349 <literal>on</literal> incurred while committing if this
1350 server was configured as a synchronous standby.
1351 </para></entry>
1352 </row>
1354 <row>
1355 <entry role="catalog_table_entry"><para role="column_definition">
1356 <structfield>replay_lag</structfield> <type>interval</type>
1357 </para>
1358 <para>
1359 Time elapsed between flushing recent WAL locally and receiving
1360 notification that this standby server has written, flushed and
1361 applied it. This can be used to gauge the delay that
1362 <literal>synchronous_commit</literal> level
1363 <literal>remote_apply</literal> incurred while committing if this
1364 server was configured as a synchronous standby.
1365 </para></entry>
1366 </row>
1368 <row>
1369 <entry role="catalog_table_entry"><para role="column_definition">
1370 <structfield>sync_priority</structfield> <type>integer</type>
1371 </para>
1372 <para>
1373 Priority of this standby server for being chosen as the
1374 synchronous standby in a priority-based synchronous replication.
1375 This has no effect in a quorum-based synchronous replication.
1376 </para></entry>
1377 </row>
1379 <row>
1380 <entry role="catalog_table_entry"><para role="column_definition">
1381 <structfield>sync_state</structfield> <type>text</type>
1382 </para>
1383 <para>
1384 Synchronous state of this standby server.
1385 Possible values are:
1386 <itemizedlist>
1387 <listitem>
1388 <para>
1389 <literal>async</literal>: This standby server is asynchronous.
1390 </para>
1391 </listitem>
1392 <listitem>
1393 <para>
1394 <literal>potential</literal>: This standby server is now asynchronous,
1395 but can potentially become synchronous if one of current
1396 synchronous ones fails.
1397 </para>
1398 </listitem>
1399 <listitem>
1400 <para>
1401 <literal>sync</literal>: This standby server is synchronous.
1402 </para>
1403 </listitem>
1404 <listitem>
1405 <para>
1406 <literal>quorum</literal>: This standby server is considered as a candidate
1407 for quorum standbys.
1408 </para>
1409 </listitem>
1410 </itemizedlist>
1411 </para></entry>
1412 </row>
1414 <row>
1415 <entry role="catalog_table_entry"><para role="column_definition">
1416 <structfield>reply_time</structfield> <type>timestamp with time zone</type>
1417 </para>
1418 <para>
1419 Send time of last reply message received from standby server
1420 </para></entry>
1421 </row>
1422 </tbody>
1423 </tgroup>
1424 </table>
1426 <para>
1427 The lag times reported in the <structname>pg_stat_replication</structname>
1428 view are measurements of the time taken for recent WAL to be written,
1429 flushed and replayed and for the sender to know about it. These times
1430 represent the commit delay that was (or would have been) introduced by each
1431 synchronous commit level, if the remote server was configured as a
1432 synchronous standby. For an asynchronous standby, the
1433 <structfield>replay_lag</structfield> column approximates the delay
1434 before recent transactions became visible to queries. If the standby
1435 server has entirely caught up with the sending server and there is no more
1436 WAL activity, the most recently measured lag times will continue to be
1437 displayed for a short time and then show NULL.
1438 </para>
1440 <para>
1441 Lag times work automatically for physical replication. Logical decoding
1442 plugins may optionally emit tracking messages; if they do not, the tracking
1443 mechanism will simply display NULL lag.
1444 </para>
1446 <note>
1447 <para>
1448 The reported lag times are not predictions of how long it will take for
1449 the standby to catch up with the sending server assuming the current
1450 rate of replay. Such a system would show similar times while new WAL is
1451 being generated, but would differ when the sender becomes idle. In
1452 particular, when the standby has caught up completely,
1453 <structname>pg_stat_replication</structname> shows the time taken to
1454 write, flush and replay the most recent reported WAL location rather than
1455 zero as some users might expect. This is consistent with the goal of
1456 measuring synchronous commit and transaction visibility delays for
1457 recent write transactions.
1458 To reduce confusion for users expecting a different model of lag, the
1459 lag columns revert to NULL after a short time on a fully replayed idle
1460 system. Monitoring systems should choose whether to represent this
1461 as missing data, zero or continue to display the last known value.
1462 </para>
1463 </note>
1465 </sect2>
1467 <sect2 id="monitoring-pg-stat-replication-slots-view">
1468 <title><structname>pg_stat_replication_slots</structname></title>
1470 <indexterm>
1471 <primary>pg_stat_replication_slots</primary>
1472 </indexterm>
1474 <para>
1475 The <structname>pg_stat_replication_slots</structname> view will contain
1476 one row per logical replication slot, showing statistics about its usage.
1477 </para>
1479 <table id="pg-stat-replication-slots-view" xreflabel="pg_stat_replication_slots">
1480 <title><structname>pg_stat_replication_slots</structname> View</title>
1481 <tgroup cols="1">
1482 <thead>
1483 <row>
1484 <entry role="catalog_table_entry"><para role="column_definition">
1485 Column Type
1486 </para>
1487 <para>
1488 Description
1489 </para></entry>
1490 </row>
1491 </thead>
1493 <tbody>
1494 <row>
1495 <entry role="catalog_table_entry"><para role="column_definition">
1496 <structfield>slot_name</structfield> <type>text</type>
1497 </para>
1498 <para>
1499 A unique, cluster-wide identifier for the replication slot
1500 </para></entry>
1501 </row>
1503 <row>
1504 <entry role="catalog_table_entry"><para role="column_definition">
1505 <structfield>spill_txns</structfield> <type>bigint</type>
1506 </para>
1507 <para>
1508 Number of transactions spilled to disk once the memory used by
1509 logical decoding to decode changes from WAL has exceeded
1510 <literal>logical_decoding_work_mem</literal>. The counter gets
1511 incremented for both top-level transactions and subtransactions.
1512 </para></entry>
1513 </row>
1515 <row>
1516 <entry role="catalog_table_entry"><para role="column_definition">
1517 <structfield>spill_count</structfield> <type>bigint</type>
1518 </para>
1519 <para>
1520 Number of times transactions were spilled to disk while decoding
1521 changes from WAL for this slot. This counter is incremented each time
1522 a transaction is spilled, and the same transaction may be spilled
1523 multiple times.
1524 </para></entry>
1525 </row>
1527 <row>
1528 <entry role="catalog_table_entry"><para role="column_definition">
1529 <structfield>spill_bytes</structfield> <type>bigint</type>
1530 </para>
1531 <para>
1532 Amount of decoded transaction data spilled to disk while performing
1533 decoding of changes from WAL for this slot. This and other spill
1534 counters can be used to gauge the I/O which occurred during logical
1535 decoding and allow tuning <literal>logical_decoding_work_mem</literal>.
1536 </para></entry>
1537 </row>
1539 <row>
1540 <entry role="catalog_table_entry"><para role="column_definition">
1541 <structfield>stream_txns</structfield> <type>bigint</type>
1542 </para>
1543 <para>
1544 Number of in-progress transactions streamed to the decoding output
1545 plugin after the memory used by logical decoding to decode changes
1546 from WAL for this slot has exceeded
1547 <literal>logical_decoding_work_mem</literal>. Streaming only
1548 works with top-level transactions (subtransactions can't be streamed
1549 independently), so the counter is not incremented for subtransactions.
1550 </para></entry>
1551 </row>
1553 <row>
1554 <entry role="catalog_table_entry"><para role="column_definition">
1555 <structfield>stream_count</structfield><type>bigint</type>
1556 </para>
1557 <para>
1558 Number of times in-progress transactions were streamed to the decoding
1559 output plugin while decoding changes from WAL for this slot. This
1560 counter is incremented each time a transaction is streamed, and the
1561 same transaction may be streamed multiple times.
1562 </para></entry>
1563 </row>
1565 <row>
1566 <entry role="catalog_table_entry"><para role="column_definition">
1567 <structfield>stream_bytes</structfield><type>bigint</type>
1568 </para>
1569 <para>
1570 Amount of transaction data decoded for streaming in-progress
1571 transactions to the decoding output plugin while decoding changes from
1572 WAL for this slot. This and other streaming counters for this slot can
1573 be used to tune <literal>logical_decoding_work_mem</literal>.
1574 </para>
1575 </entry>
1576 </row>
1578 <row>
1579 <entry role="catalog_table_entry"><para role="column_definition">
1580 <structfield>total_txns</structfield> <type>bigint</type>
1581 </para>
1582 <para>
1583 Number of decoded transactions sent to the decoding output plugin for
1584 this slot. This counts top-level transactions only, and is not incremented
1585 for subtransactions. Note that this includes the transactions that are
1586 streamed and/or spilled.
1587 </para></entry>
1588 </row>
1590 <row>
1591 <entry role="catalog_table_entry"><para role="column_definition">
1592 <structfield>total_bytes</structfield><type>bigint</type>
1593 </para>
1594 <para>
1595 Amount of transaction data decoded for sending transactions to the
1596 decoding output plugin while decoding changes from WAL for this slot.
1597 Note that this includes data that is streamed and/or spilled.
1598 </para>
1599 </entry>
1600 </row>
1602 <row>
1603 <entry role="catalog_table_entry"><para role="column_definition">
1604 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
1605 </para>
1606 <para>
1607 Time at which these statistics were last reset
1608 </para></entry>
1609 </row>
1610 </tbody>
1611 </tgroup>
1612 </table>
1614 </sect2>
1616 <sect2 id="monitoring-pg-stat-wal-receiver-view">
1617 <title><structname>pg_stat_wal_receiver</structname></title>
1619 <indexterm>
1620 <primary>pg_stat_wal_receiver</primary>
1621 </indexterm>
1623 <para>
1624 The <structname>pg_stat_wal_receiver</structname> view will contain only
1625 one row, showing statistics about the WAL receiver from that receiver's
1626 connected server.
1627 </para>
1629 <table id="pg-stat-wal-receiver-view" xreflabel="pg_stat_wal_receiver">
1630 <title><structname>pg_stat_wal_receiver</structname> View</title>
1631 <tgroup cols="1">
1632 <thead>
1633 <row>
1634 <entry role="catalog_table_entry"><para role="column_definition">
1635 Column Type
1636 </para>
1637 <para>
1638 Description
1639 </para></entry>
1640 </row>
1641 </thead>
1643 <tbody>
1644 <row>
1645 <entry role="catalog_table_entry"><para role="column_definition">
1646 <structfield>pid</structfield> <type>integer</type>
1647 </para>
1648 <para>
1649 Process ID of the WAL receiver process
1650 </para></entry>
1651 </row>
1653 <row>
1654 <entry role="catalog_table_entry"><para role="column_definition">
1655 <structfield>status</structfield> <type>text</type>
1656 </para>
1657 <para>
1658 Activity status of the WAL receiver process
1659 </para></entry>
1660 </row>
1662 <row>
1663 <entry role="catalog_table_entry"><para role="column_definition">
1664 <structfield>receive_start_lsn</structfield> <type>pg_lsn</type>
1665 </para>
1666 <para>
1667 First write-ahead log location used when WAL receiver is
1668 started
1669 </para></entry>
1670 </row>
1672 <row>
1673 <entry role="catalog_table_entry"><para role="column_definition">
1674 <structfield>receive_start_tli</structfield> <type>integer</type>
1675 </para>
1676 <para>
1677 First timeline number used when WAL receiver is started
1678 </para></entry>
1679 </row>
1681 <row>
1682 <entry role="catalog_table_entry"><para role="column_definition">
1683 <structfield>written_lsn</structfield> <type>pg_lsn</type>
1684 </para>
1685 <para>
1686 Last write-ahead log location already received and written to disk,
1687 but not flushed. This should not be used for data integrity checks.
1688 </para></entry>
1689 </row>
1691 <row>
1692 <entry role="catalog_table_entry"><para role="column_definition">
1693 <structfield>flushed_lsn</structfield> <type>pg_lsn</type>
1694 </para>
1695 <para>
1696 Last write-ahead log location already received and flushed to
1697 disk, the initial value of this field being the first log location used
1698 when WAL receiver is started
1699 </para></entry>
1700 </row>
1702 <row>
1703 <entry role="catalog_table_entry"><para role="column_definition">
1704 <structfield>received_tli</structfield> <type>integer</type>
1705 </para>
1706 <para>
1707 Timeline number of last write-ahead log location received and
1708 flushed to disk, the initial value of this field being the timeline
1709 number of the first log location used when WAL receiver is started
1710 </para></entry>
1711 </row>
1713 <row>
1714 <entry role="catalog_table_entry"><para role="column_definition">
1715 <structfield>last_msg_send_time</structfield> <type>timestamp with time zone</type>
1716 </para>
1717 <para>
1718 Send time of last message received from origin WAL sender
1719 </para></entry>
1720 </row>
1722 <row>
1723 <entry role="catalog_table_entry"><para role="column_definition">
1724 <structfield>last_msg_receipt_time</structfield> <type>timestamp with time zone</type>
1725 </para>
1726 <para>
1727 Receipt time of last message received from origin WAL sender
1728 </para></entry>
1729 </row>
1731 <row>
1732 <entry role="catalog_table_entry"><para role="column_definition">
1733 <structfield>latest_end_lsn</structfield> <type>pg_lsn</type>
1734 </para>
1735 <para>
1736 Last write-ahead log location reported to origin WAL sender
1737 </para></entry>
1738 </row>
1740 <row>
1741 <entry role="catalog_table_entry"><para role="column_definition">
1742 <structfield>latest_end_time</structfield> <type>timestamp with time zone</type>
1743 </para>
1744 <para>
1745 Time of last write-ahead log location reported to origin WAL sender
1746 </para></entry>
1747 </row>
1749 <row>
1750 <entry role="catalog_table_entry"><para role="column_definition">
1751 <structfield>slot_name</structfield> <type>text</type>
1752 </para>
1753 <para>
1754 Replication slot name used by this WAL receiver
1755 </para></entry>
1756 </row>
1758 <row>
1759 <entry role="catalog_table_entry"><para role="column_definition">
1760 <structfield>sender_host</structfield> <type>text</type>
1761 </para>
1762 <para>
1763 Host of the <productname>PostgreSQL</productname> instance
1764 this WAL receiver is connected to. This can be a host name,
1765 an IP address, or a directory path if the connection is via
1766 Unix socket. (The path case can be distinguished because it
1767 will always be an absolute path, beginning with <literal>/</literal>.)
1768 </para></entry>
1769 </row>
1771 <row>
1772 <entry role="catalog_table_entry"><para role="column_definition">
1773 <structfield>sender_port</structfield> <type>integer</type>
1774 </para>
1775 <para>
1776 Port number of the <productname>PostgreSQL</productname> instance
1777 this WAL receiver is connected to.
1778 </para></entry>
1779 </row>
1781 <row>
1782 <entry role="catalog_table_entry"><para role="column_definition">
1783 <structfield>conninfo</structfield> <type>text</type>
1784 </para>
1785 <para>
1786 Connection string used by this WAL receiver,
1787 with security-sensitive fields obfuscated.
1788 </para></entry>
1789 </row>
1790 </tbody>
1791 </tgroup>
1792 </table>
1794 </sect2>
1796 <sect2 id="monitoring-pg-stat-recovery-prefetch">
1797 <title><structname>pg_stat_recovery_prefetch</structname></title>
1799 <indexterm>
1800 <primary>pg_stat_recovery_prefetch</primary>
1801 </indexterm>
1803 <para>
1804 The <structname>pg_stat_recovery_prefetch</structname> view will contain
1805 only one row. The columns <structfield>wal_distance</structfield>,
1806 <structfield>block_distance</structfield> and
1807 <structfield>io_depth</structfield> show current values, and the
1808 other columns show cumulative counters that can be reset
1809 with the <function>pg_stat_reset_shared</function> function.
1810 </para>
1812 <table id="pg-stat-recovery-prefetch-view" xreflabel="pg_stat_recovery_prefetch">
1813 <title><structname>pg_stat_recovery_prefetch</structname> View</title>
1814 <tgroup cols="1">
1815 <thead>
1816 <row>
1817 <entry role="catalog_table_entry"><para role="column_definition">
1818 Column Type
1819 </para>
1820 <para>
1821 Description
1822 </para></entry>
1823 </row>
1824 </thead>
1826 <tbody>
1827 <row>
1828 <entry role="catalog_table_entry">
1829 <para role="column_definition">
1830 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
1831 </para>
1832 <para>
1833 Time at which these statistics were last reset
1834 </para>
1835 </entry>
1836 </row>
1838 <row>
1839 <entry role="catalog_table_entry">
1840 <para role="column_definition">
1841 <structfield>prefetch</structfield> <type>bigint</type>
1842 </para>
1843 <para>
1844 Number of blocks prefetched because they were not in the buffer pool
1845 </para>
1846 </entry>
1847 </row>
1849 <row>
1850 <entry role="catalog_table_entry">
1851 <para role="column_definition">
1852 <structfield>hit</structfield> <type>bigint</type>
1853 </para>
1854 <para>
1855 Number of blocks not prefetched because they were already in the buffer pool
1856 </para>
1857 </entry>
1858 </row>
1860 <row>
1861 <entry role="catalog_table_entry">
1862 <para role="column_definition">
1863 <structfield>skip_init</structfield> <type>bigint</type>
1864 </para>
1865 <para>
1866 Number of blocks not prefetched because they would be zero-initialized
1867 </para>
1868 </entry>
1869 </row>
1871 <row>
1872 <entry role="catalog_table_entry">
1873 <para role="column_definition">
1874 <structfield>skip_new</structfield> <type>bigint</type>
1875 </para>
1876 <para>
1877 Number of blocks not prefetched because they didn't exist yet
1878 </para>
1879 </entry>
1880 </row>
1882 <row>
1883 <entry role="catalog_table_entry">
1884 <para role="column_definition">
1885 <structfield>skip_fpw</structfield> <type>bigint</type>
1886 </para>
1887 <para>
1888 Number of blocks not prefetched because a full page image was included in the WAL
1889 </para>
1890 </entry>
1891 </row>
1893 <row>
1894 <entry role="catalog_table_entry">
1895 <para role="column_definition">
1896 <structfield>skip_rep</structfield> <type>bigint</type>
1897 </para>
1898 <para>
1899 Number of blocks not prefetched because they were already recently prefetched
1900 </para>
1901 </entry>
1902 </row>
1904 <row>
1905 <entry role="catalog_table_entry">
1906 <para role="column_definition">
1907 <structfield>wal_distance</structfield> <type>int</type>
1908 </para>
1909 <para>
1910 How many bytes ahead the prefetcher is looking
1911 </para>
1912 </entry>
1913 </row>
1915 <row>
1916 <entry role="catalog_table_entry">
1917 <para role="column_definition">
1918 <structfield>block_distance</structfield> <type>int</type>
1919 </para>
1920 <para>
1921 How many blocks ahead the prefetcher is looking
1922 </para>
1923 </entry>
1924 </row>
1926 <row>
1927 <entry role="catalog_table_entry">
1928 <para role="column_definition">
1929 <structfield>io_depth</structfield> <type>int</type>
1930 </para>
1931 <para>
1932 How many prefetches have been initiated but are not yet known to have completed
1933 </para>
1934 </entry>
1935 </row>
1936 </tbody>
1937 </tgroup>
1938 </table>
1940 </sect2>
1942 <sect2 id="monitoring-pg-stat-subscription">
1943 <title><structname>pg_stat_subscription</structname></title>
1945 <indexterm>
1946 <primary>pg_stat_subscription</primary>
1947 </indexterm>
1949 <table id="pg-stat-subscription" xreflabel="pg_stat_subscription">
1950 <title><structname>pg_stat_subscription</structname> View</title>
1951 <tgroup cols="1">
1952 <thead>
1953 <row>
1954 <entry role="catalog_table_entry"><para role="column_definition">
1955 Column Type
1956 </para>
1957 <para>
1958 Description
1959 </para></entry>
1960 </row>
1961 </thead>
1963 <tbody>
1964 <row>
1965 <entry role="catalog_table_entry"><para role="column_definition">
1966 <structfield>subid</structfield> <type>oid</type>
1967 </para>
1968 <para>
1969 OID of the subscription
1970 </para></entry>
1971 </row>
1973 <row>
1974 <entry role="catalog_table_entry"><para role="column_definition">
1975 <structfield>subname</structfield> <type>name</type>
1976 </para>
1977 <para>
1978 Name of the subscription
1979 </para></entry>
1980 </row>
1982 <row>
1983 <entry role="catalog_table_entry"><para role="column_definition">
1984 <structfield>pid</structfield> <type>integer</type>
1985 </para>
1986 <para>
1987 Process ID of the subscription worker process
1988 </para></entry>
1989 </row>
1991 <row>
1992 <entry role="catalog_table_entry"><para role="column_definition">
1993 <structfield>leader_pid</structfield> <type>integer</type>
1994 </para>
1995 <para>
1996 Process ID of the leader apply worker if this process is a parallel
1997 apply worker; NULL if this process is a leader apply worker or a
1998 synchronization worker
1999 </para></entry>
2000 </row>
2002 <row>
2003 <entry role="catalog_table_entry"><para role="column_definition">
2004 <structfield>relid</structfield> <type>oid</type>
2005 </para>
2006 <para>
2007 OID of the relation that the worker is synchronizing; NULL for the
2008 leader apply worker and parallel apply workers
2009 </para></entry>
2010 </row>
2012 <row>
2013 <entry role="catalog_table_entry"><para role="column_definition">
2014 <structfield>received_lsn</structfield> <type>pg_lsn</type>
2015 </para>
2016 <para>
2017 Last write-ahead log location received, the initial value of
2018 this field being 0; NULL for parallel apply workers
2019 </para></entry>
2020 </row>
2022 <row>
2023 <entry role="catalog_table_entry"><para role="column_definition">
2024 <structfield>last_msg_send_time</structfield> <type>timestamp with time zone</type>
2025 </para>
2026 <para>
2027 Send time of last message received from origin WAL sender; NULL for
2028 parallel apply workers
2029 </para></entry>
2030 </row>
2032 <row>
2033 <entry role="catalog_table_entry"><para role="column_definition">
2034 <structfield>last_msg_receipt_time</structfield> <type>timestamp with time zone</type>
2035 </para>
2036 <para>
2037 Receipt time of last message received from origin WAL sender; NULL for
2038 parallel apply workers
2039 </para></entry>
2040 </row>
2042 <row>
2043 <entry role="catalog_table_entry"><para role="column_definition">
2044 <structfield>latest_end_lsn</structfield> <type>pg_lsn</type>
2045 </para>
2046 <para>
2047 Last write-ahead log location reported to origin WAL sender; NULL for
2048 parallel apply workers
2049 </para></entry>
2050 </row>
2052 <row>
2053 <entry role="catalog_table_entry"><para role="column_definition">
2054 <structfield>latest_end_time</structfield> <type>timestamp with time zone</type>
2055 </para>
2056 <para>
2057 Time of last write-ahead log location reported to origin WAL
2058 sender; NULL for parallel apply workers
2059 </para></entry>
2060 </row>
2061 </tbody>
2062 </tgroup>
2063 </table>
2065 </sect2>
2067 <sect2 id="monitoring-pg-stat-subscription-stats">
2068 <title><structname>pg_stat_subscription_stats</structname></title>
2070 <indexterm>
2071 <primary>pg_stat_subscription_stats</primary>
2072 </indexterm>
2074 <para>
2075 The <structname>pg_stat_subscription_stats</structname> view will contain
2076 one row per subscription.
2077 </para>
2079 <table id="pg-stat-subscription-stats" xreflabel="pg_stat_subscription_stats">
2080 <title><structname>pg_stat_subscription_stats</structname> View</title>
2081 <tgroup cols="1">
2082 <thead>
2083 <row>
2084 <entry role="catalog_table_entry"><para role="column_definition">
2085 Column Type
2086 </para>
2087 <para>
2088 Description
2089 </para></entry>
2090 </row>
2091 </thead>
2093 <tbody>
2094 <row>
2095 <entry role="catalog_table_entry"><para role="column_definition">
2096 <structfield>subid</structfield> <type>oid</type>
2097 </para>
2098 <para>
2099 OID of the subscription
2100 </para></entry>
2101 </row>
2103 <row>
2104 <entry role="catalog_table_entry"><para role="column_definition">
2105 <structfield>subname</structfield> <type>name</type>
2106 </para>
2107 <para>
2108 Name of the subscription
2109 </para></entry>
2110 </row>
2112 <row>
2113 <entry role="catalog_table_entry"><para role="column_definition">
2114 <structfield>apply_error_count</structfield> <type>bigint</type>
2115 </para>
2116 <para>
2117 Number of times an error occurred while applying changes
2118 </para></entry>
2119 </row>
2121 <row>
2122 <entry role="catalog_table_entry"><para role="column_definition">
2123 <structfield>sync_error_count</structfield> <type>bigint</type>
2124 </para>
2125 <para>
2126 Number of times an error occurred during the initial table
2127 synchronization
2128 </para></entry>
2129 </row>
2131 <row>
2132 <entry role="catalog_table_entry"><para role="column_definition">
2133 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
2134 </para>
2135 <para>
2136 Time at which these statistics were last reset
2137 </para></entry>
2138 </row>
2139 </tbody>
2140 </tgroup>
2141 </table>
2143 </sect2>
2145 <sect2 id="monitoring-pg-stat-ssl-view">
2146 <title><structname>pg_stat_ssl</structname></title>
2148 <indexterm>
2149 <primary>pg_stat_ssl</primary>
2150 </indexterm>
2152 <para>
2153 The <structname>pg_stat_ssl</structname> view will contain one row per
2154 backend or WAL sender process, showing statistics about SSL usage on
2155 this connection. It can be joined to <structname>pg_stat_activity</structname>
2156 or <structname>pg_stat_replication</structname> on the
2157 <structfield>pid</structfield> column to get more details about the
2158 connection.
2159 </para>
2161 <table id="pg-stat-ssl-view" xreflabel="pg_stat_ssl">
2162 <title><structname>pg_stat_ssl</structname> View</title>
2163 <tgroup cols="1">
2164 <thead>
2165 <row>
2166 <entry role="catalog_table_entry"><para role="column_definition">
2167 Column Type
2168 </para>
2169 <para>
2170 Description
2171 </para></entry>
2172 </row>
2173 </thead>
2175 <tbody>
2176 <row>
2177 <entry role="catalog_table_entry"><para role="column_definition">
2178 <structfield>pid</structfield> <type>integer</type>
2179 </para>
2180 <para>
2181 Process ID of a backend or WAL sender process
2182 </para></entry>
2183 </row>
2185 <row>
2186 <entry role="catalog_table_entry"><para role="column_definition">
2187 <structfield>ssl</structfield> <type>boolean</type>
2188 </para>
2189 <para>
2190 True if SSL is used on this connection
2191 </para></entry>
2192 </row>
2194 <row>
2195 <entry role="catalog_table_entry"><para role="column_definition">
2196 <structfield>version</structfield> <type>text</type>
2197 </para>
2198 <para>
2199 Version of SSL in use, or NULL if SSL is not in use
2200 on this connection
2201 </para></entry>
2202 </row>
2204 <row>
2205 <entry role="catalog_table_entry"><para role="column_definition">
2206 <structfield>cipher</structfield> <type>text</type>
2207 </para>
2208 <para>
2209 Name of SSL cipher in use, or NULL if SSL is not in use
2210 on this connection
2211 </para></entry>
2212 </row>
2214 <row>
2215 <entry role="catalog_table_entry"><para role="column_definition">
2216 <structfield>bits</structfield> <type>integer</type>
2217 </para>
2218 <para>
2219 Number of bits in the encryption algorithm used, or NULL
2220 if SSL is not used on this connection
2221 </para></entry>
2222 </row>
2224 <row>
2225 <entry role="catalog_table_entry"><para role="column_definition">
2226 <structfield>client_dn</structfield> <type>text</type>
2227 </para>
2228 <para>
2229 Distinguished Name (DN) field from the client certificate
2230 used, or NULL if no client certificate was supplied or if SSL
2231 is not in use on this connection. This field is truncated if the
2232 DN field is longer than <symbol>NAMEDATALEN</symbol> (64 characters
2233 in a standard build).
2234 </para></entry>
2235 </row>
2237 <row>
2238 <entry role="catalog_table_entry"><para role="column_definition">
2239 <structfield>client_serial</structfield> <type>numeric</type>
2240 </para>
2241 <para>
2242 Serial number of the client certificate, or NULL if no client
2243 certificate was supplied or if SSL is not in use on this connection. The
2244 combination of certificate serial number and certificate issuer uniquely
2245 identifies a certificate (unless the issuer erroneously reuses serial
2246 numbers).
2247 </para></entry>
2248 </row>
2250 <row>
2251 <entry role="catalog_table_entry"><para role="column_definition">
2252 <structfield>issuer_dn</structfield> <type>text</type>
2253 </para>
2254 <para>
2255 DN of the issuer of the client certificate, or NULL if no client
2256 certificate was supplied or if SSL is not in use on this connection.
2257 This field is truncated like <structfield>client_dn</structfield>.
2258 </para></entry>
2259 </row>
2260 </tbody>
2261 </tgroup>
2262 </table>
2264 </sect2>
2266 <sect2 id="monitoring-pg-stat-gssapi-view">
2267 <title><structname>pg_stat_gssapi</structname></title>
2269 <indexterm>
2270 <primary>pg_stat_gssapi</primary>
2271 </indexterm>
2273 <para>
2274 The <structname>pg_stat_gssapi</structname> view will contain one row per
2275 backend, showing information about GSSAPI usage on this connection. It can
2276 be joined to <structname>pg_stat_activity</structname> or
2277 <structname>pg_stat_replication</structname> on the
2278 <structfield>pid</structfield> column to get more details about the
2279 connection.
2280 </para>
2282 <table id="pg-stat-gssapi-view" xreflabel="pg_stat_gssapi">
2283 <title><structname>pg_stat_gssapi</structname> View</title>
2284 <tgroup cols="1">
2285 <thead>
2286 <row>
2287 <entry role="catalog_table_entry"><para role="column_definition">
2288 Column Type
2289 </para>
2290 <para>
2291 Description
2292 </para></entry>
2293 </row>
2294 </thead>
2296 <tbody>
2297 <row>
2298 <entry role="catalog_table_entry"><para role="column_definition">
2299 <structfield>pid</structfield> <type>integer</type>
2300 </para>
2301 <para>
2302 Process ID of a backend
2303 </para></entry>
2304 </row>
2306 <row>
2307 <entry role="catalog_table_entry"><para role="column_definition">
2308 <structfield>gss_authenticated</structfield> <type>boolean</type>
2309 </para>
2310 <para>
2311 True if GSSAPI authentication was used for this connection
2312 </para></entry>
2313 </row>
2315 <row>
2316 <entry role="catalog_table_entry"><para role="column_definition">
2317 <structfield>principal</structfield> <type>text</type>
2318 </para>
2319 <para>
2320 Principal used to authenticate this connection, or NULL
2321 if GSSAPI was not used to authenticate this connection. This
2322 field is truncated if the principal is longer than
2323 <symbol>NAMEDATALEN</symbol> (64 characters in a standard build).
2324 </para></entry>
2325 </row>
2327 <row>
2328 <entry role="catalog_table_entry"><para role="column_definition">
2329 <structfield>encrypted</structfield> <type>boolean</type>
2330 </para>
2331 <para>
2332 True if GSSAPI encryption is in use on this connection
2333 </para></entry>
2334 </row>
2336 <row>
2337 <entry role="catalog_table_entry"><para role="column_definition">
2338 <structfield>credentials_delegated</structfield> <type>boolean</type>
2339 </para>
2340 <para>
2341 True if GSSAPI credentials were delegated on this connection.
2342 </para></entry>
2343 </row>
2344 </tbody>
2345 </tgroup>
2346 </table>
2348 </sect2>
2350 <sect2 id="monitoring-pg-stat-archiver-view">
2351 <title><structname>pg_stat_archiver</structname></title>
2353 <indexterm>
2354 <primary>pg_stat_archiver</primary>
2355 </indexterm>
2357 <para>
2358 The <structname>pg_stat_archiver</structname> view will always have a
2359 single row, containing data about the archiver process of the cluster.
2360 </para>
2362 <table id="pg-stat-archiver-view" xreflabel="pg_stat_archiver">
2363 <title><structname>pg_stat_archiver</structname> View</title>
2364 <tgroup cols="1">
2365 <thead>
2366 <row>
2367 <entry role="catalog_table_entry"><para role="column_definition">
2368 Column Type
2369 </para>
2370 <para>
2371 Description
2372 </para></entry>
2373 </row>
2374 </thead>
2376 <tbody>
2377 <row>
2378 <entry role="catalog_table_entry"><para role="column_definition">
2379 <structfield>archived_count</structfield> <type>bigint</type>
2380 </para>
2381 <para>
2382 Number of WAL files that have been successfully archived
2383 </para></entry>
2384 </row>
2386 <row>
2387 <entry role="catalog_table_entry"><para role="column_definition">
2388 <structfield>last_archived_wal</structfield> <type>text</type>
2389 </para>
2390 <para>
2391 Name of the WAL file most recently successfully archived
2392 </para></entry>
2393 </row>
2395 <row>
2396 <entry role="catalog_table_entry"><para role="column_definition">
2397 <structfield>last_archived_time</structfield> <type>timestamp with time zone</type>
2398 </para>
2399 <para>
2400 Time of the most recent successful archive operation
2401 </para></entry>
2402 </row>
2404 <row>
2405 <entry role="catalog_table_entry"><para role="column_definition">
2406 <structfield>failed_count</structfield> <type>bigint</type>
2407 </para>
2408 <para>
2409 Number of failed attempts for archiving WAL files
2410 </para></entry>
2411 </row>
2413 <row>
2414 <entry role="catalog_table_entry"><para role="column_definition">
2415 <structfield>last_failed_wal</structfield> <type>text</type>
2416 </para>
2417 <para>
2418 Name of the WAL file of the most recent failed archival operation
2419 </para></entry>
2420 </row>
2422 <row>
2423 <entry role="catalog_table_entry"><para role="column_definition">
2424 <structfield>last_failed_time</structfield> <type>timestamp with time zone</type>
2425 </para>
2426 <para>
2427 Time of the most recent failed archival operation
2428 </para></entry>
2429 </row>
2431 <row>
2432 <entry role="catalog_table_entry"><para role="column_definition">
2433 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
2434 </para>
2435 <para>
2436 Time at which these statistics were last reset
2437 </para></entry>
2438 </row>
2439 </tbody>
2440 </tgroup>
2441 </table>
2443 <para>
2444 Normally, WAL files are archived in order, oldest to newest, but that is
2445 not guaranteed, and does not hold under special circumstances like when
2446 promoting a standby or after crash recovery. Therefore it is not safe to
2447 assume that all files older than
2448 <structfield>last_archived_wal</structfield> have also been successfully
2449 archived.
2450 </para>
2451 </sect2>
2453 <sect2 id="monitoring-pg-stat-io-view">
2454 <title><structname>pg_stat_io</structname></title>
2456 <indexterm>
2457 <primary>pg_stat_io</primary>
2458 </indexterm>
2460 <para>
2461 The <structname>pg_stat_io</structname> view will contain one row for each
2462 combination of backend type, target I/O object, and I/O context, showing
2463 cluster-wide I/O statistics. Combinations which do not make sense are
2464 omitted.
2465 </para>
2467 <para>
2468 Currently, I/O on relations (e.g. tables, indexes) is tracked. However,
2469 relation I/O which bypasses shared buffers (e.g. when moving a table from one
2470 tablespace to another) is currently not tracked.
2471 </para>
2473 <table id="pg-stat-io-view" xreflabel="pg_stat_io">
2474 <title><structname>pg_stat_io</structname> View</title>
2475 <tgroup cols="1">
2476 <thead>
2477 <row>
2478 <entry role="catalog_table_entry">
2479 <para role="column_definition">
2480 Column Type
2481 </para>
2482 <para>
2483 Description
2484 </para>
2485 </entry>
2486 </row>
2487 </thead>
2488 <tbody>
2489 <row>
2490 <entry role="catalog_table_entry">
2491 <para role="column_definition">
2492 <structfield>backend_type</structfield> <type>text</type>
2493 </para>
2494 <para>
2495 Type of backend (e.g. background worker, autovacuum worker). See <link
2496 linkend="monitoring-pg-stat-activity-view">
2497 <structname>pg_stat_activity</structname></link> for more information
2498 on <varname>backend_type</varname>s. Some
2499 <varname>backend_type</varname>s do not accumulate I/O operation
2500 statistics and will not be included in the view.
2501 </para>
2502 </entry>
2503 </row>
2505 <row>
2506 <entry role="catalog_table_entry">
2507 <para role="column_definition">
2508 <structfield>object</structfield> <type>text</type>
2509 </para>
2510 <para>
2511 Target object of an I/O operation. Possible values are:
2512 <itemizedlist>
2513 <listitem>
2514 <para>
2515 <literal>relation</literal>: Permanent relations.
2516 </para>
2517 </listitem>
2518 <listitem>
2519 <para>
2520 <literal>temp relation</literal>: Temporary relations.
2521 </para>
2522 </listitem>
2523 </itemizedlist>
2524 </para>
2525 </entry>
2526 </row>
2528 <row>
2529 <entry role="catalog_table_entry">
2530 <para role="column_definition">
2531 <structfield>context</structfield> <type>text</type>
2532 </para>
2533 <para>
2534 The context of an I/O operation. Possible values are:
2535 </para>
2536 <itemizedlist>
2537 <listitem>
2538 <para>
2539 <literal>normal</literal>: The default or standard
2540 <varname>context</varname> for a type of I/O operation. For
2541 example, by default, relation data is read into and written out from
2542 shared buffers. Thus, reads and writes of relation data to and from
2543 shared buffers are tracked in <varname>context</varname>
2544 <literal>normal</literal>.
2545 </para>
2546 </listitem>
2547 <listitem>
2548 <para>
2549 <literal>vacuum</literal>: I/O operations performed outside of shared
2550 buffers while vacuuming and analyzing permanent relations. Temporary
2551 table vacuums use the same local buffer pool as other temporary table
2552 IO operations and are tracked in <varname>context</varname>
2553 <literal>normal</literal>.
2554 </para>
2555 </listitem>
2556 <listitem>
2557 <para>
2558 <literal>bulkread</literal>: Certain large read I/O operations
2559 done outside of shared buffers, for example, a sequential scan of a
2560 large table.
2561 </para>
2562 </listitem>
2563 <listitem>
2564 <para>
2565 <literal>bulkwrite</literal>: Certain large write I/O operations
2566 done outside of shared buffers, such as <command>COPY</command>.
2567 </para>
2568 </listitem>
2569 </itemizedlist>
2570 </entry>
2571 </row>
2573 <row>
2574 <entry role="catalog_table_entry">
2575 <para role="column_definition">
2576 <structfield>reads</structfield> <type>bigint</type>
2577 </para>
2578 <para>
2579 Number of read operations, each of the size specified in
2580 <varname>op_bytes</varname>.
2581 </para>
2582 </entry>
2583 </row>
2585 <row>
2586 <entry role="catalog_table_entry">
2587 <para role="column_definition">
2588 <structfield>read_time</structfield> <type>double precision</type>
2589 </para>
2590 <para>
2591 Time spent in read operations in milliseconds (if
2592 <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
2593 </para>
2594 </entry>
2595 </row>
2597 <row>
2598 <entry role="catalog_table_entry">
2599 <para role="column_definition">
2600 <structfield>writes</structfield> <type>bigint</type>
2601 </para>
2602 <para>
2603 Number of write operations, each of the size specified in
2604 <varname>op_bytes</varname>.
2605 </para>
2606 </entry>
2607 </row>
2609 <row>
2610 <entry role="catalog_table_entry">
2611 <para role="column_definition">
2612 <structfield>write_time</structfield> <type>double precision</type>
2613 </para>
2614 <para>
2615 Time spent in write operations in milliseconds (if
2616 <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
2617 </para>
2618 </entry>
2619 </row>
2621 <row>
2622 <entry role="catalog_table_entry">
2623 <para role="column_definition">
2624 <structfield>writebacks</structfield> <type>bigint</type>
2625 </para>
2626 <para>
2627 Number of units of size <varname>op_bytes</varname> which the process
2628 requested the kernel write out to permanent storage.
2629 </para>
2630 </entry>
2631 </row>
2633 <row>
2634 <entry role="catalog_table_entry">
2635 <para role="column_definition">
2636 <structfield>writeback_time</structfield> <type>double precision</type>
2637 </para>
2638 <para>
2639 Time spent in writeback operations in milliseconds (if
2640 <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero). This
2641 includes the time spent queueing write-out requests and, potentially,
2642 the time spent to write out the dirty data.
2643 </para>
2644 </entry>
2645 </row>
2647 <row>
2648 <entry role="catalog_table_entry">
2649 <para role="column_definition">
2650 <structfield>extends</structfield> <type>bigint</type>
2651 </para>
2652 <para>
2653 Number of relation extend operations, each of the size specified in
2654 <varname>op_bytes</varname>.
2655 </para>
2656 </entry>
2657 </row>
2659 <row>
2660 <entry role="catalog_table_entry">
2661 <para role="column_definition">
2662 <structfield>extend_time</structfield> <type>double precision</type>
2663 </para>
2664 <para>
2665 Time spent in extend operations in milliseconds (if
2666 <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
2667 </para>
2668 </entry>
2669 </row>
2671 <row>
2672 <entry role="catalog_table_entry">
2673 <para role="column_definition">
2674 <structfield>op_bytes</structfield> <type>bigint</type>
2675 </para>
2676 <para>
2677 The number of bytes per unit of I/O read, written, or extended.
2678 </para>
2679 <para>
2680 Relation data reads, writes, and extends are done in
2681 <varname>block_size</varname> units, derived from the build-time
2682 parameter <symbol>BLCKSZ</symbol>, which is <literal>8192</literal> by
2683 default.
2684 </para>
2685 </entry>
2686 </row>
2688 <row>
2689 <entry role="catalog_table_entry">
2690 <para role="column_definition">
2691 <structfield>hits</structfield> <type>bigint</type>
2692 </para>
2693 <para>
2694 The number of times a desired block was found in a shared buffer.
2695 </para>
2696 </entry>
2697 </row>
2699 <row>
2700 <entry role="catalog_table_entry">
2701 <para role="column_definition">
2702 <structfield>evictions</structfield> <type>bigint</type>
2703 </para>
2704 <para>
2705 Number of times a block has been written out from a shared or local
2706 buffer in order to make it available for another use.
2707 </para>
2708 <para>
2709 In <varname>context</varname> <literal>normal</literal>, this counts
2710 the number of times a block was evicted from a buffer and replaced with
2711 another block. In <varname>context</varname>s
2712 <literal>bulkwrite</literal>, <literal>bulkread</literal>, and
2713 <literal>vacuum</literal>, this counts the number of times a block was
2714 evicted from shared buffers in order to add the shared buffer to a
2715 separate, size-limited ring buffer for use in a bulk I/O operation.
2716 </para>
2717 </entry>
2718 </row>
2720 <row>
2721 <entry role="catalog_table_entry">
2722 <para role="column_definition">
2723 <structfield>reuses</structfield> <type>bigint</type>
2724 </para>
2725 <para>
2726 The number of times an existing buffer in a size-limited ring buffer
2727 outside of shared buffers was reused as part of an I/O operation in the
2728 <literal>bulkread</literal>, <literal>bulkwrite</literal>, or
2729 <literal>vacuum</literal> <varname>context</varname>s.
2730 </para>
2731 </entry>
2732 </row>
2734 <row>
2735 <entry role="catalog_table_entry">
2736 <para role="column_definition">
2737 <structfield>fsyncs</structfield> <type>bigint</type>
2738 </para>
2739 <para>
2740 Number of <literal>fsync</literal> calls. These are only tracked in
2741 <varname>context</varname> <literal>normal</literal>.
2742 </para>
2743 </entry>
2744 </row>
2746 <row>
2747 <entry role="catalog_table_entry">
2748 <para role="column_definition">
2749 <structfield>fsync_time</structfield> <type>double precision</type>
2750 </para>
2751 <para>
2752 Time spent in fsync operations in milliseconds (if
2753 <xref linkend="guc-track-io-timing"/> is enabled, otherwise zero)
2754 </para>
2755 </entry>
2756 </row>
2758 <row>
2759 <entry role="catalog_table_entry">
2760 <para role="column_definition">
2761 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
2762 </para>
2763 <para>
2764 Time at which these statistics were last reset.
2765 </para>
2766 </entry>
2767 </row>
2768 </tbody>
2769 </tgroup>
2770 </table>
2772 <para>
2773 Some backend types never perform I/O operations on some I/O objects and/or
2774 in some I/O contexts. These rows are omitted from the view. For example, the
2775 checkpointer does not checkpoint temporary tables, so there will be no rows
2776 for <varname>backend_type</varname> <literal>checkpointer</literal> and
2777 <varname>object</varname> <literal>temp relation</literal>.
2778 </para>
2780 <para>
2781 In addition, some I/O operations will never be performed either by certain
2782 backend types or on certain I/O objects and/or in certain I/O contexts.
2783 These cells will be NULL. For example, temporary tables are not
2784 <literal>fsync</literal>ed, so <varname>fsyncs</varname> will be NULL for
2785 <varname>object</varname> <literal>temp relation</literal>. Also, the
2786 background writer does not perform reads, so <varname>reads</varname> will
2787 be NULL in rows for <varname>backend_type</varname> <literal>background
2788 writer</literal>.
2789 </para>
2791 <para>
2792 <structname>pg_stat_io</structname> can be used to inform database tuning.
2793 For example:
2794 <itemizedlist>
2795 <listitem>
2796 <para>
2797 A high <varname>evictions</varname> count can indicate that shared
2798 buffers should be increased.
2799 </para>
2800 </listitem>
2801 <listitem>
2802 <para>
2803 Client backends rely on the checkpointer to ensure data is persisted to
2804 permanent storage. Large numbers of <varname>fsyncs</varname> by
2805 <literal>client backend</literal>s could indicate a misconfiguration of
2806 shared buffers or of the checkpointer. More information on configuring
2807 the checkpointer can be found in <xref linkend="wal-configuration"/>.
2808 </para>
2809 </listitem>
2810 <listitem>
2811 <para>
2812 Normally, client backends should be able to rely on auxiliary processes
2813 like the checkpointer and the background writer to write out dirty data
2814 as much as possible. Large numbers of writes by client backends could
2815 indicate a misconfiguration of shared buffers or of the checkpointer.
2816 More information on configuring the checkpointer can be found in <xref
2817 linkend="wal-configuration"/>.
2818 </para>
2819 </listitem>
2820 </itemizedlist>
2821 </para>
2823 <note>
2824 <para>
2825 Columns tracking I/O time will only be non-zero when
2826 <xref linkend="guc-track-io-timing"/> is enabled. The user should be
2827 careful when referencing these columns in combination with their
2828 corresponding IO operations in case <varname>track_io_timing</varname>
2829 was not enabled for the entire time since the last stats reset.
2830 </para>
2831 </note>
2835 </sect2>
2837 <sect2 id="monitoring-pg-stat-bgwriter-view">
2838 <title><structname>pg_stat_bgwriter</structname></title>
2840 <indexterm>
2841 <primary>pg_stat_bgwriter</primary>
2842 </indexterm>
2844 <para>
2845 The <structname>pg_stat_bgwriter</structname> view will always have a
2846 single row, containing global data for the cluster.
2847 </para>
2849 <table id="pg-stat-bgwriter-view" xreflabel="pg_stat_bgwriter">
2850 <title><structname>pg_stat_bgwriter</structname> View</title>
2851 <tgroup cols="1">
2852 <thead>
2853 <row>
2854 <entry role="catalog_table_entry"><para role="column_definition">
2855 Column Type
2856 </para>
2857 <para>
2858 Description
2859 </para></entry>
2860 </row>
2861 </thead>
2863 <tbody>
2864 <row>
2865 <entry role="catalog_table_entry"><para role="column_definition">
2866 <structfield>checkpoints_timed</structfield> <type>bigint</type>
2867 </para>
2868 <para>
2869 Number of scheduled checkpoints that have been performed
2870 </para></entry>
2871 </row>
2873 <row>
2874 <entry role="catalog_table_entry"><para role="column_definition">
2875 <structfield>checkpoints_req</structfield> <type>bigint</type>
2876 </para>
2877 <para>
2878 Number of requested checkpoints that have been performed
2879 </para></entry>
2880 </row>
2882 <row>
2883 <entry role="catalog_table_entry"><para role="column_definition">
2884 <structfield>checkpoint_write_time</structfield> <type>double precision</type>
2885 </para>
2886 <para>
2887 Total amount of time that has been spent in the portion of
2888 checkpoint processing where files are written to disk, in milliseconds
2889 </para></entry>
2890 </row>
2892 <row>
2893 <entry role="catalog_table_entry"><para role="column_definition">
2894 <structfield>checkpoint_sync_time</structfield> <type>double precision</type>
2895 </para>
2896 <para>
2897 Total amount of time that has been spent in the portion of
2898 checkpoint processing where files are synchronized to disk, in
2899 milliseconds
2900 </para></entry>
2901 </row>
2903 <row>
2904 <entry role="catalog_table_entry"><para role="column_definition">
2905 <structfield>buffers_checkpoint</structfield> <type>bigint</type>
2906 </para>
2907 <para>
2908 Number of buffers written during checkpoints
2909 </para></entry>
2910 </row>
2912 <row>
2913 <entry role="catalog_table_entry"><para role="column_definition">
2914 <structfield>buffers_clean</structfield> <type>bigint</type>
2915 </para>
2916 <para>
2917 Number of buffers written by the background writer
2918 </para></entry>
2919 </row>
2921 <row>
2922 <entry role="catalog_table_entry"><para role="column_definition">
2923 <structfield>maxwritten_clean</structfield> <type>bigint</type>
2924 </para>
2925 <para>
2926 Number of times the background writer stopped a cleaning
2927 scan because it had written too many buffers
2928 </para></entry>
2929 </row>
2931 <row>
2932 <entry role="catalog_table_entry"><para role="column_definition">
2933 <structfield>buffers_backend</structfield> <type>bigint</type>
2934 </para>
2935 <para>
2936 Number of buffers written directly by a backend
2937 </para></entry>
2938 </row>
2940 <row>
2941 <entry role="catalog_table_entry"><para role="column_definition">
2942 <structfield>buffers_backend_fsync</structfield> <type>bigint</type>
2943 </para>
2944 <para>
2945 Number of times a backend had to execute its own
2946 <function>fsync</function> call (normally the background writer handles those
2947 even when the backend does its own write)
2948 </para></entry>
2949 </row>
2951 <row>
2952 <entry role="catalog_table_entry"><para role="column_definition">
2953 <structfield>buffers_alloc</structfield> <type>bigint</type>
2954 </para>
2955 <para>
2956 Number of buffers allocated
2957 </para></entry>
2958 </row>
2960 <row>
2961 <entry role="catalog_table_entry"><para role="column_definition">
2962 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
2963 </para>
2964 <para>
2965 Time at which these statistics were last reset
2966 </para></entry>
2967 </row>
2968 </tbody>
2969 </tgroup>
2970 </table>
2972 </sect2>
2974 <sect2 id="monitoring-pg-stat-wal-view">
2975 <title><structname>pg_stat_wal</structname></title>
2977 <indexterm>
2978 <primary>pg_stat_wal</primary>
2979 </indexterm>
2981 <para>
2982 The <structname>pg_stat_wal</structname> view will always have a
2983 single row, containing data about WAL activity of the cluster.
2984 </para>
2986 <table id="pg-stat-wal-view" xreflabel="pg_stat_wal">
2987 <title><structname>pg_stat_wal</structname> View</title>
2988 <tgroup cols="1">
2989 <thead>
2990 <row>
2991 <entry role="catalog_table_entry"><para role="column_definition">
2992 Column Type
2993 </para>
2994 <para>
2995 Description
2996 </para></entry>
2997 </row>
2998 </thead>
3000 <tbody>
3001 <row>
3002 <entry role="catalog_table_entry"><para role="column_definition">
3003 <structfield>wal_records</structfield> <type>bigint</type>
3004 </para>
3005 <para>
3006 Total number of WAL records generated
3007 </para></entry>
3008 </row>
3010 <row>
3011 <entry role="catalog_table_entry"><para role="column_definition">
3012 <structfield>wal_fpi</structfield> <type>bigint</type>
3013 </para>
3014 <para>
3015 Total number of WAL full page images generated
3016 </para></entry>
3017 </row>
3019 <row>
3020 <entry role="catalog_table_entry"><para role="column_definition">
3021 <structfield>wal_bytes</structfield> <type>numeric</type>
3022 </para>
3023 <para>
3024 Total amount of WAL generated in bytes
3025 </para></entry>
3026 </row>
3028 <row>
3029 <entry role="catalog_table_entry"><para role="column_definition">
3030 <structfield>wal_buffers_full</structfield> <type>bigint</type>
3031 </para>
3032 <para>
3033 Number of times WAL data was written to disk because WAL buffers became full
3034 </para></entry>
3035 </row>
3037 <row>
3038 <entry role="catalog_table_entry"><para role="column_definition">
3039 <structfield>wal_write</structfield> <type>bigint</type>
3040 </para>
3041 <para>
3042 Number of times WAL buffers were written out to disk via
3043 <function>XLogWrite</function> request.
3044 See <xref linkend="wal-configuration"/> for more information about
3045 the internal WAL function <function>XLogWrite</function>.
3046 </para></entry>
3047 </row>
3049 <row>
3050 <entry role="catalog_table_entry"><para role="column_definition">
3051 <structfield>wal_sync</structfield> <type>bigint</type>
3052 </para>
3053 <para>
3054 Number of times WAL files were synced to disk via
3055 <function>issue_xlog_fsync</function> request
3056 (if <xref linkend="guc-fsync"/> is <literal>on</literal> and
3057 <xref linkend="guc-wal-sync-method"/> is either
3058 <literal>fdatasync</literal>, <literal>fsync</literal> or
3059 <literal>fsync_writethrough</literal>, otherwise zero).
3060 See <xref linkend="wal-configuration"/> for more information about
3061 the internal WAL function <function>issue_xlog_fsync</function>.
3062 </para></entry>
3063 </row>
3065 <row>
3066 <entry role="catalog_table_entry"><para role="column_definition">
3067 <structfield>wal_write_time</structfield> <type>double precision</type>
3068 </para>
3069 <para>
3070 Total amount of time spent writing WAL buffers to disk via
3071 <function>XLogWrite</function> request, in milliseconds
3072 (if <xref linkend="guc-track-wal-io-timing"/> is enabled,
3073 otherwise zero). This includes the sync time when
3074 <varname>wal_sync_method</varname> is either
3075 <literal>open_datasync</literal> or <literal>open_sync</literal>.
3076 </para></entry>
3077 </row>
3079 <row>
3080 <entry role="catalog_table_entry"><para role="column_definition">
3081 <structfield>wal_sync_time</structfield> <type>double precision</type>
3082 </para>
3083 <para>
3084 Total amount of time spent syncing WAL files to disk via
3085 <function>issue_xlog_fsync</function> request, in milliseconds
3086 (if <varname>track_wal_io_timing</varname> is enabled,
3087 <varname>fsync</varname> is <literal>on</literal>, and
3088 <varname>wal_sync_method</varname> is either
3089 <literal>fdatasync</literal>, <literal>fsync</literal> or
3090 <literal>fsync_writethrough</literal>, otherwise zero).
3091 </para></entry>
3092 </row>
3094 <row>
3095 <entry role="catalog_table_entry"><para role="column_definition">
3096 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
3097 </para>
3098 <para>
3099 Time at which these statistics were last reset
3100 </para></entry>
3101 </row>
3102 </tbody>
3103 </tgroup>
3104 </table>
3106 </sect2>
3108 <sect2 id="monitoring-pg-stat-database-view">
3109 <title><structname>pg_stat_database</structname></title>
3111 <indexterm>
3112 <primary>pg_stat_database</primary>
3113 </indexterm>
3115 <para>
3116 The <structname>pg_stat_database</structname> view will contain one row
3117 for each database in the cluster, plus one for shared objects, showing
3118 database-wide statistics.
3119 </para>
3121 <table id="pg-stat-database-view" xreflabel="pg_stat_database">
3122 <title><structname>pg_stat_database</structname> View</title>
3123 <tgroup cols="1">
3124 <thead>
3125 <row>
3126 <entry role="catalog_table_entry"><para role="column_definition">
3127 Column Type
3128 </para>
3129 <para>
3130 Description
3131 </para></entry>
3132 </row>
3133 </thead>
3135 <tbody>
3136 <row>
3137 <entry role="catalog_table_entry"><para role="column_definition">
3138 <structfield>datid</structfield> <type>oid</type>
3139 </para>
3140 <para>
3141 OID of this database, or 0 for objects belonging to a shared
3142 relation
3143 </para></entry>
3144 </row>
3146 <row>
3147 <entry role="catalog_table_entry"><para role="column_definition">
3148 <structfield>datname</structfield> <type>name</type>
3149 </para>
3150 <para>
3151 Name of this database, or <literal>NULL</literal> for shared
3152 objects.
3153 </para></entry>
3154 </row>
3156 <row>
3157 <entry role="catalog_table_entry"><para role="column_definition">
3158 <structfield>numbackends</structfield> <type>integer</type>
3159 </para>
3160 <para>
3161 Number of backends currently connected to this database, or
3162 <literal>NULL</literal> for shared objects. This is the only column
3163 in this view that returns a value reflecting current state; all other
3164 columns return the accumulated values since the last reset.
3165 </para></entry>
3166 </row>
3168 <row>
3169 <entry role="catalog_table_entry"><para role="column_definition">
3170 <structfield>xact_commit</structfield> <type>bigint</type>
3171 </para>
3172 <para>
3173 Number of transactions in this database that have been
3174 committed
3175 </para></entry>
3176 </row>
3178 <row>
3179 <entry role="catalog_table_entry"><para role="column_definition">
3180 <structfield>xact_rollback</structfield> <type>bigint</type>
3181 </para>
3182 <para>
3183 Number of transactions in this database that have been
3184 rolled back
3185 </para></entry>
3186 </row>
3188 <row>
3189 <entry role="catalog_table_entry"><para role="column_definition">
3190 <structfield>blks_read</structfield> <type>bigint</type>
3191 </para>
3192 <para>
3193 Number of disk blocks read in this database
3194 </para></entry>
3195 </row>
3197 <row>
3198 <entry role="catalog_table_entry"><para role="column_definition">
3199 <structfield>blks_hit</structfield> <type>bigint</type>
3200 </para>
3201 <para>
3202 Number of times disk blocks were found already in the buffer
3203 cache, so that a read was not necessary (this only includes hits in the
3204 PostgreSQL buffer cache, not the operating system's file system cache)
3205 </para></entry>
3206 </row>
3208 <row>
3209 <entry role="catalog_table_entry"><para role="column_definition">
3210 <structfield>tup_returned</structfield> <type>bigint</type>
3211 </para>
3212 <para>
3213 Number of live rows fetched by sequential scans and index entries returned by index scans in this database
3214 </para></entry>
3215 </row>
3217 <row>
3218 <entry role="catalog_table_entry"><para role="column_definition">
3219 <structfield>tup_fetched</structfield> <type>bigint</type>
3220 </para>
3221 <para>
3222 Number of live rows fetched by index scans in this database
3223 </para></entry>
3224 </row>
3226 <row>
3227 <entry role="catalog_table_entry"><para role="column_definition">
3228 <structfield>tup_inserted</structfield> <type>bigint</type>
3229 </para>
3230 <para>
3231 Number of rows inserted by queries in this database
3232 </para></entry>
3233 </row>
3235 <row>
3236 <entry role="catalog_table_entry"><para role="column_definition">
3237 <structfield>tup_updated</structfield> <type>bigint</type>
3238 </para>
3239 <para>
3240 Number of rows updated by queries in this database
3241 </para></entry>
3242 </row>
3244 <row>
3245 <entry role="catalog_table_entry"><para role="column_definition">
3246 <structfield>tup_deleted</structfield> <type>bigint</type>
3247 </para>
3248 <para>
3249 Number of rows deleted by queries in this database
3250 </para></entry>
3251 </row>
3253 <row>
3254 <entry role="catalog_table_entry"><para role="column_definition">
3255 <structfield>conflicts</structfield> <type>bigint</type>
3256 </para>
3257 <para>
3258 Number of queries canceled due to conflicts with recovery
3259 in this database. (Conflicts occur only on standby servers; see
3260 <link linkend="monitoring-pg-stat-database-conflicts-view">
3261 <structname>pg_stat_database_conflicts</structname></link> for details.)
3262 </para></entry>
3263 </row>
3265 <row>
3266 <entry role="catalog_table_entry"><para role="column_definition">
3267 <structfield>temp_files</structfield> <type>bigint</type>
3268 </para>
3269 <para>
3270 Number of temporary files created by queries in this database.
3271 All temporary files are counted, regardless of why the temporary file
3272 was created (e.g., sorting or hashing), and regardless of the
3273 <xref linkend="guc-log-temp-files"/> setting.
3274 </para></entry>
3275 </row>
3277 <row>
3278 <entry role="catalog_table_entry"><para role="column_definition">
3279 <structfield>temp_bytes</structfield> <type>bigint</type>
3280 </para>
3281 <para>
3282 Total amount of data written to temporary files by queries in
3283 this database. All temporary files are counted, regardless of why
3284 the temporary file was created, and
3285 regardless of the <xref linkend="guc-log-temp-files"/> setting.
3286 </para></entry>
3287 </row>
3289 <row>
3290 <entry role="catalog_table_entry"><para role="column_definition">
3291 <structfield>deadlocks</structfield> <type>bigint</type>
3292 </para>
3293 <para>
3294 Number of deadlocks detected in this database
3295 </para></entry>
3296 </row>
3298 <row>
3299 <entry role="catalog_table_entry"><para role="column_definition">
3300 <structfield>checksum_failures</structfield> <type>bigint</type>
3301 </para>
3302 <para>
3303 Number of data page checksum failures detected in this
3304 database (or on a shared object), or NULL if data checksums are not
3305 enabled.
3306 </para></entry>
3307 </row>
3309 <row>
3310 <entry role="catalog_table_entry"><para role="column_definition">
3311 <structfield>checksum_last_failure</structfield> <type>timestamp with time zone</type>
3312 </para>
3313 <para>
3314 Time at which the last data page checksum failure was detected in
3315 this database (or on a shared object), or NULL if data checksums are not
3316 enabled.
3317 </para></entry>
3318 </row>
3320 <row>
3321 <entry role="catalog_table_entry"><para role="column_definition">
3322 <structfield>blk_read_time</structfield> <type>double precision</type>
3323 </para>
3324 <para>
3325 Time spent reading data file blocks by backends in this database,
3326 in milliseconds (if <xref linkend="guc-track-io-timing"/> is enabled,
3327 otherwise zero)
3328 </para></entry>
3329 </row>
3331 <row>
3332 <entry role="catalog_table_entry"><para role="column_definition">
3333 <structfield>blk_write_time</structfield> <type>double precision</type>
3334 </para>
3335 <para>
3336 Time spent writing data file blocks by backends in this database,
3337 in milliseconds (if <xref linkend="guc-track-io-timing"/> is enabled,
3338 otherwise zero)
3339 </para></entry>
3340 </row>
3342 <row>
3343 <entry role="catalog_table_entry"><para role="column_definition">
3344 <structfield>session_time</structfield> <type>double precision</type>
3345 </para>
3346 <para>
3347 Time spent by database sessions in this database, in milliseconds
3348 (note that statistics are only updated when the state of a session
3349 changes, so if sessions have been idle for a long time, this idle time
3350 won't be included)
3351 </para></entry>
3352 </row>
3354 <row>
3355 <entry role="catalog_table_entry"><para role="column_definition">
3356 <structfield>active_time</structfield> <type>double precision</type>
3357 </para>
3358 <para>
3359 Time spent executing SQL statements in this database, in milliseconds
3360 (this corresponds to the states <literal>active</literal> and
3361 <literal>fastpath function call</literal> in
3362 <link linkend="monitoring-pg-stat-activity-view">
3363 <structname>pg_stat_activity</structname></link>)
3364 </para></entry>
3365 </row>
3367 <row>
3368 <entry role="catalog_table_entry"><para role="column_definition">
3369 <structfield>idle_in_transaction_time</structfield> <type>double precision</type>
3370 </para>
3371 <para>
3372 Time spent idling while in a transaction in this database, in milliseconds
3373 (this corresponds to the states <literal>idle in transaction</literal> and
3374 <literal>idle in transaction (aborted)</literal> in
3375 <link linkend="monitoring-pg-stat-activity-view">
3376 <structname>pg_stat_activity</structname></link>)
3377 </para></entry>
3378 </row>
3380 <row>
3381 <entry role="catalog_table_entry"><para role="column_definition">
3382 <structfield>sessions</structfield> <type>bigint</type>
3383 </para>
3384 <para>
3385 Total number of sessions established to this database
3386 </para></entry>
3387 </row>
3389 <row>
3390 <entry role="catalog_table_entry"><para role="column_definition">
3391 <structfield>sessions_abandoned</structfield> <type>bigint</type>
3392 </para>
3393 <para>
3394 Number of database sessions to this database that were terminated
3395 because connection to the client was lost
3396 </para></entry>
3397 </row>
3399 <row>
3400 <entry role="catalog_table_entry"><para role="column_definition">
3401 <structfield>sessions_fatal</structfield> <type>bigint</type>
3402 </para>
3403 <para>
3404 Number of database sessions to this database that were terminated
3405 by fatal errors
3406 </para></entry>
3407 </row>
3409 <row>
3410 <entry role="catalog_table_entry"><para role="column_definition">
3411 <structfield>sessions_killed</structfield> <type>bigint</type>
3412 </para>
3413 <para>
3414 Number of database sessions to this database that were terminated
3415 by operator intervention
3416 </para></entry>
3417 </row>
3419 <row>
3420 <entry role="catalog_table_entry"><para role="column_definition">
3421 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
3422 </para>
3423 <para>
3424 Time at which these statistics were last reset
3425 </para></entry>
3426 </row>
3427 </tbody>
3428 </tgroup>
3429 </table>
3431 </sect2>
3433 <sect2 id="monitoring-pg-stat-database-conflicts-view">
3434 <title><structname>pg_stat_database_conflicts</structname></title>
3436 <indexterm>
3437 <primary>pg_stat_database_conflicts</primary>
3438 </indexterm>
3440 <para>
3441 The <structname>pg_stat_database_conflicts</structname> view will contain
3442 one row per database, showing database-wide statistics about
3443 query cancels occurring due to conflicts with recovery on standby servers.
3444 This view will only contain information on standby servers, since
3445 conflicts do not occur on primary servers.
3446 </para>
3448 <table id="pg-stat-database-conflicts-view" xreflabel="pg_stat_database_conflicts">
3449 <title><structname>pg_stat_database_conflicts</structname> View</title>
3450 <tgroup cols="1">
3451 <thead>
3452 <row>
3453 <entry role="catalog_table_entry"><para role="column_definition">
3454 Column Type
3455 </para>
3456 <para>
3457 Description
3458 </para></entry>
3459 </row>
3460 </thead>
3462 <tbody>
3463 <row>
3464 <entry role="catalog_table_entry"><para role="column_definition">
3465 <structfield>datid</structfield> <type>oid</type>
3466 </para>
3467 <para>
3468 OID of a database
3469 </para></entry>
3470 </row>
3472 <row>
3473 <entry role="catalog_table_entry"><para role="column_definition">
3474 <structfield>datname</structfield> <type>name</type>
3475 </para>
3476 <para>
3477 Name of this database
3478 </para></entry>
3479 </row>
3481 <row>
3482 <entry role="catalog_table_entry"><para role="column_definition">
3483 <structfield>confl_tablespace</structfield> <type>bigint</type>
3484 </para>
3485 <para>
3486 Number of queries in this database that have been canceled due to
3487 dropped tablespaces
3488 </para></entry>
3489 </row>
3491 <row>
3492 <entry role="catalog_table_entry"><para role="column_definition">
3493 <structfield>confl_lock</structfield> <type>bigint</type>
3494 </para>
3495 <para>
3496 Number of queries in this database that have been canceled due to
3497 lock timeouts
3498 </para></entry>
3499 </row>
3501 <row>
3502 <entry role="catalog_table_entry"><para role="column_definition">
3503 <structfield>confl_snapshot</structfield> <type>bigint</type>
3504 </para>
3505 <para>
3506 Number of queries in this database that have been canceled due to
3507 old snapshots
3508 </para></entry>
3509 </row>
3511 <row>
3512 <entry role="catalog_table_entry"><para role="column_definition">
3513 <structfield>confl_bufferpin</structfield> <type>bigint</type>
3514 </para>
3515 <para>
3516 Number of queries in this database that have been canceled due to
3517 pinned buffers
3518 </para></entry>
3519 </row>
3521 <row>
3522 <entry role="catalog_table_entry"><para role="column_definition">
3523 <structfield>confl_deadlock</structfield> <type>bigint</type>
3524 </para>
3525 <para>
3526 Number of queries in this database that have been canceled due to
3527 deadlocks
3528 </para></entry>
3529 </row>
3531 <row>
3532 <entry role="catalog_table_entry"><para role="column_definition">
3533 <structfield>confl_active_logicalslot</structfield> <type>bigint</type>
3534 </para>
3535 <para>
3536 Number of uses of logical slots in this database that have been
3537 canceled due to old snapshots or too low a <xref linkend="guc-wal-level"/>
3538 on the primary
3539 </para></entry>
3540 </row>
3541 </tbody>
3542 </tgroup>
3543 </table>
3545 </sect2>
3547 <sect2 id="monitoring-pg-stat-all-tables-view">
3548 <title><structname>pg_stat_all_tables</structname></title>
3550 <indexterm>
3551 <primary>pg_stat_all_tables</primary>
3552 </indexterm>
3554 <para>
3555 The <structname>pg_stat_all_tables</structname> view will contain
3556 one row for each table in the current database (including TOAST
3557 tables), showing statistics about accesses to that specific table. The
3558 <structname>pg_stat_user_tables</structname> and
3559 <structname>pg_stat_sys_tables</structname> views
3560 contain the same information,
3561 but filtered to only show user and system tables respectively.
3562 </para>
3564 <table id="pg-stat-all-tables-view" xreflabel="pg_stat_all_tables">
3565 <title><structname>pg_stat_all_tables</structname> View</title>
3566 <tgroup cols="1">
3567 <thead>
3568 <row>
3569 <entry role="catalog_table_entry"><para role="column_definition">
3570 Column Type
3571 </para>
3572 <para>
3573 Description
3574 </para></entry>
3575 </row>
3576 </thead>
3578 <tbody>
3579 <row>
3580 <entry role="catalog_table_entry"><para role="column_definition">
3581 <structfield>relid</structfield> <type>oid</type>
3582 </para>
3583 <para>
3584 OID of a table
3585 </para></entry>
3586 </row>
3588 <row>
3589 <entry role="catalog_table_entry"><para role="column_definition">
3590 <structfield>schemaname</structfield> <type>name</type>
3591 </para>
3592 <para>
3593 Name of the schema that this table is in
3594 </para></entry>
3595 </row>
3597 <row>
3598 <entry role="catalog_table_entry"><para role="column_definition">
3599 <structfield>relname</structfield> <type>name</type>
3600 </para>
3601 <para>
3602 Name of this table
3603 </para></entry>
3604 </row>
3606 <row>
3607 <entry role="catalog_table_entry"><para role="column_definition">
3608 <structfield>seq_scan</structfield> <type>bigint</type>
3609 </para>
3610 <para>
3611 Number of sequential scans initiated on this table
3612 </para></entry>
3613 </row>
3615 <row>
3616 <entry role="catalog_table_entry"><para role="column_definition">
3617 <structfield>last_seq_scan</structfield> <type>timestamp with time zone</type>
3618 </para>
3619 <para>
3620 The time of the last sequential scan on this table, based on the
3621 most recent transaction stop time
3622 </para></entry>
3623 </row>
3625 <row>
3626 <entry role="catalog_table_entry"><para role="column_definition">
3627 <structfield>seq_tup_read</structfield> <type>bigint</type>
3628 </para>
3629 <para>
3630 Number of live rows fetched by sequential scans
3631 </para></entry>
3632 </row>
3634 <row>
3635 <entry role="catalog_table_entry"><para role="column_definition">
3636 <structfield>idx_scan</structfield> <type>bigint</type>
3637 </para>
3638 <para>
3639 Number of index scans initiated on this table
3640 </para></entry>
3641 </row>
3643 <row>
3644 <entry role="catalog_table_entry"><para role="column_definition">
3645 <structfield>last_idx_scan</structfield> <type>timestamp with time zone</type>
3646 </para>
3647 <para>
3648 The time of the last index scan on this table, based on the
3649 most recent transaction stop time
3650 </para></entry>
3651 </row>
3653 <row>
3654 <entry role="catalog_table_entry"><para role="column_definition">
3655 <structfield>idx_tup_fetch</structfield> <type>bigint</type>
3656 </para>
3657 <para>
3658 Number of live rows fetched by index scans
3659 </para></entry>
3660 </row>
3662 <row>
3663 <entry role="catalog_table_entry"><para role="column_definition">
3664 <structfield>n_tup_ins</structfield> <type>bigint</type>
3665 </para>
3666 <para>
3667 Total number of rows inserted
3668 </para></entry>
3669 </row>
3671 <row>
3672 <entry role="catalog_table_entry"><para role="column_definition">
3673 <structfield>n_tup_upd</structfield> <type>bigint</type>
3674 </para>
3675 <para>
3676 Total number of rows updated. (This includes row updates
3677 counted in <structfield>n_tup_hot_upd</structfield> and
3678 <structfield>n_tup_newpage_upd</structfield>, and remaining
3679 non-<acronym>HOT</acronym> updates.)
3680 </para></entry>
3681 </row>
3683 <row>
3684 <entry role="catalog_table_entry"><para role="column_definition">
3685 <structfield>n_tup_del</structfield> <type>bigint</type>
3686 </para>
3687 <para>
3688 Total number of rows deleted
3689 </para></entry>
3690 </row>
3692 <row>
3693 <entry role="catalog_table_entry"><para role="column_definition">
3694 <structfield>n_tup_hot_upd</structfield> <type>bigint</type>
3695 </para>
3696 <para>
3697 Number of rows <link linkend="storage-hot">HOT updated</link>.
3698 These are updates where no successor versions are required in
3699 indexes.
3700 </para></entry>
3701 </row>
3703 <row>
3704 <entry role="catalog_table_entry"><para role="column_definition">
3705 <structfield>n_tup_newpage_upd</structfield> <type>bigint</type>
3706 </para>
3707 <para>
3708 Number of rows updated where the successor version goes onto a
3709 <emphasis>new</emphasis> heap page, leaving behind an original
3710 version with a
3711 <link linkend="storage-tuple-layout"><structfield>t_ctid</structfield>
3712 field</link> that points to a different heap page. These are
3713 always non-<acronym>HOT</acronym> updates.
3714 </para></entry>
3715 </row>
3717 <row>
3718 <entry role="catalog_table_entry"><para role="column_definition">
3719 <structfield>n_live_tup</structfield> <type>bigint</type>
3720 </para>
3721 <para>
3722 Estimated number of live rows
3723 </para></entry>
3724 </row>
3726 <row>
3727 <entry role="catalog_table_entry"><para role="column_definition">
3728 <structfield>n_dead_tup</structfield> <type>bigint</type>
3729 </para>
3730 <para>
3731 Estimated number of dead rows
3732 </para></entry>
3733 </row>
3735 <row>
3736 <entry role="catalog_table_entry"><para role="column_definition">
3737 <structfield>n_mod_since_analyze</structfield> <type>bigint</type>
3738 </para>
3739 <para>
3740 Estimated number of rows modified since this table was last analyzed
3741 </para></entry>
3742 </row>
3744 <row>
3745 <entry role="catalog_table_entry"><para role="column_definition">
3746 <structfield>n_ins_since_vacuum</structfield> <type>bigint</type>
3747 </para>
3748 <para>
3749 Estimated number of rows inserted since this table was last vacuumed
3750 </para></entry>
3751 </row>
3753 <row>
3754 <entry role="catalog_table_entry"><para role="column_definition">
3755 <structfield>last_vacuum</structfield> <type>timestamp with time zone</type>
3756 </para>
3757 <para>
3758 Last time at which this table was manually vacuumed
3759 (not counting <command>VACUUM FULL</command>)
3760 </para></entry>
3761 </row>
3763 <row>
3764 <entry role="catalog_table_entry"><para role="column_definition">
3765 <structfield>last_autovacuum</structfield> <type>timestamp with time zone</type>
3766 </para>
3767 <para>
3768 Last time at which this table was vacuumed by the autovacuum
3769 daemon
3770 </para></entry>
3771 </row>
3773 <row>
3774 <entry role="catalog_table_entry"><para role="column_definition">
3775 <structfield>last_analyze</structfield> <type>timestamp with time zone</type>
3776 </para>
3777 <para>
3778 Last time at which this table was manually analyzed
3779 </para></entry>
3780 </row>
3782 <row>
3783 <entry role="catalog_table_entry"><para role="column_definition">
3784 <structfield>last_autoanalyze</structfield> <type>timestamp with time zone</type>
3785 </para>
3786 <para>
3787 Last time at which this table was analyzed by the autovacuum
3788 daemon
3789 </para></entry>
3790 </row>
3792 <row>
3793 <entry role="catalog_table_entry"><para role="column_definition">
3794 <structfield>vacuum_count</structfield> <type>bigint</type>
3795 </para>
3796 <para>
3797 Number of times this table has been manually vacuumed
3798 (not counting <command>VACUUM FULL</command>)
3799 </para></entry>
3800 </row>
3802 <row>
3803 <entry role="catalog_table_entry"><para role="column_definition">
3804 <structfield>autovacuum_count</structfield> <type>bigint</type>
3805 </para>
3806 <para>
3807 Number of times this table has been vacuumed by the autovacuum
3808 daemon
3809 </para></entry>
3810 </row>
3812 <row>
3813 <entry role="catalog_table_entry"><para role="column_definition">
3814 <structfield>analyze_count</structfield> <type>bigint</type>
3815 </para>
3816 <para>
3817 Number of times this table has been manually analyzed
3818 </para></entry>
3819 </row>
3821 <row>
3822 <entry role="catalog_table_entry"><para role="column_definition">
3823 <structfield>autoanalyze_count</structfield> <type>bigint</type>
3824 </para>
3825 <para>
3826 Number of times this table has been analyzed by the autovacuum
3827 daemon
3828 </para></entry>
3829 </row>
3830 </tbody>
3831 </tgroup>
3832 </table>
3834 </sect2>
3836 <sect2 id="monitoring-pg-stat-all-indexes-view">
3837 <title><structname>pg_stat_all_indexes</structname></title>
3839 <indexterm>
3840 <primary>pg_stat_all_indexes</primary>
3841 </indexterm>
3843 <para>
3844 The <structname>pg_stat_all_indexes</structname> view will contain
3845 one row for each index in the current database,
3846 showing statistics about accesses to that specific index. The
3847 <structname>pg_stat_user_indexes</structname> and
3848 <structname>pg_stat_sys_indexes</structname> views
3849 contain the same information,
3850 but filtered to only show user and system indexes respectively.
3851 </para>
3853 <table id="pg-stat-all-indexes-view" xreflabel="pg_stat_all_indexes">
3854 <title><structname>pg_stat_all_indexes</structname> View</title>
3855 <tgroup cols="1">
3856 <thead>
3857 <row>
3858 <entry role="catalog_table_entry"><para role="column_definition">
3859 Column Type
3860 </para>
3861 <para>
3862 Description
3863 </para></entry>
3864 </row>
3865 </thead>
3867 <tbody>
3868 <row>
3869 <entry role="catalog_table_entry"><para role="column_definition">
3870 <structfield>relid</structfield> <type>oid</type>
3871 </para>
3872 <para>
3873 OID of the table for this index
3874 </para></entry>
3875 </row>
3877 <row>
3878 <entry role="catalog_table_entry"><para role="column_definition">
3879 <structfield>indexrelid</structfield> <type>oid</type>
3880 </para>
3881 <para>
3882 OID of this index
3883 </para></entry>
3884 </row>
3886 <row>
3887 <entry role="catalog_table_entry"><para role="column_definition">
3888 <structfield>schemaname</structfield> <type>name</type>
3889 </para>
3890 <para>
3891 Name of the schema this index is in
3892 </para></entry>
3893 </row>
3895 <row>
3896 <entry role="catalog_table_entry"><para role="column_definition">
3897 <structfield>relname</structfield> <type>name</type>
3898 </para>
3899 <para>
3900 Name of the table for this index
3901 </para></entry>
3902 </row>
3904 <row>
3905 <entry role="catalog_table_entry"><para role="column_definition">
3906 <structfield>indexrelname</structfield> <type>name</type>
3907 </para>
3908 <para>
3909 Name of this index
3910 </para></entry>
3911 </row>
3913 <row>
3914 <entry role="catalog_table_entry"><para role="column_definition">
3915 <structfield>idx_scan</structfield> <type>bigint</type>
3916 </para>
3917 <para>
3918 Number of index scans initiated on this index
3919 </para></entry>
3920 </row>
3922 <row>
3923 <entry role="catalog_table_entry"><para role="column_definition">
3924 <structfield>last_idx_scan</structfield> <type>timestamp with time zone</type>
3925 </para>
3926 <para>
3927 The time of the last scan on this index, based on the
3928 most recent transaction stop time
3929 </para></entry>
3930 </row>
3932 <row>
3933 <entry role="catalog_table_entry"><para role="column_definition">
3934 <structfield>idx_tup_read</structfield> <type>bigint</type>
3935 </para>
3936 <para>
3937 Number of index entries returned by scans on this index
3938 </para></entry>
3939 </row>
3941 <row>
3942 <entry role="catalog_table_entry"><para role="column_definition">
3943 <structfield>idx_tup_fetch</structfield> <type>bigint</type>
3944 </para>
3945 <para>
3946 Number of live table rows fetched by simple index scans using this
3947 index
3948 </para></entry>
3949 </row>
3950 </tbody>
3951 </tgroup>
3952 </table>
3954 <para>
3955 Indexes can be used by simple index scans, <quote>bitmap</quote> index scans,
3956 and the optimizer. In a bitmap scan
3957 the output of several indexes can be combined via AND or OR rules,
3958 so it is difficult to associate individual heap row fetches
3959 with specific indexes when a bitmap scan is used. Therefore, a bitmap
3960 scan increments the
3961 <structname>pg_stat_all_indexes</structname>.<structfield>idx_tup_read</structfield>
3962 count(s) for the index(es) it uses, and it increments the
3963 <structname>pg_stat_all_tables</structname>.<structfield>idx_tup_fetch</structfield>
3964 count for the table, but it does not affect
3965 <structname>pg_stat_all_indexes</structname>.<structfield>idx_tup_fetch</structfield>.
3966 The optimizer also accesses indexes to check for supplied constants
3967 whose values are outside the recorded range of the optimizer statistics
3968 because the optimizer statistics might be stale.
3969 </para>
3971 <note>
3972 <para>
3973 The <structfield>idx_tup_read</structfield> and <structfield>idx_tup_fetch</structfield> counts
3974 can be different even without any use of bitmap scans,
3975 because <structfield>idx_tup_read</structfield> counts
3976 index entries retrieved from the index while <structfield>idx_tup_fetch</structfield>
3977 counts live rows fetched from the table. The latter will be less if any
3978 dead or not-yet-committed rows are fetched using the index, or if any
3979 heap fetches are avoided by means of an index-only scan.
3980 </para>
3981 </note>
3983 </sect2>
3985 <sect2 id="monitoring-pg-statio-all-tables-view">
3986 <title><structname>pg_statio_all_tables</structname></title>
3988 <indexterm>
3989 <primary>pg_statio_all_tables</primary>
3990 </indexterm>
3992 <para>
3993 The <structname>pg_statio_all_tables</structname> view will contain
3994 one row for each table in the current database (including TOAST
3995 tables), showing statistics about I/O on that specific table. The
3996 <structname>pg_statio_user_tables</structname> and
3997 <structname>pg_statio_sys_tables</structname> views
3998 contain the same information,
3999 but filtered to only show user and system tables respectively.
4000 </para>
4002 <table id="pg-statio-all-tables-view" xreflabel="pg_statio_all_tables">
4003 <title><structname>pg_statio_all_tables</structname> View</title>
4004 <tgroup cols="1">
4005 <thead>
4006 <row>
4007 <entry role="catalog_table_entry"><para role="column_definition">
4008 Column Type
4009 </para>
4010 <para>
4011 Description
4012 </para></entry>
4013 </row>
4014 </thead>
4016 <tbody>
4017 <row>
4018 <entry role="catalog_table_entry"><para role="column_definition">
4019 <structfield>relid</structfield> <type>oid</type>
4020 </para>
4021 <para>
4022 OID of a table
4023 </para></entry>
4024 </row>
4026 <row>
4027 <entry role="catalog_table_entry"><para role="column_definition">
4028 <structfield>schemaname</structfield> <type>name</type>
4029 </para>
4030 <para>
4031 Name of the schema that this table is in
4032 </para></entry>
4033 </row>
4035 <row>
4036 <entry role="catalog_table_entry"><para role="column_definition">
4037 <structfield>relname</structfield> <type>name</type>
4038 </para>
4039 <para>
4040 Name of this table
4041 </para></entry>
4042 </row>
4044 <row>
4045 <entry role="catalog_table_entry"><para role="column_definition">
4046 <structfield>heap_blks_read</structfield> <type>bigint</type>
4047 </para>
4048 <para>
4049 Number of disk blocks read from this table
4050 </para></entry>
4051 </row>
4053 <row>
4054 <entry role="catalog_table_entry"><para role="column_definition">
4055 <structfield>heap_blks_hit</structfield> <type>bigint</type>
4056 </para>
4057 <para>
4058 Number of buffer hits in this table
4059 </para></entry>
4060 </row>
4062 <row>
4063 <entry role="catalog_table_entry"><para role="column_definition">
4064 <structfield>idx_blks_read</structfield> <type>bigint</type>
4065 </para>
4066 <para>
4067 Number of disk blocks read from all indexes on this table
4068 </para></entry>
4069 </row>
4071 <row>
4072 <entry role="catalog_table_entry"><para role="column_definition">
4073 <structfield>idx_blks_hit</structfield> <type>bigint</type>
4074 </para>
4075 <para>
4076 Number of buffer hits in all indexes on this table
4077 </para></entry>
4078 </row>
4080 <row>
4081 <entry role="catalog_table_entry"><para role="column_definition">
4082 <structfield>toast_blks_read</structfield> <type>bigint</type>
4083 </para>
4084 <para>
4085 Number of disk blocks read from this table's TOAST table (if any)
4086 </para></entry>
4087 </row>
4089 <row>
4090 <entry role="catalog_table_entry"><para role="column_definition">
4091 <structfield>toast_blks_hit</structfield> <type>bigint</type>
4092 </para>
4093 <para>
4094 Number of buffer hits in this table's TOAST table (if any)
4095 </para></entry>
4096 </row>
4098 <row>
4099 <entry role="catalog_table_entry"><para role="column_definition">
4100 <structfield>tidx_blks_read</structfield> <type>bigint</type>
4101 </para>
4102 <para>
4103 Number of disk blocks read from this table's TOAST table indexes (if any)
4104 </para></entry>
4105 </row>
4107 <row>
4108 <entry role="catalog_table_entry"><para role="column_definition">
4109 <structfield>tidx_blks_hit</structfield> <type>bigint</type>
4110 </para>
4111 <para>
4112 Number of buffer hits in this table's TOAST table indexes (if any)
4113 </para></entry>
4114 </row>
4115 </tbody>
4116 </tgroup>
4117 </table>
4119 </sect2>
4121 <sect2 id="monitoring-pg-statio-all-indexes-view">
4122 <title><structname>pg_statio_all_indexes</structname></title>
4124 <indexterm>
4125 <primary>pg_statio_all_indexes</primary>
4126 </indexterm>
4128 <para>
4129 The <structname>pg_statio_all_indexes</structname> view will contain
4130 one row for each index in the current database,
4131 showing statistics about I/O on that specific index. The
4132 <structname>pg_statio_user_indexes</structname> and
4133 <structname>pg_statio_sys_indexes</structname> views
4134 contain the same information,
4135 but filtered to only show user and system indexes respectively.
4136 </para>
4138 <table id="pg-statio-all-indexes-view" xreflabel="pg_statio_all_indexes">
4139 <title><structname>pg_statio_all_indexes</structname> View</title>
4140 <tgroup cols="1">
4141 <thead>
4142 <row>
4143 <entry role="catalog_table_entry"><para role="column_definition">
4144 Column Type
4145 </para>
4146 <para>
4147 Description
4148 </para></entry>
4149 </row>
4150 </thead>
4152 <tbody>
4153 <row>
4154 <entry role="catalog_table_entry"><para role="column_definition">
4155 <structfield>relid</structfield> <type>oid</type>
4156 </para>
4157 <para>
4158 OID of the table for this index
4159 </para></entry>
4160 </row>
4162 <row>
4163 <entry role="catalog_table_entry"><para role="column_definition">
4164 <structfield>indexrelid</structfield> <type>oid</type>
4165 </para>
4166 <para>
4167 OID of this index
4168 </para></entry>
4169 </row>
4171 <row>
4172 <entry role="catalog_table_entry"><para role="column_definition">
4173 <structfield>schemaname</structfield> <type>name</type>
4174 </para>
4175 <para>
4176 Name of the schema this index is in
4177 </para></entry>
4178 </row>
4180 <row>
4181 <entry role="catalog_table_entry"><para role="column_definition">
4182 <structfield>relname</structfield> <type>name</type>
4183 </para>
4184 <para>
4185 Name of the table for this index
4186 </para></entry>
4187 </row>
4189 <row>
4190 <entry role="catalog_table_entry"><para role="column_definition">
4191 <structfield>indexrelname</structfield> <type>name</type>
4192 </para>
4193 <para>
4194 Name of this index
4195 </para></entry>
4196 </row>
4198 <row>
4199 <entry role="catalog_table_entry"><para role="column_definition">
4200 <structfield>idx_blks_read</structfield> <type>bigint</type>
4201 </para>
4202 <para>
4203 Number of disk blocks read from this index
4204 </para></entry>
4205 </row>
4207 <row>
4208 <entry role="catalog_table_entry"><para role="column_definition">
4209 <structfield>idx_blks_hit</structfield> <type>bigint</type>
4210 </para>
4211 <para>
4212 Number of buffer hits in this index
4213 </para></entry>
4214 </row>
4215 </tbody>
4216 </tgroup>
4217 </table>
4219 </sect2>
4221 <sect2 id="monitoring-pg-statio-all-sequences-view">
4222 <title><structname>pg_statio_all_sequences</structname></title>
4224 <indexterm>
4225 <primary>pg_statio_all_sequences</primary>
4226 </indexterm>
4228 <para>
4229 The <structname>pg_statio_all_sequences</structname> view will contain
4230 one row for each sequence in the current database,
4231 showing statistics about I/O on that specific sequence.
4232 </para>
4234 <table id="pg-statio-all-sequences-view" xreflabel="pg_statio_all_sequences">
4235 <title><structname>pg_statio_all_sequences</structname> View</title>
4236 <tgroup cols="1">
4237 <thead>
4238 <row>
4239 <entry role="catalog_table_entry"><para role="column_definition">
4240 Column Type
4241 </para>
4242 <para>
4243 Description
4244 </para></entry>
4245 </row>
4246 </thead>
4248 <tbody>
4249 <row>
4250 <entry role="catalog_table_entry"><para role="column_definition">
4251 <structfield>relid</structfield> <type>oid</type>
4252 </para>
4253 <para>
4254 OID of a sequence
4255 </para></entry>
4256 </row>
4258 <row>
4259 <entry role="catalog_table_entry"><para role="column_definition">
4260 <structfield>schemaname</structfield> <type>name</type>
4261 </para>
4262 <para>
4263 Name of the schema this sequence is in
4264 </para></entry>
4265 </row>
4267 <row>
4268 <entry role="catalog_table_entry"><para role="column_definition">
4269 <structfield>relname</structfield> <type>name</type>
4270 </para>
4271 <para>
4272 Name of this sequence
4273 </para></entry>
4274 </row>
4276 <row>
4277 <entry role="catalog_table_entry"><para role="column_definition">
4278 <structfield>blks_read</structfield> <type>bigint</type>
4279 </para>
4280 <para>
4281 Number of disk blocks read from this sequence
4282 </para></entry>
4283 </row>
4285 <row>
4286 <entry role="catalog_table_entry"><para role="column_definition">
4287 <structfield>blks_hit</structfield> <type>bigint</type>
4288 </para>
4289 <para>
4290 Number of buffer hits in this sequence
4291 </para></entry>
4292 </row>
4293 </tbody>
4294 </tgroup>
4295 </table>
4297 </sect2>
4299 <sect2 id="monitoring-pg-stat-user-functions-view">
4300 <title><structname>pg_stat_user_functions</structname></title>
4302 <indexterm>
4303 <primary>pg_stat_user_functions</primary>
4304 </indexterm>
4306 <para>
4307 The <structname>pg_stat_user_functions</structname> view will contain
4308 one row for each tracked function, showing statistics about executions of
4309 that function. The <xref linkend="guc-track-functions"/> parameter
4310 controls exactly which functions are tracked.
4311 </para>
4313 <table id="pg-stat-user-functions-view" xreflabel="pg_stat_user_functions">
4314 <title><structname>pg_stat_user_functions</structname> View</title>
4315 <tgroup cols="1">
4316 <thead>
4317 <row>
4318 <entry role="catalog_table_entry"><para role="column_definition">
4319 Column Type
4320 </para>
4321 <para>
4322 Description
4323 </para></entry>
4324 </row>
4325 </thead>
4327 <tbody>
4328 <row>
4329 <entry role="catalog_table_entry"><para role="column_definition">
4330 <structfield>funcid</structfield> <type>oid</type>
4331 </para>
4332 <para>
4333 OID of a function
4334 </para></entry>
4335 </row>
4337 <row>
4338 <entry role="catalog_table_entry"><para role="column_definition">
4339 <structfield>schemaname</structfield> <type>name</type>
4340 </para>
4341 <para>
4342 Name of the schema this function is in
4343 </para></entry>
4344 </row>
4346 <row>
4347 <entry role="catalog_table_entry"><para role="column_definition">
4348 <structfield>funcname</structfield> <type>name</type>
4349 </para>
4350 <para>
4351 Name of this function
4352 </para></entry>
4353 </row>
4355 <row>
4356 <entry role="catalog_table_entry"><para role="column_definition">
4357 <structfield>calls</structfield> <type>bigint</type>
4358 </para>
4359 <para>
4360 Number of times this function has been called
4361 </para></entry>
4362 </row>
4364 <row>
4365 <entry role="catalog_table_entry"><para role="column_definition">
4366 <structfield>total_time</structfield> <type>double precision</type>
4367 </para>
4368 <para>
4369 Total time spent in this function and all other functions
4370 called by it, in milliseconds
4371 </para></entry>
4372 </row>
4374 <row>
4375 <entry role="catalog_table_entry"><para role="column_definition">
4376 <structfield>self_time</structfield> <type>double precision</type>
4377 </para>
4378 <para>
4379 Total time spent in this function itself, not including
4380 other functions called by it, in milliseconds
4381 </para></entry>
4382 </row>
4383 </tbody>
4384 </tgroup>
4385 </table>
4387 </sect2>
4389 <sect2 id="monitoring-pg-stat-slru-view">
4390 <title><structname>pg_stat_slru</structname></title>
4392 <indexterm>
4393 <primary>SLRU</primary>
4394 </indexterm>
4396 <indexterm>
4397 <primary>pg_stat_slru</primary>
4398 </indexterm>
4400 <para>
4401 <productname>PostgreSQL</productname> accesses certain on-disk information
4402 via <firstterm>SLRU</firstterm> (simple least-recently-used) caches.
4403 The <structname>pg_stat_slru</structname> view will contain
4404 one row for each tracked SLRU cache, showing statistics about access
4405 to cached pages.
4406 </para>
4408 <table id="pg-stat-slru-view" xreflabel="pg_stat_slru">
4409 <title><structname>pg_stat_slru</structname> View</title>
4410 <tgroup cols="1">
4411 <thead>
4412 <row>
4413 <entry role="catalog_table_entry"><para role="column_definition">
4414 Column Type
4415 </para>
4416 <para>
4417 Description
4418 </para></entry>
4419 </row>
4420 </thead>
4422 <tbody>
4423 <row>
4424 <entry role="catalog_table_entry"><para role="column_definition">
4425 <structfield>name</structfield> <type>text</type>
4426 </para>
4427 <para>
4428 Name of the SLRU
4429 </para></entry>
4430 </row>
4432 <row>
4433 <entry role="catalog_table_entry"><para role="column_definition">
4434 <structfield>blks_zeroed</structfield> <type>bigint</type>
4435 </para>
4436 <para>
4437 Number of blocks zeroed during initializations
4438 </para></entry>
4439 </row>
4441 <row>
4442 <entry role="catalog_table_entry"><para role="column_definition">
4443 <structfield>blks_hit</structfield> <type>bigint</type>
4444 </para>
4445 <para>
4446 Number of times disk blocks were found already in the SLRU,
4447 so that a read was not necessary (this only includes hits in the
4448 SLRU, not the operating system's file system cache)
4449 </para></entry>
4450 </row>
4452 <row>
4453 <entry role="catalog_table_entry"><para role="column_definition">
4454 <structfield>blks_read</structfield> <type>bigint</type>
4455 </para>
4456 <para>
4457 Number of disk blocks read for this SLRU
4458 </para></entry>
4459 </row>
4461 <row>
4462 <entry role="catalog_table_entry"><para role="column_definition">
4463 <structfield>blks_written</structfield> <type>bigint</type>
4464 </para>
4465 <para>
4466 Number of disk blocks written for this SLRU
4467 </para></entry>
4468 </row>
4470 <row>
4471 <entry role="catalog_table_entry"><para role="column_definition">
4472 <structfield>blks_exists</structfield> <type>bigint</type>
4473 </para>
4474 <para>
4475 Number of blocks checked for existence for this SLRU
4476 </para></entry>
4477 </row>
4479 <row>
4480 <entry role="catalog_table_entry"><para role="column_definition">
4481 <structfield>flushes</structfield> <type>bigint</type>
4482 </para>
4483 <para>
4484 Number of flushes of dirty data for this SLRU
4485 </para></entry>
4486 </row>
4488 <row>
4489 <entry role="catalog_table_entry"><para role="column_definition">
4490 <structfield>truncates</structfield> <type>bigint</type>
4491 </para>
4492 <para>
4493 Number of truncates for this SLRU
4494 </para></entry>
4495 </row>
4497 <row>
4498 <entry role="catalog_table_entry"><para role="column_definition">
4499 <structfield>stats_reset</structfield> <type>timestamp with time zone</type>
4500 </para>
4501 <para>
4502 Time at which these statistics were last reset
4503 </para></entry>
4504 </row>
4505 </tbody>
4506 </tgroup>
4507 </table>
4509 </sect2>
4511 <sect2 id="monitoring-stats-functions">
4512 <title>Statistics Functions</title>
4514 <para>
4515 Other ways of looking at the statistics can be set up by writing
4516 queries that use the same underlying statistics access functions used by
4517 the standard views shown above. For details such as the functions' names,
4518 consult the definitions of the standard views. (For example, in
4519 <application>psql</application> you could issue <literal>\d+ pg_stat_activity</literal>.)
4520 The access functions for per-database statistics take a database OID as an
4521 argument to identify which database to report on.
4522 The per-table and per-index functions take a table or index OID.
4523 The functions for per-function statistics take a function OID.
4524 Note that only tables, indexes, and functions in the current database
4525 can be seen with these functions.
4526 </para>
4528 <para>
4529 Additional functions related to the cumulative statistics system are listed
4530 in <xref linkend="monitoring-stats-funcs-table"/>.
4531 </para>
4533 <table id="monitoring-stats-funcs-table">
4534 <title>Additional Statistics Functions</title>
4535 <tgroup cols="1">
4536 <thead>
4537 <row>
4538 <entry role="func_table_entry"><para role="func_signature">
4539 Function
4540 </para>
4541 <para>
4542 Description
4543 </para></entry>
4544 </row>
4545 </thead>
4547 <tbody>
4548 <row>
4549 <!-- See also the entry for this in func.sgml -->
4550 <entry role="func_table_entry"><para role="func_signature">
4551 <function>pg_backend_pid</function> ()
4552 <returnvalue>integer</returnvalue>
4553 </para>
4554 <para>
4555 Returns the process ID of the server process attached to the current
4556 session.
4557 </para></entry>
4558 </row>
4560 <row>
4561 <entry role="func_table_entry"><para role="func_signature">
4562 <indexterm>
4563 <primary>pg_stat_get_activity</primary>
4564 </indexterm>
4565 <function>pg_stat_get_activity</function> ( <type>integer</type> )
4566 <returnvalue>setof record</returnvalue>
4567 </para>
4568 <para>
4569 Returns a record of information about the backend with the specified
4570 process ID, or one record for each active backend in the system
4571 if <literal>NULL</literal> is specified. The fields returned are a
4572 subset of those in the <structname>pg_stat_activity</structname> view.
4573 </para></entry>
4574 </row>
4576 <row>
4577 <entry role="func_table_entry"><para role="func_signature">
4578 <indexterm>
4579 <primary>pg_stat_get_snapshot_timestamp</primary>
4580 </indexterm>
4581 <function>pg_stat_get_snapshot_timestamp</function> ()
4582 <returnvalue>timestamp with time zone</returnvalue>
4583 </para>
4584 <para>
4585 Returns the timestamp of the current statistics snapshot, or NULL if
4586 no statistics snapshot has been taken. A snapshot is taken the first
4587 time cumulative statistics are accessed in a transaction if
4588 <varname>stats_fetch_consistency</varname> is set to
4589 <literal>snapshot</literal>
4590 </para></entry>
4591 </row>
4593 <row>
4594 <entry role="func_table_entry"><para role="func_signature">
4595 <indexterm>
4596 <primary>pg_stat_get_xact_blocks_fetched</primary>
4597 </indexterm>
4598 <function>pg_stat_get_xact_blocks_fetched</function> ( <type>oid</type> )
4599 <returnvalue>bigint</returnvalue>
4600 </para>
4601 <para>
4602 Returns the number of block read requests for table or index, in the
4603 current transaction. This number minus
4604 <function>pg_stat_get_xact_blocks_hit</function> gives the number of
4605 kernel <function>read()</function> calls; the number of actual
4606 physical reads is usually lower due to kernel-level buffering.
4607 </para></entry>
4608 </row>
4610 <row>
4611 <entry role="func_table_entry"><para role="func_signature">
4612 <indexterm>
4613 <primary>pg_stat_get_xact_blocks_hit</primary>
4614 </indexterm>
4615 <function>pg_stat_get_xact_blocks_hit</function> ( <type>oid</type> )
4616 <returnvalue>bigint</returnvalue>
4617 </para>
4618 <para>
4619 Returns the number of block read requests for table or index, in the
4620 current transaction, found in cache (not triggering kernel
4621 <function>read()</function> calls).
4622 </para></entry>
4623 </row>
4625 <row>
4626 <entry role="func_table_entry"><para role="func_signature">
4627 <indexterm>
4628 <primary>pg_stat_clear_snapshot</primary>
4629 </indexterm>
4630 <function>pg_stat_clear_snapshot</function> ()
4631 <returnvalue>void</returnvalue>
4632 </para>
4633 <para>
4634 Discards the current statistics snapshot or cached information.
4635 </para></entry>
4636 </row>
4638 <row>
4639 <entry role="func_table_entry"><para role="func_signature">
4640 <indexterm>
4641 <primary>pg_stat_reset</primary>
4642 </indexterm>
4643 <function>pg_stat_reset</function> ()
4644 <returnvalue>void</returnvalue>
4645 </para>
4646 <para>
4647 Resets all statistics counters for the current database to zero.
4648 </para>
4649 <para>
4650 This function is restricted to superusers by default, but other users
4651 can be granted EXECUTE to run the function.
4652 </para></entry>
4653 </row>
4655 <row>
4656 <entry role="func_table_entry"><para role="func_signature">
4657 <indexterm>
4658 <primary>pg_stat_reset_shared</primary>
4659 </indexterm>
4660 <function>pg_stat_reset_shared</function> ( <type>text</type> )
4661 <returnvalue>void</returnvalue>
4662 </para>
4663 <para>
4664 Resets some cluster-wide statistics counters to zero, depending on the
4665 argument. The argument can be <literal>bgwriter</literal> to reset
4666 all the counters shown in
4667 the <structname>pg_stat_bgwriter</structname>
4668 view, <literal>archiver</literal> to reset all the counters shown in
4669 the <structname>pg_stat_archiver</structname> view,
4670 <literal>io</literal> to reset all the counters shown in the
4671 <structname>pg_stat_io</structname> view,
4672 <literal>wal</literal> to reset all the counters shown in the
4673 <structname>pg_stat_wal</structname> view or
4674 <literal>recovery_prefetch</literal> to reset all the counters shown
4675 in the <structname>pg_stat_recovery_prefetch</structname> view.
4676 </para>
4677 <para>
4678 This function is restricted to superusers by default, but other users
4679 can be granted EXECUTE to run the function.
4680 </para></entry>
4681 </row>
4683 <row>
4684 <entry role="func_table_entry"><para role="func_signature">
4685 <indexterm>
4686 <primary>pg_stat_reset_single_table_counters</primary>
4687 </indexterm>
4688 <function>pg_stat_reset_single_table_counters</function> ( <type>oid</type> )
4689 <returnvalue>void</returnvalue>
4690 </para>
4691 <para>
4692 Resets statistics for a single table or index in the current database
4693 or shared across all databases in the cluster to zero.
4694 </para>
4695 <para>
4696 This function is restricted to superusers by default, but other users
4697 can be granted EXECUTE to run the function.
4698 </para></entry>
4699 </row>
4701 <row>
4702 <entry role="func_table_entry"><para role="func_signature">
4703 <indexterm>
4704 <primary>pg_stat_reset_single_function_counters</primary>
4705 </indexterm>
4706 <function>pg_stat_reset_single_function_counters</function> ( <type>oid</type> )
4707 <returnvalue>void</returnvalue>
4708 </para>
4709 <para>
4710 Resets statistics for a single function in the current database to
4711 zero.
4712 </para>
4713 <para>
4714 This function is restricted to superusers by default, but other users
4715 can be granted EXECUTE to run the function.
4716 </para></entry>
4717 </row>
4719 <row>
4720 <entry role="func_table_entry"><para role="func_signature">
4721 <indexterm>
4722 <primary>pg_stat_reset_slru</primary>
4723 </indexterm>
4724 <function>pg_stat_reset_slru</function> ( <type>text</type> )
4725 <returnvalue>void</returnvalue>
4726 </para>
4727 <para>
4728 Resets statistics to zero for a single SLRU cache, or for all SLRUs in
4729 the cluster. If the argument is NULL, all counters shown in
4730 the <structname>pg_stat_slru</structname> view for all SLRU caches are
4731 reset. The argument can be one of
4732 <literal>CommitTs</literal>,
4733 <literal>MultiXactMember</literal>,
4734 <literal>MultiXactOffset</literal>,
4735 <literal>Notify</literal>,
4736 <literal>Serial</literal>,
4737 <literal>Subtrans</literal>, or
4738 <literal>Xact</literal>
4739 to reset the counters for only that entry.
4740 If the argument is <literal>other</literal> (or indeed, any
4741 unrecognized name), then the counters for all other SLRU caches, such
4742 as extension-defined caches, are reset.
4743 </para>
4744 <para>
4745 This function is restricted to superusers by default, but other users
4746 can be granted EXECUTE to run the function.
4747 </para></entry>
4748 </row>
4750 <row>
4751 <entry role="func_table_entry"><para role="func_signature">
4752 <indexterm>
4753 <primary>pg_stat_reset_replication_slot</primary>
4754 </indexterm>
4755 <function>pg_stat_reset_replication_slot</function> ( <type>text</type> )
4756 <returnvalue>void</returnvalue>
4757 </para>
4758 <para>
4759 Resets statistics of the replication slot defined by the argument. If
4760 the argument is <literal>NULL</literal>, resets statistics for all
4761 the replication slots.
4762 </para>
4763 <para>
4764 This function is restricted to superusers by default, but other users
4765 can be granted EXECUTE to run the function.
4766 </para></entry>
4767 </row>
4769 <row>
4770 <entry role="func_table_entry"><para role="func_signature">
4771 <indexterm>
4772 <primary>pg_stat_reset_subscription_stats</primary>
4773 </indexterm>
4774 <function>pg_stat_reset_subscription_stats</function> ( <type>oid</type> )
4775 <returnvalue>void</returnvalue>
4776 </para>
4777 <para>
4778 Resets statistics for a single subscription shown in the
4779 <structname>pg_stat_subscription_stats</structname> view to zero. If
4780 the argument is <literal>NULL</literal>, reset statistics for all
4781 subscriptions.
4782 </para>
4783 <para>
4784 This function is restricted to superusers by default, but other users
4785 can be granted EXECUTE to run the function.
4786 </para></entry>
4787 </row>
4788 </tbody>
4789 </tgroup>
4790 </table>
4792 <warning>
4793 <para>
4794 Using <function>pg_stat_reset()</function> also resets counters that
4795 autovacuum uses to determine when to trigger a vacuum or an analyze.
4796 Resetting these counters can cause autovacuum to not perform necessary
4797 work, which can cause problems such as table bloat or out-dated
4798 table statistics. A database-wide <command>ANALYZE</command> is
4799 recommended after the statistics have been reset.
4800 </para>
4801 </warning>
4803 <para>
4804 <function>pg_stat_get_activity</function>, the underlying function of
4805 the <structname>pg_stat_activity</structname> view, returns a set of records
4806 containing all the available information about each backend process.
4807 Sometimes it may be more convenient to obtain just a subset of this
4808 information. In such cases, another set of per-backend statistics
4809 access functions can be used; these are shown in <xref
4810 linkend="monitoring-stats-backend-funcs-table"/>.
4811 These access functions use the session's backend ID number, which is a
4812 small positive integer that is distinct from the backend ID of any
4813 concurrent session, although a session's ID can be recycled as soon as
4814 it exits. The backend ID is used, among other things, to identify the
4815 session's temporary schema if it has one.
4816 The function <function>pg_stat_get_backend_idset</function> provides a
4817 convenient way to list all the active backends' ID numbers for
4818 invoking these functions. For example, to show the <acronym>PID</acronym>s and
4819 current queries of all backends:
4821 <programlisting>
4822 SELECT pg_stat_get_backend_pid(backendid) AS pid,
4823 pg_stat_get_backend_activity(backendid) AS query
4824 FROM pg_stat_get_backend_idset() AS backendid;
4825 </programlisting>
4826 </para>
4828 <table id="monitoring-stats-backend-funcs-table">
4829 <title>Per-Backend Statistics Functions</title>
4830 <tgroup cols="1">
4831 <thead>
4832 <row>
4833 <entry role="func_table_entry"><para role="func_signature">
4834 Function
4835 </para>
4836 <para>
4837 Description
4838 </para></entry>
4839 </row>
4840 </thead>
4842 <tbody>
4843 <row>
4844 <entry role="func_table_entry"><para role="func_signature">
4845 <indexterm>
4846 <primary>pg_stat_get_backend_activity</primary>
4847 </indexterm>
4848 <function>pg_stat_get_backend_activity</function> ( <type>integer</type> )
4849 <returnvalue>text</returnvalue>
4850 </para>
4851 <para>
4852 Returns the text of this backend's most recent query.
4853 </para></entry>
4854 </row>
4856 <row>
4857 <entry role="func_table_entry"><para role="func_signature">
4858 <indexterm>
4859 <primary>pg_stat_get_backend_activity_start</primary>
4860 </indexterm>
4861 <function>pg_stat_get_backend_activity_start</function> ( <type>integer</type> )
4862 <returnvalue>timestamp with time zone</returnvalue>
4863 </para>
4864 <para>
4865 Returns the time when the backend's most recent query was started.
4866 </para></entry>
4867 </row>
4869 <row>
4870 <entry role="func_table_entry"><para role="func_signature">
4871 <indexterm>
4872 <primary>pg_stat_get_backend_client_addr</primary>
4873 </indexterm>
4874 <function>pg_stat_get_backend_client_addr</function> ( <type>integer</type> )
4875 <returnvalue>inet</returnvalue>
4876 </para>
4877 <para>
4878 Returns the IP address of the client connected to this backend.
4879 </para></entry>
4880 </row>
4882 <row>
4883 <entry role="func_table_entry"><para role="func_signature">
4884 <indexterm>
4885 <primary>pg_stat_get_backend_client_port</primary>
4886 </indexterm>
4887 <function>pg_stat_get_backend_client_port</function> ( <type>integer</type> )
4888 <returnvalue>integer</returnvalue>
4889 </para>
4890 <para>
4891 Returns the TCP port number that the client is using for communication.
4892 </para></entry>
4893 </row>
4895 <row>
4896 <entry role="func_table_entry"><para role="func_signature">
4897 <indexterm>
4898 <primary>pg_stat_get_backend_dbid</primary>
4899 </indexterm>
4900 <function>pg_stat_get_backend_dbid</function> ( <type>integer</type> )
4901 <returnvalue>oid</returnvalue>
4902 </para>
4903 <para>
4904 Returns the OID of the database this backend is connected to.
4905 </para></entry>
4906 </row>
4908 <row>
4909 <entry role="func_table_entry"><para role="func_signature">
4910 <indexterm>
4911 <primary>pg_stat_get_backend_idset</primary>
4912 </indexterm>
4913 <function>pg_stat_get_backend_idset</function> ()
4914 <returnvalue>setof integer</returnvalue>
4915 </para>
4916 <para>
4917 Returns the set of currently active backend ID numbers.
4918 </para></entry>
4919 </row>
4921 <row>
4922 <entry role="func_table_entry"><para role="func_signature">
4923 <indexterm>
4924 <primary>pg_stat_get_backend_pid</primary>
4925 </indexterm>
4926 <function>pg_stat_get_backend_pid</function> ( <type>integer</type> )
4927 <returnvalue>integer</returnvalue>
4928 </para>
4929 <para>
4930 Returns the process ID of this backend.
4931 </para></entry>
4932 </row>
4934 <row>
4935 <entry role="func_table_entry"><para role="func_signature">
4936 <indexterm>
4937 <primary>pg_stat_get_backend_start</primary>
4938 </indexterm>
4939 <function>pg_stat_get_backend_start</function> ( <type>integer</type> )
4940 <returnvalue>timestamp with time zone</returnvalue>
4941 </para>
4942 <para>
4943 Returns the time when this process was started.
4944 </para></entry>
4945 </row>
4947 <row>
4948 <entry role="func_table_entry"><para role="func_signature">
4949 <indexterm>
4950 <primary>pg_stat_get_backend_subxact</primary>
4951 </indexterm>
4952 <function>pg_stat_get_backend_subxact</function> ( <type>integer</type> )
4953 <returnvalue>record</returnvalue>
4954 </para>
4955 <para>
4956 Returns a record of information about the subtransactions of the
4957 backend with the specified ID.
4958 The fields returned are <parameter>subxact_count</parameter>, which
4959 is the number of subtransactions in the backend's subtransaction cache,
4960 and <parameter>subxact_overflow</parameter>, which indicates whether
4961 the backend's subtransaction cache is overflowed or not.
4962 </para></entry>
4963 </row>
4965 <row>
4966 <entry role="func_table_entry"><para role="func_signature">
4967 <indexterm>
4968 <primary>pg_stat_get_backend_userid</primary>
4969 </indexterm>
4970 <function>pg_stat_get_backend_userid</function> ( <type>integer</type> )
4971 <returnvalue>oid</returnvalue>
4972 </para>
4973 <para>
4974 Returns the OID of the user logged into this backend.
4975 </para></entry>
4976 </row>
4978 <row>
4979 <entry role="func_table_entry"><para role="func_signature">
4980 <indexterm>
4981 <primary>pg_stat_get_backend_wait_event</primary>
4982 </indexterm>
4983 <function>pg_stat_get_backend_wait_event</function> ( <type>integer</type> )
4984 <returnvalue>text</returnvalue>
4985 </para>
4986 <para>
4987 Returns the wait event name if this backend is currently waiting,
4988 otherwise NULL. See <xref linkend="wait-event-activity-table"/> through
4989 <xref linkend="wait-event-timeout-table"/>.
4990 </para></entry>
4991 </row>
4993 <row>
4994 <entry role="func_table_entry"><para role="func_signature">
4995 <indexterm>
4996 <primary>pg_stat_get_backend_wait_event_type</primary>
4997 </indexterm>
4998 <function>pg_stat_get_backend_wait_event_type</function> ( <type>integer</type> )
4999 <returnvalue>text</returnvalue>
5000 </para>
5001 <para>
5002 Returns the wait event type name if this backend is currently waiting,
5003 otherwise NULL. See <xref linkend="wait-event-table"/> for details.
5004 </para></entry>
5005 </row>
5007 <row>
5008 <entry role="func_table_entry"><para role="func_signature">
5009 <indexterm>
5010 <primary>pg_stat_get_backend_xact_start</primary>
5011 </indexterm>
5012 <function>pg_stat_get_backend_xact_start</function> ( <type>integer</type> )
5013 <returnvalue>timestamp with time zone</returnvalue>
5014 </para>
5015 <para>
5016 Returns the time when the backend's current transaction was started.
5017 </para></entry>
5018 </row>
5019 </tbody>
5020 </tgroup>
5021 </table>
5023 </sect2>
5024 </sect1>
5026 <sect1 id="monitoring-locks">
5027 <title>Viewing Locks</title>
5029 <indexterm zone="monitoring-locks">
5030 <primary>lock</primary>
5031 <secondary>monitoring</secondary>
5032 </indexterm>
5034 <para>
5035 Another useful tool for monitoring database activity is the
5036 <structname>pg_locks</structname> system table. It allows the
5037 database administrator to view information about the outstanding
5038 locks in the lock manager. For example, this capability can be used
5041 <itemizedlist>
5042 <listitem>
5043 <para>
5044 View all the locks currently outstanding, all the locks on
5045 relations in a particular database, all the locks on a
5046 particular relation, or all the locks held by a particular
5047 <productname>PostgreSQL</productname> session.
5048 </para>
5049 </listitem>
5051 <listitem>
5052 <para>
5053 Determine the relation in the current database with the most
5054 ungranted locks (which might be a source of contention among
5055 database clients).
5056 </para>
5057 </listitem>
5059 <listitem>
5060 <para>
5061 Determine the effect of lock contention on overall database
5062 performance, as well as the extent to which contention varies
5063 with overall database traffic.
5064 </para>
5065 </listitem>
5066 </itemizedlist>
5068 Details of the <structname>pg_locks</structname> view appear in
5069 <xref linkend="view-pg-locks"/>.
5070 For more information on locking and managing concurrency with
5071 <productname>PostgreSQL</productname>, refer to <xref linkend="mvcc"/>.
5072 </para>
5073 </sect1>
5075 <sect1 id="progress-reporting">
5076 <title>Progress Reporting</title>
5078 <para>
5079 <productname>PostgreSQL</productname> has the ability to report the progress of
5080 certain commands during command execution. Currently, the only commands
5081 which support progress reporting are <command>ANALYZE</command>,
5082 <command>CLUSTER</command>,
5083 <command>CREATE INDEX</command>, <command>VACUUM</command>,
5084 <command>COPY</command>,
5085 and <xref linkend="protocol-replication-base-backup"/> (i.e., replication
5086 command that <xref linkend="app-pgbasebackup"/> issues to take
5087 a base backup).
5088 This may be expanded in the future.
5089 </para>
5091 <sect2 id="analyze-progress-reporting">
5092 <title>ANALYZE Progress Reporting</title>
5094 <indexterm>
5095 <primary>pg_stat_progress_analyze</primary>
5096 </indexterm>
5098 <para>
5099 Whenever <command>ANALYZE</command> is running, the
5100 <structname>pg_stat_progress_analyze</structname> view will contain a
5101 row for each backend that is currently running that command. The tables
5102 below describe the information that will be reported and provide
5103 information about how to interpret it.
5104 </para>
5106 <table id="pg-stat-progress-analyze-view" xreflabel="pg_stat_progress_analyze">
5107 <title><structname>pg_stat_progress_analyze</structname> View</title>
5108 <tgroup cols="1">
5109 <thead>
5110 <row>
5111 <entry role="catalog_table_entry"><para role="column_definition">
5112 Column Type
5113 </para>
5114 <para>
5115 Description
5116 </para></entry>
5117 </row>
5118 </thead>
5120 <tbody>
5121 <row>
5122 <entry role="catalog_table_entry"><para role="column_definition">
5123 <structfield>pid</structfield> <type>integer</type>
5124 </para>
5125 <para>
5126 Process ID of backend.
5127 </para></entry>
5128 </row>
5130 <row>
5131 <entry role="catalog_table_entry"><para role="column_definition">
5132 <structfield>datid</structfield> <type>oid</type>
5133 </para>
5134 <para>
5135 OID of the database to which this backend is connected.
5136 </para></entry>
5137 </row>
5139 <row>
5140 <entry role="catalog_table_entry"><para role="column_definition">
5141 <structfield>datname</structfield> <type>name</type>
5142 </para>
5143 <para>
5144 Name of the database to which this backend is connected.
5145 </para></entry>
5146 </row>
5148 <row>
5149 <entry role="catalog_table_entry"><para role="column_definition">
5150 <structfield>relid</structfield> <type>oid</type>
5151 </para>
5152 <para>
5153 OID of the table being analyzed.
5154 </para></entry>
5155 </row>
5157 <row>
5158 <entry role="catalog_table_entry"><para role="column_definition">
5159 <structfield>phase</structfield> <type>text</type>
5160 </para>
5161 <para>
5162 Current processing phase. See <xref linkend="analyze-phases"/>.
5163 </para></entry>
5164 </row>
5166 <row>
5167 <entry role="catalog_table_entry"><para role="column_definition">
5168 <structfield>sample_blks_total</structfield> <type>bigint</type>
5169 </para>
5170 <para>
5171 Total number of heap blocks that will be sampled.
5172 </para></entry>
5173 </row>
5175 <row>
5176 <entry role="catalog_table_entry"><para role="column_definition">
5177 <structfield>sample_blks_scanned</structfield> <type>bigint</type>
5178 </para>
5179 <para>
5180 Number of heap blocks scanned.
5181 </para></entry>
5182 </row>
5184 <row>
5185 <entry role="catalog_table_entry"><para role="column_definition">
5186 <structfield>ext_stats_total</structfield> <type>bigint</type>
5187 </para>
5188 <para>
5189 Number of extended statistics.
5190 </para></entry>
5191 </row>
5193 <row>
5194 <entry role="catalog_table_entry"><para role="column_definition">
5195 <structfield>ext_stats_computed</structfield> <type>bigint</type>
5196 </para>
5197 <para>
5198 Number of extended statistics computed. This counter only advances
5199 when the phase is <literal>computing extended statistics</literal>.
5200 </para></entry>
5201 </row>
5203 <row>
5204 <entry role="catalog_table_entry"><para role="column_definition">
5205 <structfield>child_tables_total</structfield> <type>bigint</type>
5206 </para>
5207 <para>
5208 Number of child tables.
5209 </para></entry>
5210 </row>
5212 <row>
5213 <entry role="catalog_table_entry"><para role="column_definition">
5214 <structfield>child_tables_done</structfield> <type>bigint</type>
5215 </para>
5216 <para>
5217 Number of child tables scanned. This counter only advances when the
5218 phase is <literal>acquiring inherited sample rows</literal>.
5219 </para></entry>
5220 </row>
5222 <row>
5223 <entry role="catalog_table_entry"><para role="column_definition">
5224 <structfield>current_child_table_relid</structfield> <type>oid</type>
5225 </para>
5226 <para>
5227 OID of the child table currently being scanned. This field is
5228 only valid when the phase is
5229 <literal>acquiring inherited sample rows</literal>.
5230 </para></entry>
5231 </row>
5232 </tbody>
5233 </tgroup>
5234 </table>
5236 <table id="analyze-phases">
5237 <title>ANALYZE Phases</title>
5238 <tgroup cols="2">
5239 <colspec colname="col1" colwidth="1*"/>
5240 <colspec colname="col2" colwidth="2*"/>
5241 <thead>
5242 <row>
5243 <entry>Phase</entry>
5244 <entry>Description</entry>
5245 </row>
5246 </thead>
5247 <tbody>
5248 <row>
5249 <entry><literal>initializing</literal></entry>
5250 <entry>
5251 The command is preparing to begin scanning the heap. This phase is
5252 expected to be very brief.
5253 </entry>
5254 </row>
5255 <row>
5256 <entry><literal>acquiring sample rows</literal></entry>
5257 <entry>
5258 The command is currently scanning the table given by
5259 <structfield>relid</structfield> to obtain sample rows.
5260 </entry>
5261 </row>
5262 <row>
5263 <entry><literal>acquiring inherited sample rows</literal></entry>
5264 <entry>
5265 The command is currently scanning child tables to obtain sample rows.
5266 Columns <structfield>child_tables_total</structfield>,
5267 <structfield>child_tables_done</structfield>, and
5268 <structfield>current_child_table_relid</structfield> contain the
5269 progress information for this phase.
5270 </entry>
5271 </row>
5272 <row>
5273 <entry><literal>computing statistics</literal></entry>
5274 <entry>
5275 The command is computing statistics from the sample rows obtained
5276 during the table scan.
5277 </entry>
5278 </row>
5279 <row>
5280 <entry><literal>computing extended statistics</literal></entry>
5281 <entry>
5282 The command is computing extended statistics from the sample rows
5283 obtained during the table scan.
5284 </entry>
5285 </row>
5286 <row>
5287 <entry><literal>finalizing analyze</literal></entry>
5288 <entry>
5289 The command is updating <structname>pg_class</structname>. When this
5290 phase is completed, <command>ANALYZE</command> will end.
5291 </entry>
5292 </row>
5293 </tbody>
5294 </tgroup>
5295 </table>
5297 <note>
5298 <para>
5299 Note that when <command>ANALYZE</command> is run on a partitioned table,
5300 all of its partitions are also recursively analyzed.
5301 In that case, <command>ANALYZE</command>
5302 progress is reported first for the parent table, whereby its inheritance
5303 statistics are collected, followed by that for each partition.
5304 </para>
5305 </note>
5306 </sect2>
5308 <sect2 id="cluster-progress-reporting">
5309 <title>CLUSTER Progress Reporting</title>
5311 <indexterm>
5312 <primary>pg_stat_progress_cluster</primary>
5313 </indexterm>
5315 <para>
5316 Whenever <command>CLUSTER</command> or <command>VACUUM FULL</command> is
5317 running, the <structname>pg_stat_progress_cluster</structname> view will
5318 contain a row for each backend that is currently running either command.
5319 The tables below describe the information that will be reported and
5320 provide information about how to interpret it.
5321 </para>
5323 <table id="pg-stat-progress-cluster-view" xreflabel="pg_stat_progress_cluster">
5324 <title><structname>pg_stat_progress_cluster</structname> View</title>
5325 <tgroup cols="1">
5326 <thead>
5327 <row>
5328 <entry role="catalog_table_entry"><para role="column_definition">
5329 Column Type
5330 </para>
5331 <para>
5332 Description
5333 </para></entry>
5334 </row>
5335 </thead>
5337 <tbody>
5338 <row>
5339 <entry role="catalog_table_entry"><para role="column_definition">
5340 <structfield>pid</structfield> <type>integer</type>
5341 </para>
5342 <para>
5343 Process ID of backend.
5344 </para></entry>
5345 </row>
5347 <row>
5348 <entry role="catalog_table_entry"><para role="column_definition">
5349 <structfield>datid</structfield> <type>oid</type>
5350 </para>
5351 <para>
5352 OID of the database to which this backend is connected.
5353 </para></entry>
5354 </row>
5356 <row>
5357 <entry role="catalog_table_entry"><para role="column_definition">
5358 <structfield>datname</structfield> <type>name</type>
5359 </para>
5360 <para>
5361 Name of the database to which this backend is connected.
5362 </para></entry>
5363 </row>
5365 <row>
5366 <entry role="catalog_table_entry"><para role="column_definition">
5367 <structfield>relid</structfield> <type>oid</type>
5368 </para>
5369 <para>
5370 OID of the table being clustered.
5371 </para></entry>
5372 </row>
5374 <row>
5375 <entry role="catalog_table_entry"><para role="column_definition">
5376 <structfield>command</structfield> <type>text</type>
5377 </para>
5378 <para>
5379 The command that is running. Either <literal>CLUSTER</literal> or <literal>VACUUM FULL</literal>.
5380 </para></entry>
5381 </row>
5383 <row>
5384 <entry role="catalog_table_entry"><para role="column_definition">
5385 <structfield>phase</structfield> <type>text</type>
5386 </para>
5387 <para>
5388 Current processing phase. See <xref linkend="cluster-phases"/>.
5389 </para></entry>
5390 </row>
5392 <row>
5393 <entry role="catalog_table_entry"><para role="column_definition">
5394 <structfield>cluster_index_relid</structfield> <type>oid</type>
5395 </para>
5396 <para>
5397 If the table is being scanned using an index, this is the OID of the
5398 index being used; otherwise, it is zero.
5399 </para></entry>
5400 </row>
5402 <row>
5403 <entry role="catalog_table_entry"><para role="column_definition">
5404 <structfield>heap_tuples_scanned</structfield> <type>bigint</type>
5405 </para>
5406 <para>
5407 Number of heap tuples scanned.
5408 This counter only advances when the phase is
5409 <literal>seq scanning heap</literal>,
5410 <literal>index scanning heap</literal>
5411 or <literal>writing new heap</literal>.
5412 </para></entry>
5413 </row>
5415 <row>
5416 <entry role="catalog_table_entry"><para role="column_definition">
5417 <structfield>heap_tuples_written</structfield> <type>bigint</type>
5418 </para>
5419 <para>
5420 Number of heap tuples written.
5421 This counter only advances when the phase is
5422 <literal>seq scanning heap</literal>,
5423 <literal>index scanning heap</literal>
5424 or <literal>writing new heap</literal>.
5425 </para></entry>
5426 </row>
5428 <row>
5429 <entry role="catalog_table_entry"><para role="column_definition">
5430 <structfield>heap_blks_total</structfield> <type>bigint</type>
5431 </para>
5432 <para>
5433 Total number of heap blocks in the table. This number is reported
5434 as of the beginning of <literal>seq scanning heap</literal>.
5435 </para></entry>
5436 </row>
5438 <row>
5439 <entry role="catalog_table_entry"><para role="column_definition">
5440 <structfield>heap_blks_scanned</structfield> <type>bigint</type>
5441 </para>
5442 <para>
5443 Number of heap blocks scanned. This counter only advances when the
5444 phase is <literal>seq scanning heap</literal>.
5445 </para></entry>
5446 </row>
5448 <row>
5449 <entry role="catalog_table_entry"><para role="column_definition">
5450 <structfield>index_rebuild_count</structfield> <type>bigint</type>
5451 </para>
5452 <para>
5453 Number of indexes rebuilt. This counter only advances when the phase
5454 is <literal>rebuilding index</literal>.
5455 </para></entry>
5456 </row>
5457 </tbody>
5458 </tgroup>
5459 </table>
5461 <table id="cluster-phases">
5462 <title>CLUSTER and VACUUM FULL Phases</title>
5463 <tgroup cols="2">
5464 <colspec colname="col1" colwidth="1*"/>
5465 <colspec colname="col2" colwidth="2*"/>
5466 <thead>
5467 <row>
5468 <entry>Phase</entry>
5469 <entry>Description</entry>
5470 </row>
5471 </thead>
5473 <tbody>
5474 <row>
5475 <entry><literal>initializing</literal></entry>
5476 <entry>
5477 The command is preparing to begin scanning the heap. This phase is
5478 expected to be very brief.
5479 </entry>
5480 </row>
5481 <row>
5482 <entry><literal>seq scanning heap</literal></entry>
5483 <entry>
5484 The command is currently scanning the table using a sequential scan.
5485 </entry>
5486 </row>
5487 <row>
5488 <entry><literal>index scanning heap</literal></entry>
5489 <entry>
5490 <command>CLUSTER</command> is currently scanning the table using an index scan.
5491 </entry>
5492 </row>
5493 <row>
5494 <entry><literal>sorting tuples</literal></entry>
5495 <entry>
5496 <command>CLUSTER</command> is currently sorting tuples.
5497 </entry>
5498 </row>
5499 <row>
5500 <entry><literal>writing new heap</literal></entry>
5501 <entry>
5502 <command>CLUSTER</command> is currently writing the new heap.
5503 </entry>
5504 </row>
5505 <row>
5506 <entry><literal>swapping relation files</literal></entry>
5507 <entry>
5508 The command is currently swapping newly-built files into place.
5509 </entry>
5510 </row>
5511 <row>
5512 <entry><literal>rebuilding index</literal></entry>
5513 <entry>
5514 The command is currently rebuilding an index.
5515 </entry>
5516 </row>
5517 <row>
5518 <entry><literal>performing final cleanup</literal></entry>
5519 <entry>
5520 The command is performing final cleanup. When this phase is
5521 completed, <command>CLUSTER</command>
5522 or <command>VACUUM FULL</command> will end.
5523 </entry>
5524 </row>
5525 </tbody>
5526 </tgroup>
5527 </table>
5528 </sect2>
5530 <sect2 id="copy-progress-reporting">
5531 <title>COPY Progress Reporting</title>
5533 <indexterm>
5534 <primary>pg_stat_progress_copy</primary>
5535 </indexterm>
5537 <para>
5538 Whenever <command>COPY</command> is running, the
5539 <structname>pg_stat_progress_copy</structname> view will contain one row
5540 for each backend that is currently running a <command>COPY</command> command.
5541 The table below describes the information that will be reported and provides
5542 information about how to interpret it.
5543 </para>
5545 <table id="pg-stat-progress-copy-view" xreflabel="pg_stat_progress_copy">
5546 <title><structname>pg_stat_progress_copy</structname> View</title>
5547 <tgroup cols="1">
5548 <thead>
5549 <row>
5550 <entry role="catalog_table_entry"><para role="column_definition">
5551 Column Type
5552 </para>
5553 <para>
5554 Description
5555 </para></entry>
5556 </row>
5557 </thead>
5559 <tbody>
5560 <row>
5561 <entry role="catalog_table_entry"><para role="column_definition">
5562 <structfield>pid</structfield> <type>integer</type>
5563 </para>
5564 <para>
5565 Process ID of backend.
5566 </para></entry>
5567 </row>
5569 <row>
5570 <entry role="catalog_table_entry"><para role="column_definition">
5571 <structfield>datid</structfield> <type>oid</type>
5572 </para>
5573 <para>
5574 OID of the database to which this backend is connected.
5575 </para></entry>
5576 </row>
5578 <row>
5579 <entry role="catalog_table_entry"><para role="column_definition">
5580 <structfield>datname</structfield> <type>name</type>
5581 </para>
5582 <para>
5583 Name of the database to which this backend is connected.
5584 </para></entry>
5585 </row>
5587 <row>
5588 <entry role="catalog_table_entry"><para role="column_definition">
5589 <structfield>relid</structfield> <type>oid</type>
5590 </para>
5591 <para>
5592 OID of the table on which the <command>COPY</command> command is
5593 executed. It is set to <literal>0</literal> if copying from a
5594 <command>SELECT</command> query.
5595 </para></entry>
5596 </row>
5598 <row>
5599 <entry role="catalog_table_entry"><para role="column_definition">
5600 <structfield>command</structfield> <type>text</type>
5601 </para>
5602 <para>
5603 The command that is running: <literal>COPY FROM</literal>, or
5604 <literal>COPY TO</literal>.
5605 </para></entry>
5606 </row>
5608 <row>
5609 <entry role="catalog_table_entry"><para role="column_definition">
5610 <structfield>type</structfield> <type>text</type>
5611 </para>
5612 <para>
5613 The io type that the data is read from or written to:
5614 <literal>FILE</literal>, <literal>PROGRAM</literal>,
5615 <literal>PIPE</literal> (for <command>COPY FROM STDIN</command> and
5616 <command>COPY TO STDOUT</command>), or <literal>CALLBACK</literal>
5617 (used for example during the initial table synchronization in
5618 logical replication).
5619 </para></entry>
5620 </row>
5622 <row>
5623 <entry role="catalog_table_entry"><para role="column_definition">
5624 <structfield>bytes_processed</structfield> <type>bigint</type>
5625 </para>
5626 <para>
5627 Number of bytes already processed by <command>COPY</command> command.
5628 </para></entry>
5629 </row>
5631 <row>
5632 <entry role="catalog_table_entry"><para role="column_definition">
5633 <structfield>bytes_total</structfield> <type>bigint</type>
5634 </para>
5635 <para>
5636 Size of source file for <command>COPY FROM</command> command in bytes.
5637 It is set to <literal>0</literal> if not available.
5638 </para></entry>
5639 </row>
5641 <row>
5642 <entry role="catalog_table_entry"><para role="column_definition">
5643 <structfield>tuples_processed</structfield> <type>bigint</type>
5644 </para>
5645 <para>
5646 Number of tuples already processed by <command>COPY</command> command.
5647 </para></entry>
5648 </row>
5650 <row>
5651 <entry role="catalog_table_entry"><para role="column_definition">
5652 <structfield>tuples_excluded</structfield> <type>bigint</type>
5653 </para>
5654 <para>
5655 Number of tuples not processed because they were excluded by the
5656 <command>WHERE</command> clause of the <command>COPY</command> command.
5657 </para></entry>
5658 </row>
5659 </tbody>
5660 </tgroup>
5661 </table>
5662 </sect2>
5664 <sect2 id="create-index-progress-reporting">
5665 <title>CREATE INDEX Progress Reporting</title>
5667 <indexterm>
5668 <primary>pg_stat_progress_create_index</primary>
5669 </indexterm>
5671 <para>
5672 Whenever <command>CREATE INDEX</command> or <command>REINDEX</command> is running, the
5673 <structname>pg_stat_progress_create_index</structname> view will contain
5674 one row for each backend that is currently creating indexes. The tables
5675 below describe the information that will be reported and provide information
5676 about how to interpret it.
5677 </para>
5679 <table id="pg-stat-progress-create-index-view" xreflabel="pg_stat_progress_create_index">
5680 <title><structname>pg_stat_progress_create_index</structname> View</title>
5681 <tgroup cols="1">
5682 <thead>
5683 <row>
5684 <entry role="catalog_table_entry"><para role="column_definition">
5685 Column Type
5686 </para>
5687 <para>
5688 Description
5689 </para></entry>
5690 </row>
5691 </thead>
5693 <tbody>
5694 <row>
5695 <entry role="catalog_table_entry"><para role="column_definition">
5696 <structfield>pid</structfield> <type>integer</type>
5697 </para>
5698 <para>
5699 Process ID of the backend creating indexes.
5700 </para></entry>
5701 </row>
5703 <row>
5704 <entry role="catalog_table_entry"><para role="column_definition">
5705 <structfield>datid</structfield> <type>oid</type>
5706 </para>
5707 <para>
5708 OID of the database to which this backend is connected.
5709 </para></entry>
5710 </row>
5712 <row>
5713 <entry role="catalog_table_entry"><para role="column_definition">
5714 <structfield>datname</structfield> <type>name</type>
5715 </para>
5716 <para>
5717 Name of the database to which this backend is connected.
5718 </para></entry>
5719 </row>
5721 <row>
5722 <entry role="catalog_table_entry"><para role="column_definition">
5723 <structfield>relid</structfield> <type>oid</type>
5724 </para>
5725 <para>
5726 OID of the table on which the index is being created.
5727 </para></entry>
5728 </row>
5730 <row>
5731 <entry role="catalog_table_entry"><para role="column_definition">
5732 <structfield>index_relid</structfield> <type>oid</type>
5733 </para>
5734 <para>
5735 OID of the index being created or reindexed. During a
5736 non-concurrent <command>CREATE INDEX</command>, this is 0.
5737 </para></entry>
5738 </row>
5740 <row>
5741 <entry role="catalog_table_entry"><para role="column_definition">
5742 <structfield>command</structfield> <type>text</type>
5743 </para>
5744 <para>
5745 Specific command type: <literal>CREATE INDEX</literal>,
5746 <literal>CREATE INDEX CONCURRENTLY</literal>,
5747 <literal>REINDEX</literal>, or <literal>REINDEX CONCURRENTLY</literal>.
5748 </para></entry>
5749 </row>
5751 <row>
5752 <entry role="catalog_table_entry"><para role="column_definition">
5753 <structfield>phase</structfield> <type>text</type>
5754 </para>
5755 <para>
5756 Current processing phase of index creation. See <xref linkend="create-index-phases"/>.
5757 </para></entry>
5758 </row>
5760 <row>
5761 <entry role="catalog_table_entry"><para role="column_definition">
5762 <structfield>lockers_total</structfield> <type>bigint</type>
5763 </para>
5764 <para>
5765 Total number of lockers to wait for, when applicable.
5766 </para></entry>
5767 </row>
5769 <row>
5770 <entry role="catalog_table_entry"><para role="column_definition">
5771 <structfield>lockers_done</structfield> <type>bigint</type>
5772 </para>
5773 <para>
5774 Number of lockers already waited for.
5775 </para></entry>
5776 </row>
5778 <row>
5779 <entry role="catalog_table_entry"><para role="column_definition">
5780 <structfield>current_locker_pid</structfield> <type>bigint</type>
5781 </para>
5782 <para>
5783 Process ID of the locker currently being waited for.
5784 </para></entry>
5785 </row>
5787 <row>
5788 <entry role="catalog_table_entry"><para role="column_definition">
5789 <structfield>blocks_total</structfield> <type>bigint</type>
5790 </para>
5791 <para>
5792 Total number of blocks to be processed in the current phase.
5793 </para></entry>
5794 </row>
5796 <row>
5797 <entry role="catalog_table_entry"><para role="column_definition">
5798 <structfield>blocks_done</structfield> <type>bigint</type>
5799 </para>
5800 <para>
5801 Number of blocks already processed in the current phase.
5802 </para></entry>
5803 </row>
5805 <row>
5806 <entry role="catalog_table_entry"><para role="column_definition">
5807 <structfield>tuples_total</structfield> <type>bigint</type>
5808 </para>
5809 <para>
5810 Total number of tuples to be processed in the current phase.
5811 </para></entry>
5812 </row>
5814 <row>
5815 <entry role="catalog_table_entry"><para role="column_definition">
5816 <structfield>tuples_done</structfield> <type>bigint</type>
5817 </para>
5818 <para>
5819 Number of tuples already processed in the current phase.
5820 </para></entry>
5821 </row>
5823 <row>
5824 <entry role="catalog_table_entry"><para role="column_definition">
5825 <structfield>partitions_total</structfield> <type>bigint</type>
5826 </para>
5827 <para>
5828 Total number of partitions on which the index is to be created
5829 or attached, including both direct and indirect partitions.
5830 <literal>0</literal> during a <literal>REINDEX</literal>, or when
5831 the index is not partitioned.
5832 </para></entry>
5833 </row>
5835 <row>
5836 <entry role="catalog_table_entry"><para role="column_definition">
5837 <structfield>partitions_done</structfield> <type>bigint</type>
5838 </para>
5839 <para>
5840 Number of partitions on which the index has already been created
5841 or attached, including both direct and indirect partitions.
5842 <literal>0</literal> during a <literal>REINDEX</literal>, or when
5843 the index is not partitioned.
5844 </para></entry>
5845 </row>
5846 </tbody>
5847 </tgroup>
5848 </table>
5850 <table id="create-index-phases">
5851 <title>CREATE INDEX Phases</title>
5852 <tgroup cols="2">
5853 <colspec colname="col1" colwidth="1*"/>
5854 <colspec colname="col2" colwidth="2*"/>
5855 <thead>
5856 <row>
5857 <entry>Phase</entry>
5858 <entry>Description</entry>
5859 </row>
5860 </thead>
5861 <tbody>
5862 <row>
5863 <entry><literal>initializing</literal></entry>
5864 <entry>
5865 <command>CREATE INDEX</command> or <command>REINDEX</command> is preparing to create the index. This
5866 phase is expected to be very brief.
5867 </entry>
5868 </row>
5869 <row>
5870 <entry><literal>waiting for writers before build</literal></entry>
5871 <entry>
5872 <command>CREATE INDEX CONCURRENTLY</command> or <command>REINDEX CONCURRENTLY</command> is waiting for transactions
5873 with write locks that can potentially see the table to finish.
5874 This phase is skipped when not in concurrent mode.
5875 Columns <structname>lockers_total</structname>, <structname>lockers_done</structname>
5876 and <structname>current_locker_pid</structname> contain the progress
5877 information for this phase.
5878 </entry>
5879 </row>
5880 <row>
5881 <entry><literal>building index</literal></entry>
5882 <entry>
5883 The index is being built by the access method-specific code. In this phase,
5884 access methods that support progress reporting fill in their own progress data,
5885 and the subphase is indicated in this column. Typically,
5886 <structname>blocks_total</structname> and <structname>blocks_done</structname>
5887 will contain progress data, as well as potentially
5888 <structname>tuples_total</structname> and <structname>tuples_done</structname>.
5889 </entry>
5890 </row>
5891 <row>
5892 <entry><literal>waiting for writers before validation</literal></entry>
5893 <entry>
5894 <command>CREATE INDEX CONCURRENTLY</command> or <command>REINDEX CONCURRENTLY</command> is waiting for transactions
5895 with write locks that can potentially write into the table to finish.
5896 This phase is skipped when not in concurrent mode.
5897 Columns <structname>lockers_total</structname>, <structname>lockers_done</structname>
5898 and <structname>current_locker_pid</structname> contain the progress
5899 information for this phase.
5900 </entry>
5901 </row>
5902 <row>
5903 <entry><literal>index validation: scanning index</literal></entry>
5904 <entry>
5905 <command>CREATE INDEX CONCURRENTLY</command> is scanning the index searching
5906 for tuples that need to be validated.
5907 This phase is skipped when not in concurrent mode.
5908 Columns <structname>blocks_total</structname> (set to the total size of the index)
5909 and <structname>blocks_done</structname> contain the progress information for this phase.
5910 </entry>
5911 </row>
5912 <row>
5913 <entry><literal>index validation: sorting tuples</literal></entry>
5914 <entry>
5915 <command>CREATE INDEX CONCURRENTLY</command> is sorting the output of the
5916 index scanning phase.
5917 </entry>
5918 </row>
5919 <row>
5920 <entry><literal>index validation: scanning table</literal></entry>
5921 <entry>
5922 <command>CREATE INDEX CONCURRENTLY</command> is scanning the table
5923 to validate the index tuples collected in the previous two phases.
5924 This phase is skipped when not in concurrent mode.
5925 Columns <structname>blocks_total</structname> (set to the total size of the table)
5926 and <structname>blocks_done</structname> contain the progress information for this phase.
5927 </entry>
5928 </row>
5929 <row>
5930 <entry><literal>waiting for old snapshots</literal></entry>
5931 <entry>
5932 <command>CREATE INDEX CONCURRENTLY</command> or <command>REINDEX CONCURRENTLY</command> is waiting for transactions
5933 that can potentially see the table to release their snapshots. This
5934 phase is skipped when not in concurrent mode.
5935 Columns <structname>lockers_total</structname>, <structname>lockers_done</structname>
5936 and <structname>current_locker_pid</structname> contain the progress
5937 information for this phase.
5938 </entry>
5939 </row>
5940 <row>
5941 <entry><literal>waiting for readers before marking dead</literal></entry>
5942 <entry>
5943 <command>REINDEX CONCURRENTLY</command> is waiting for transactions
5944 with read locks on the table to finish, before marking the old index dead.
5945 This phase is skipped when not in concurrent mode.
5946 Columns <structname>lockers_total</structname>, <structname>lockers_done</structname>
5947 and <structname>current_locker_pid</structname> contain the progress
5948 information for this phase.
5949 </entry>
5950 </row>
5951 <row>
5952 <entry><literal>waiting for readers before dropping</literal></entry>
5953 <entry>
5954 <command>REINDEX CONCURRENTLY</command> is waiting for transactions
5955 with read locks on the table to finish, before dropping the old index.
5956 This phase is skipped when not in concurrent mode.
5957 Columns <structname>lockers_total</structname>, <structname>lockers_done</structname>
5958 and <structname>current_locker_pid</structname> contain the progress
5959 information for this phase.
5960 </entry>
5961 </row>
5962 </tbody>
5963 </tgroup>
5964 </table>
5966 </sect2>
5968 <sect2 id="vacuum-progress-reporting">
5969 <title>VACUUM Progress Reporting</title>
5971 <indexterm>
5972 <primary>pg_stat_progress_vacuum</primary>
5973 </indexterm>
5975 <para>
5976 Whenever <command>VACUUM</command> is running, the
5977 <structname>pg_stat_progress_vacuum</structname> view will contain
5978 one row for each backend (including autovacuum worker processes) that is
5979 currently vacuuming. The tables below describe the information
5980 that will be reported and provide information about how to interpret it.
5981 Progress for <command>VACUUM FULL</command> commands is reported via
5982 <structname>pg_stat_progress_cluster</structname>
5983 because both <command>VACUUM FULL</command> and <command>CLUSTER</command>
5984 rewrite the table, while regular <command>VACUUM</command> only modifies it
5985 in place. See <xref linkend="cluster-progress-reporting"/>.
5986 </para>
5988 <table id="pg-stat-progress-vacuum-view" xreflabel="pg_stat_progress_vacuum">
5989 <title><structname>pg_stat_progress_vacuum</structname> View</title>
5990 <tgroup cols="1">
5991 <thead>
5992 <row>
5993 <entry role="catalog_table_entry"><para role="column_definition">
5994 Column Type
5995 </para>
5996 <para>
5997 Description
5998 </para></entry>
5999 </row>
6000 </thead>
6002 <tbody>
6003 <row>
6004 <entry role="catalog_table_entry"><para role="column_definition">
6005 <structfield>pid</structfield> <type>integer</type>
6006 </para>
6007 <para>
6008 Process ID of backend.
6009 </para></entry>
6010 </row>
6012 <row>
6013 <entry role="catalog_table_entry"><para role="column_definition">
6014 <structfield>datid</structfield> <type>oid</type>
6015 </para>
6016 <para>
6017 OID of the database to which this backend is connected.
6018 </para></entry>
6019 </row>
6021 <row>
6022 <entry role="catalog_table_entry"><para role="column_definition">
6023 <structfield>datname</structfield> <type>name</type>
6024 </para>
6025 <para>
6026 Name of the database to which this backend is connected.
6027 </para></entry>
6028 </row>
6030 <row>
6031 <entry role="catalog_table_entry"><para role="column_definition">
6032 <structfield>relid</structfield> <type>oid</type>
6033 </para>
6034 <para>
6035 OID of the table being vacuumed.
6036 </para></entry>
6037 </row>
6039 <row>
6040 <entry role="catalog_table_entry"><para role="column_definition">
6041 <structfield>phase</structfield> <type>text</type>
6042 </para>
6043 <para>
6044 Current processing phase of vacuum. See <xref linkend="vacuum-phases"/>.
6045 </para></entry>
6046 </row>
6048 <row>
6049 <entry role="catalog_table_entry"><para role="column_definition">
6050 <structfield>heap_blks_total</structfield> <type>bigint</type>
6051 </para>
6052 <para>
6053 Total number of heap blocks in the table. This number is reported
6054 as of the beginning of the scan; blocks added later will not be (and
6055 need not be) visited by this <command>VACUUM</command>.
6056 </para></entry>
6057 </row>
6059 <row>
6060 <entry role="catalog_table_entry"><para role="column_definition">
6061 <structfield>heap_blks_scanned</structfield> <type>bigint</type>
6062 </para>
6063 <para>
6064 Number of heap blocks scanned. Because the
6065 <link linkend="storage-vm">visibility map</link> is used to optimize scans,
6066 some blocks will be skipped without inspection; skipped blocks are
6067 included in this total, so that this number will eventually become
6068 equal to <structfield>heap_blks_total</structfield> when the vacuum is complete.
6069 This counter only advances when the phase is <literal>scanning heap</literal>.
6070 </para></entry>
6071 </row>
6073 <row>
6074 <entry role="catalog_table_entry"><para role="column_definition">
6075 <structfield>heap_blks_vacuumed</structfield> <type>bigint</type>
6076 </para>
6077 <para>
6078 Number of heap blocks vacuumed. Unless the table has no indexes, this
6079 counter only advances when the phase is <literal>vacuuming heap</literal>.
6080 Blocks that contain no dead tuples are skipped, so the counter may
6081 sometimes skip forward in large increments.
6082 </para></entry>
6083 </row>
6085 <row>
6086 <entry role="catalog_table_entry"><para role="column_definition">
6087 <structfield>index_vacuum_count</structfield> <type>bigint</type>
6088 </para>
6089 <para>
6090 Number of completed index vacuum cycles.
6091 </para></entry>
6092 </row>
6094 <row>
6095 <entry role="catalog_table_entry"><para role="column_definition">
6096 <structfield>max_dead_tuples</structfield> <type>bigint</type>
6097 </para>
6098 <para>
6099 Number of dead tuples that we can store before needing to perform
6100 an index vacuum cycle, based on
6101 <xref linkend="guc-maintenance-work-mem"/>.
6102 </para></entry>
6103 </row>
6105 <row>
6106 <entry role="catalog_table_entry"><para role="column_definition">
6107 <structfield>num_dead_tuples</structfield> <type>bigint</type>
6108 </para>
6109 <para>
6110 Number of dead tuples collected since the last index vacuum cycle.
6111 </para></entry>
6112 </row>
6113 </tbody>
6114 </tgroup>
6115 </table>
6117 <table id="vacuum-phases">
6118 <title>VACUUM Phases</title>
6119 <tgroup cols="2">
6120 <colspec colname="col1" colwidth="1*"/>
6121 <colspec colname="col2" colwidth="2*"/>
6122 <thead>
6123 <row>
6124 <entry>Phase</entry>
6125 <entry>Description</entry>
6126 </row>
6127 </thead>
6129 <tbody>
6130 <row>
6131 <entry><literal>initializing</literal></entry>
6132 <entry>
6133 <command>VACUUM</command> is preparing to begin scanning the heap. This
6134 phase is expected to be very brief.
6135 </entry>
6136 </row>
6137 <row>
6138 <entry><literal>scanning heap</literal></entry>
6139 <entry>
6140 <command>VACUUM</command> is currently scanning the heap. It will prune and
6141 defragment each page if required, and possibly perform freezing
6142 activity. The <structfield>heap_blks_scanned</structfield> column can be used
6143 to monitor the progress of the scan.
6144 </entry>
6145 </row>
6146 <row>
6147 <entry><literal>vacuuming indexes</literal></entry>
6148 <entry>
6149 <command>VACUUM</command> is currently vacuuming the indexes. If a table has
6150 any indexes, this will happen at least once per vacuum, after the heap
6151 has been completely scanned. It may happen multiple times per vacuum
6152 if <xref linkend="guc-maintenance-work-mem"/> (or, in the case of autovacuum,
6153 <xref linkend="guc-autovacuum-work-mem"/> if set) is insufficient to store
6154 the number of dead tuples found.
6155 </entry>
6156 </row>
6157 <row>
6158 <entry><literal>vacuuming heap</literal></entry>
6159 <entry>
6160 <command>VACUUM</command> is currently vacuuming the heap. Vacuuming the heap
6161 is distinct from scanning the heap, and occurs after each instance of
6162 vacuuming indexes. If <structfield>heap_blks_scanned</structfield> is less than
6163 <structfield>heap_blks_total</structfield>, the system will return to scanning
6164 the heap after this phase is completed; otherwise, it will begin
6165 cleaning up indexes after this phase is completed.
6166 </entry>
6167 </row>
6168 <row>
6169 <entry><literal>cleaning up indexes</literal></entry>
6170 <entry>
6171 <command>VACUUM</command> is currently cleaning up indexes. This occurs after
6172 the heap has been completely scanned and all vacuuming of the indexes
6173 and the heap has been completed.
6174 </entry>
6175 </row>
6176 <row>
6177 <entry><literal>truncating heap</literal></entry>
6178 <entry>
6179 <command>VACUUM</command> is currently truncating the heap so as to return
6180 empty pages at the end of the relation to the operating system. This
6181 occurs after cleaning up indexes.
6182 </entry>
6183 </row>
6184 <row>
6185 <entry><literal>performing final cleanup</literal></entry>
6186 <entry>
6187 <command>VACUUM</command> is performing final cleanup. During this phase,
6188 <command>VACUUM</command> will vacuum the free space map, update statistics
6189 in <literal>pg_class</literal>, and report statistics to the cumulative
6190 statistics system. When this phase is completed, <command>VACUUM</command> will end.
6191 </entry>
6192 </row>
6193 </tbody>
6194 </tgroup>
6195 </table>
6196 </sect2>
6198 <sect2 id="basebackup-progress-reporting">
6199 <title>Base Backup Progress Reporting</title>
6201 <indexterm>
6202 <primary>pg_stat_progress_basebackup</primary>
6203 </indexterm>
6205 <para>
6206 Whenever an application like <application>pg_basebackup</application>
6207 is taking a base backup, the
6208 <structname>pg_stat_progress_basebackup</structname>
6209 view will contain a row for each WAL sender process that is currently
6210 running the <command>BASE_BACKUP</command> replication command
6211 and streaming the backup. The tables below describe the information
6212 that will be reported and provide information about how to interpret it.
6213 </para>
6215 <table id="pg-stat-progress-basebackup-view" xreflabel="pg_stat_progress_basebackup">
6216 <title><structname>pg_stat_progress_basebackup</structname> View</title>
6217 <tgroup cols="1">
6218 <thead>
6219 <row>
6220 <entry role="catalog_table_entry"><para role="column_definition">
6221 Column Type
6222 </para>
6223 <para>
6224 Description
6225 </para></entry>
6226 </row>
6227 </thead>
6229 <tbody>
6230 <row>
6231 <entry role="catalog_table_entry"><para role="column_definition">
6232 <structfield>pid</structfield> <type>integer</type>
6233 </para>
6234 <para>
6235 Process ID of a WAL sender process.
6236 </para></entry>
6237 </row>
6239 <row>
6240 <entry role="catalog_table_entry"><para role="column_definition">
6241 <structfield>phase</structfield> <type>text</type>
6242 </para>
6243 <para>
6244 Current processing phase. See <xref linkend="basebackup-phases"/>.
6245 </para></entry>
6246 </row>
6248 <row>
6249 <entry role="catalog_table_entry"><para role="column_definition">
6250 <structfield>backup_total</structfield> <type>bigint</type>
6251 </para>
6252 <para>
6253 Total amount of data that will be streamed. This is estimated and
6254 reported as of the beginning of
6255 <literal>streaming database files</literal> phase. Note that
6256 this is only an approximation since the database
6257 may change during <literal>streaming database files</literal> phase
6258 and WAL log may be included in the backup later. This is always
6259 the same value as <structfield>backup_streamed</structfield>
6260 once the amount of data streamed exceeds the estimated
6261 total size. If the estimation is disabled in
6262 <application>pg_basebackup</application>
6263 (i.e., <literal>--no-estimate-size</literal> option is specified),
6264 this is <literal>NULL</literal>.
6265 </para></entry>
6266 </row>
6268 <row>
6269 <entry role="catalog_table_entry"><para role="column_definition">
6270 <structfield>backup_streamed</structfield> <type>bigint</type>
6271 </para>
6272 <para>
6273 Amount of data streamed. This counter only advances
6274 when the phase is <literal>streaming database files</literal> or
6275 <literal>transferring wal files</literal>.
6276 </para></entry>
6277 </row>
6279 <row>
6280 <entry role="catalog_table_entry"><para role="column_definition">
6281 <structfield>tablespaces_total</structfield> <type>bigint</type>
6282 </para>
6283 <para>
6284 Total number of tablespaces that will be streamed.
6285 </para></entry>
6286 </row>
6288 <row>
6289 <entry role="catalog_table_entry"><para role="column_definition">
6290 <structfield>tablespaces_streamed</structfield> <type>bigint</type>
6291 </para>
6292 <para>
6293 Number of tablespaces streamed. This counter only
6294 advances when the phase is <literal>streaming database files</literal>.
6295 </para></entry>
6296 </row>
6297 </tbody>
6298 </tgroup>
6299 </table>
6301 <table id="basebackup-phases">
6302 <title>Base Backup Phases</title>
6303 <tgroup cols="2">
6304 <colspec colname="col1" colwidth="1*"/>
6305 <colspec colname="col2" colwidth="2*"/>
6306 <thead>
6307 <row>
6308 <entry>Phase</entry>
6309 <entry>Description</entry>
6310 </row>
6311 </thead>
6312 <tbody>
6313 <row>
6314 <entry><literal>initializing</literal></entry>
6315 <entry>
6316 The WAL sender process is preparing to begin the backup.
6317 This phase is expected to be very brief.
6318 </entry>
6319 </row>
6320 <row>
6321 <entry><literal>waiting for checkpoint to finish</literal></entry>
6322 <entry>
6323 The WAL sender process is currently performing
6324 <function>pg_backup_start</function> to prepare to
6325 take a base backup, and waiting for the start-of-backup
6326 checkpoint to finish.
6327 </entry>
6328 </row>
6329 <row>
6330 <entry><literal>estimating backup size</literal></entry>
6331 <entry>
6332 The WAL sender process is currently estimating the total amount
6333 of database files that will be streamed as a base backup.
6334 </entry>
6335 </row>
6336 <row>
6337 <entry><literal>streaming database files</literal></entry>
6338 <entry>
6339 The WAL sender process is currently streaming database files
6340 as a base backup.
6341 </entry>
6342 </row>
6343 <row>
6344 <entry><literal>waiting for wal archiving to finish</literal></entry>
6345 <entry>
6346 The WAL sender process is currently performing
6347 <function>pg_backup_stop</function> to finish the backup,
6348 and waiting for all the WAL files required for the base backup
6349 to be successfully archived.
6350 If either <literal>--wal-method=none</literal> or
6351 <literal>--wal-method=stream</literal> is specified in
6352 <application>pg_basebackup</application>, the backup will end
6353 when this phase is completed.
6354 </entry>
6355 </row>
6356 <row>
6357 <entry><literal>transferring wal files</literal></entry>
6358 <entry>
6359 The WAL sender process is currently transferring all WAL logs
6360 generated during the backup. This phase occurs after
6361 <literal>waiting for wal archiving to finish</literal> phase if
6362 <literal>--wal-method=fetch</literal> is specified in
6363 <application>pg_basebackup</application>. The backup will end
6364 when this phase is completed.
6365 </entry>
6366 </row>
6367 </tbody>
6368 </tgroup>
6369 </table>
6371 </sect2>
6373 </sect1>
6375 <sect1 id="dynamic-trace">
6376 <title>Dynamic Tracing</title>
6378 <indexterm zone="dynamic-trace">
6379 <primary>DTrace</primary>
6380 </indexterm>
6382 <para>
6383 <productname>PostgreSQL</productname> provides facilities to support
6384 dynamic tracing of the database server. This allows an external
6385 utility to be called at specific points in the code and thereby trace
6386 execution.
6387 </para>
6389 <para>
6390 A number of probes or trace points are already inserted into the source
6391 code. These probes are intended to be used by database developers and
6392 administrators. By default the probes are not compiled into
6393 <productname>PostgreSQL</productname>; the user needs to explicitly tell
6394 the configure script to make the probes available.
6395 </para>
6397 <para>
6398 Currently, the
6399 <ulink url="https://en.wikipedia.org/wiki/DTrace">DTrace</ulink>
6400 utility is supported, which, at the time of this writing, is available
6401 on Solaris, macOS, FreeBSD, NetBSD, and Oracle Linux. The
6402 <ulink url="https://sourceware.org/systemtap/">SystemTap</ulink> project
6403 for Linux provides a DTrace equivalent and can also be used. Supporting other dynamic
6404 tracing utilities is theoretically possible by changing the definitions for
6405 the macros in <filename>src/include/utils/probes.h</filename>.
6406 </para>
6408 <sect2 id="compiling-for-trace">
6409 <title>Compiling for Dynamic Tracing</title>
6411 <para>
6412 By default, probes are not available, so you will need to
6413 explicitly tell the configure script to make the probes available
6414 in <productname>PostgreSQL</productname>. To include DTrace support
6415 specify <option>--enable-dtrace</option> to configure. See <xref
6416 linkend="configure-options-devel"/> for further information.
6417 </para>
6418 </sect2>
6420 <sect2 id="trace-points">
6421 <title>Built-in Probes</title>
6423 <para>
6424 A number of standard probes are provided in the source code,
6425 as shown in <xref linkend="dtrace-probe-point-table"/>;
6426 <xref linkend="typedefs-table"/>
6427 shows the types used in the probes. More probes can certainly be
6428 added to enhance <productname>PostgreSQL</productname>'s observability.
6429 </para>
6431 <table id="dtrace-probe-point-table">
6432 <title>Built-in DTrace Probes</title>
6433 <tgroup cols="3">
6434 <colspec colname="col1" colwidth="2*"/>
6435 <colspec colname="col2" colwidth="3*"/>
6436 <colspec colname="col3" colwidth="3*"/>
6437 <thead>
6438 <row>
6439 <entry>Name</entry>
6440 <entry>Parameters</entry>
6441 <entry>Description</entry>
6442 </row>
6443 </thead>
6445 <tbody>
6447 <row>
6448 <entry><literal>transaction-start</literal></entry>
6449 <entry><literal>(LocalTransactionId)</literal></entry>
6450 <entry>Probe that fires at the start of a new transaction.
6451 arg0 is the transaction ID.</entry>
6452 </row>
6453 <row>
6454 <entry><literal>transaction-commit</literal></entry>
6455 <entry><literal>(LocalTransactionId)</literal></entry>
6456 <entry>Probe that fires when a transaction completes successfully.
6457 arg0 is the transaction ID.</entry>
6458 </row>
6459 <row>
6460 <entry><literal>transaction-abort</literal></entry>
6461 <entry><literal>(LocalTransactionId)</literal></entry>
6462 <entry>Probe that fires when a transaction completes unsuccessfully.
6463 arg0 is the transaction ID.</entry>
6464 </row>
6465 <row>
6466 <entry><literal>query-start</literal></entry>
6467 <entry><literal>(const char *)</literal></entry>
6468 <entry>Probe that fires when the processing of a query is started.
6469 arg0 is the query string.</entry>
6470 </row>
6471 <row>
6472 <entry><literal>query-done</literal></entry>
6473 <entry><literal>(const char *)</literal></entry>
6474 <entry>Probe that fires when the processing of a query is complete.
6475 arg0 is the query string.</entry>
6476 </row>
6477 <row>
6478 <entry><literal>query-parse-start</literal></entry>
6479 <entry><literal>(const char *)</literal></entry>
6480 <entry>Probe that fires when the parsing of a query is started.
6481 arg0 is the query string.</entry>
6482 </row>
6483 <row>
6484 <entry><literal>query-parse-done</literal></entry>
6485 <entry><literal>(const char *)</literal></entry>
6486 <entry>Probe that fires when the parsing of a query is complete.
6487 arg0 is the query string.</entry>
6488 </row>
6489 <row>
6490 <entry><literal>query-rewrite-start</literal></entry>
6491 <entry><literal>(const char *)</literal></entry>
6492 <entry>Probe that fires when the rewriting of a query is started.
6493 arg0 is the query string.</entry>
6494 </row>
6495 <row>
6496 <entry><literal>query-rewrite-done</literal></entry>
6497 <entry><literal>(const char *)</literal></entry>
6498 <entry>Probe that fires when the rewriting of a query is complete.
6499 arg0 is the query string.</entry>
6500 </row>
6501 <row>
6502 <entry><literal>query-plan-start</literal></entry>
6503 <entry><literal>()</literal></entry>
6504 <entry>Probe that fires when the planning of a query is started.</entry>
6505 </row>
6506 <row>
6507 <entry><literal>query-plan-done</literal></entry>
6508 <entry><literal>()</literal></entry>
6509 <entry>Probe that fires when the planning of a query is complete.</entry>
6510 </row>
6511 <row>
6512 <entry><literal>query-execute-start</literal></entry>
6513 <entry><literal>()</literal></entry>
6514 <entry>Probe that fires when the execution of a query is started.</entry>
6515 </row>
6516 <row>
6517 <entry><literal>query-execute-done</literal></entry>
6518 <entry><literal>()</literal></entry>
6519 <entry>Probe that fires when the execution of a query is complete.</entry>
6520 </row>
6521 <row>
6522 <entry><literal>statement-status</literal></entry>
6523 <entry><literal>(const char *)</literal></entry>
6524 <entry>Probe that fires anytime the server process updates its
6525 <structname>pg_stat_activity</structname>.<structfield>status</structfield>.
6526 arg0 is the new status string.</entry>
6527 </row>
6528 <row>
6529 <entry><literal>checkpoint-start</literal></entry>
6530 <entry><literal>(int)</literal></entry>
6531 <entry>Probe that fires when a checkpoint is started.
6532 arg0 holds the bitwise flags used to distinguish different checkpoint
6533 types, such as shutdown, immediate or force.</entry>
6534 </row>
6535 <row>
6536 <entry><literal>checkpoint-done</literal></entry>
6537 <entry><literal>(int, int, int, int, int)</literal></entry>
6538 <entry>Probe that fires when a checkpoint is complete.
6539 (The probes listed next fire in sequence during checkpoint processing.)
6540 arg0 is the number of buffers written. arg1 is the total number of
6541 buffers. arg2, arg3 and arg4 contain the number of WAL files added,
6542 removed and recycled respectively.</entry>
6543 </row>
6544 <row>
6545 <entry><literal>clog-checkpoint-start</literal></entry>
6546 <entry><literal>(bool)</literal></entry>
6547 <entry>Probe that fires when the CLOG portion of a checkpoint is started.
6548 arg0 is true for normal checkpoint, false for shutdown
6549 checkpoint.</entry>
6550 </row>
6551 <row>
6552 <entry><literal>clog-checkpoint-done</literal></entry>
6553 <entry><literal>(bool)</literal></entry>
6554 <entry>Probe that fires when the CLOG portion of a checkpoint is
6555 complete. arg0 has the same meaning as for <literal>clog-checkpoint-start</literal>.</entry>
6556 </row>
6557 <row>
6558 <entry><literal>subtrans-checkpoint-start</literal></entry>
6559 <entry><literal>(bool)</literal></entry>
6560 <entry>Probe that fires when the SUBTRANS portion of a checkpoint is
6561 started.
6562 arg0 is true for normal checkpoint, false for shutdown
6563 checkpoint.</entry>
6564 </row>
6565 <row>
6566 <entry><literal>subtrans-checkpoint-done</literal></entry>
6567 <entry><literal>(bool)</literal></entry>
6568 <entry>Probe that fires when the SUBTRANS portion of a checkpoint is
6569 complete. arg0 has the same meaning as for
6570 <literal>subtrans-checkpoint-start</literal>.</entry>
6571 </row>
6572 <row>
6573 <entry><literal>multixact-checkpoint-start</literal></entry>
6574 <entry><literal>(bool)</literal></entry>
6575 <entry>Probe that fires when the MultiXact portion of a checkpoint is
6576 started.
6577 arg0 is true for normal checkpoint, false for shutdown
6578 checkpoint.</entry>
6579 </row>
6580 <row>
6581 <entry><literal>multixact-checkpoint-done</literal></entry>
6582 <entry><literal>(bool)</literal></entry>
6583 <entry>Probe that fires when the MultiXact portion of a checkpoint is
6584 complete. arg0 has the same meaning as for
6585 <literal>multixact-checkpoint-start</literal>.</entry>
6586 </row>
6587 <row>
6588 <entry><literal>buffer-checkpoint-start</literal></entry>
6589 <entry><literal>(int)</literal></entry>
6590 <entry>Probe that fires when the buffer-writing portion of a checkpoint
6591 is started.
6592 arg0 holds the bitwise flags used to distinguish different checkpoint
6593 types, such as shutdown, immediate or force.</entry>
6594 </row>
6595 <row>
6596 <entry><literal>buffer-sync-start</literal></entry>
6597 <entry><literal>(int, int)</literal></entry>
6598 <entry>Probe that fires when we begin to write dirty buffers during
6599 checkpoint (after identifying which buffers must be written).
6600 arg0 is the total number of buffers.
6601 arg1 is the number that are currently dirty and need to be written.</entry>
6602 </row>
6603 <row>
6604 <entry><literal>buffer-sync-written</literal></entry>
6605 <entry><literal>(int)</literal></entry>
6606 <entry>Probe that fires after each buffer is written during checkpoint.
6607 arg0 is the ID number of the buffer.</entry>
6608 </row>
6609 <row>
6610 <entry><literal>buffer-sync-done</literal></entry>
6611 <entry><literal>(int, int, int)</literal></entry>
6612 <entry>Probe that fires when all dirty buffers have been written.
6613 arg0 is the total number of buffers.
6614 arg1 is the number of buffers actually written by the checkpoint process.
6615 arg2 is the number that were expected to be written (arg1 of
6616 <literal>buffer-sync-start</literal>); any difference reflects other processes flushing
6617 buffers during the checkpoint.</entry>
6618 </row>
6619 <row>
6620 <entry><literal>buffer-checkpoint-sync-start</literal></entry>
6621 <entry><literal>()</literal></entry>
6622 <entry>Probe that fires after dirty buffers have been written to the
6623 kernel, and before starting to issue fsync requests.</entry>
6624 </row>
6625 <row>
6626 <entry><literal>buffer-checkpoint-done</literal></entry>
6627 <entry><literal>()</literal></entry>
6628 <entry>Probe that fires when syncing of buffers to disk is
6629 complete.</entry>
6630 </row>
6631 <row>
6632 <entry><literal>twophase-checkpoint-start</literal></entry>
6633 <entry><literal>()</literal></entry>
6634 <entry>Probe that fires when the two-phase portion of a checkpoint is
6635 started.</entry>
6636 </row>
6637 <row>
6638 <entry><literal>twophase-checkpoint-done</literal></entry>
6639 <entry><literal>()</literal></entry>
6640 <entry>Probe that fires when the two-phase portion of a checkpoint is
6641 complete.</entry>
6642 </row>
6643 <row>
6644 <entry><literal>buffer-extend-start</literal></entry>
6645 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, unsigned int)</literal></entry>
6646 <entry>Probe that fires when a relation extension starts.
6647 arg0 contains the fork to be extended. arg1, arg2, and arg3 contain the
6648 tablespace, database, and relation OIDs identifying the relation. arg4
6649 is the ID of the backend which created the temporary relation for a
6650 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared
6651 buffer. arg5 is the number of blocks the caller would like to extend
6652 by.</entry>
6653 </row>
6654 <row>
6655 <entry><literal>buffer-extend-done</literal></entry>
6656 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, unsigned int, BlockNumber)</literal></entry>
6657 <entry>Probe that fires when a relation extension is complete.
6658 arg0 contains the fork to be extended. arg1, arg2, and arg3 contain the
6659 tablespace, database, and relation OIDs identifying the relation. arg4
6660 is the ID of the backend which created the temporary relation for a
6661 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared
6662 buffer. arg5 is the number of blocks the relation was extended by, this
6663 can be less than the number in the
6664 <literal>buffer-extend-start</literal> due to resource
6665 constraints. arg6 contains the BlockNumber of the first new
6666 block.</entry>
6667 </row>
6668 <row>
6669 <entry><literal>buffer-read-start</literal></entry>
6670 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</literal></entry>
6671 <entry>Probe that fires when a buffer read is started.
6672 arg0 and arg1 contain the fork and block numbers of the page.
6673 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6674 identifying the relation.
6675 arg5 is the ID of the backend which created the temporary relation for a
6676 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared buffer.
6677 </entry>
6678 </row>
6679 <row>
6680 <entry><literal>buffer-read-done</literal></entry>
6681 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool)</literal></entry>
6682 <entry>Probe that fires when a buffer read is complete.
6683 arg0 and arg1 contain the fork and block numbers of the page.
6684 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6685 identifying the relation.
6686 arg5 is the ID of the backend which created the temporary relation for a
6687 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared buffer.
6688 arg6 is true if the buffer was found in the pool, false if not.</entry>
6689 </row>
6690 <row>
6691 <entry><literal>buffer-flush-start</literal></entry>
6692 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid)</literal></entry>
6693 <entry>Probe that fires before issuing any write request for a shared
6694 buffer.
6695 arg0 and arg1 contain the fork and block numbers of the page.
6696 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6697 identifying the relation.</entry>
6698 </row>
6699 <row>
6700 <entry><literal>buffer-flush-done</literal></entry>
6701 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid)</literal></entry>
6702 <entry>Probe that fires when a write request is complete. (Note
6703 that this just reflects the time to pass the data to the kernel;
6704 it's typically not actually been written to disk yet.)
6705 The arguments are the same as for <literal>buffer-flush-start</literal>.</entry>
6706 </row>
6707 <row>
6708 <entry><literal>wal-buffer-write-dirty-start</literal></entry>
6709 <entry><literal>()</literal></entry>
6710 <entry>Probe that fires when a server process begins to write a
6711 dirty WAL buffer because no more WAL buffer space is available.
6712 (If this happens often, it implies that
6713 <xref linkend="guc-wal-buffers"/> is too small.)</entry>
6714 </row>
6715 <row>
6716 <entry><literal>wal-buffer-write-dirty-done</literal></entry>
6717 <entry><literal>()</literal></entry>
6718 <entry>Probe that fires when a dirty WAL buffer write is complete.</entry>
6719 </row>
6720 <row>
6721 <entry><literal>wal-insert</literal></entry>
6722 <entry><literal>(unsigned char, unsigned char)</literal></entry>
6723 <entry>Probe that fires when a WAL record is inserted.
6724 arg0 is the resource manager (rmid) for the record.
6725 arg1 contains the info flags.</entry>
6726 </row>
6727 <row>
6728 <entry><literal>wal-switch</literal></entry>
6729 <entry><literal>()</literal></entry>
6730 <entry>Probe that fires when a WAL segment switch is requested.</entry>
6731 </row>
6732 <row>
6733 <entry><literal>smgr-md-read-start</literal></entry>
6734 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</literal></entry>
6735 <entry>Probe that fires when beginning to read a block from a relation.
6736 arg0 and arg1 contain the fork and block numbers of the page.
6737 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6738 identifying the relation.
6739 arg5 is the ID of the backend which created the temporary relation for a
6740 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared buffer.</entry>
6741 </row>
6742 <row>
6743 <entry><literal>smgr-md-read-done</literal></entry>
6744 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</literal></entry>
6745 <entry>Probe that fires when a block read is complete.
6746 arg0 and arg1 contain the fork and block numbers of the page.
6747 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6748 identifying the relation.
6749 arg5 is the ID of the backend which created the temporary relation for a
6750 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared buffer.
6751 arg6 is the number of bytes actually read, while arg7 is the number
6752 requested (if these are different it indicates trouble).</entry>
6753 </row>
6754 <row>
6755 <entry><literal>smgr-md-write-start</literal></entry>
6756 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</literal></entry>
6757 <entry>Probe that fires when beginning to write a block to a relation.
6758 arg0 and arg1 contain the fork and block numbers of the page.
6759 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6760 identifying the relation.
6761 arg5 is the ID of the backend which created the temporary relation for a
6762 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared buffer.</entry>
6763 </row>
6764 <row>
6765 <entry><literal>smgr-md-write-done</literal></entry>
6766 <entry><literal>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</literal></entry>
6767 <entry>Probe that fires when a block write is complete.
6768 arg0 and arg1 contain the fork and block numbers of the page.
6769 arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
6770 identifying the relation.
6771 arg5 is the ID of the backend which created the temporary relation for a
6772 local buffer, or <symbol>InvalidBackendId</symbol> (-1) for a shared buffer.
6773 arg6 is the number of bytes actually written, while arg7 is the number
6774 requested (if these are different it indicates trouble).</entry>
6775 </row>
6776 <row>
6777 <entry><literal>sort-start</literal></entry>
6778 <entry><literal>(int, bool, int, int, bool, int)</literal></entry>
6779 <entry>Probe that fires when a sort operation is started.
6780 arg0 indicates heap, index or datum sort.
6781 arg1 is true for unique-value enforcement.
6782 arg2 is the number of key columns.
6783 arg3 is the number of kilobytes of work memory allowed.
6784 arg4 is true if random access to the sort result is required.
6785 arg5 indicates serial when <literal>0</literal>, parallel worker when
6786 <literal>1</literal>, or parallel leader when <literal>2</literal>.</entry>
6787 </row>
6788 <row>
6789 <entry><literal>sort-done</literal></entry>
6790 <entry><literal>(bool, long)</literal></entry>
6791 <entry>Probe that fires when a sort is complete.
6792 arg0 is true for external sort, false for internal sort.
6793 arg1 is the number of disk blocks used for an external sort,
6794 or kilobytes of memory used for an internal sort.</entry>
6795 </row>
6796 <row>
6797 <entry><literal>lwlock-acquire</literal></entry>
6798 <entry><literal>(char *, LWLockMode)</literal></entry>
6799 <entry>Probe that fires when an LWLock has been acquired.
6800 arg0 is the LWLock's tranche.
6801 arg1 is the requested lock mode, either exclusive or shared.</entry>
6802 </row>
6803 <row>
6804 <entry><literal>lwlock-release</literal></entry>
6805 <entry><literal>(char *)</literal></entry>
6806 <entry>Probe that fires when an LWLock has been released (but note
6807 that any released waiters have not yet been awakened).
6808 arg0 is the LWLock's tranche.</entry>
6809 </row>
6810 <row>
6811 <entry><literal>lwlock-wait-start</literal></entry>
6812 <entry><literal>(char *, LWLockMode)</literal></entry>
6813 <entry>Probe that fires when an LWLock was not immediately available and
6814 a server process has begun to wait for the lock to become available.
6815 arg0 is the LWLock's tranche.
6816 arg1 is the requested lock mode, either exclusive or shared.</entry>
6817 </row>
6818 <row>
6819 <entry><literal>lwlock-wait-done</literal></entry>
6820 <entry><literal>(char *, LWLockMode)</literal></entry>
6821 <entry>Probe that fires when a server process has been released from its
6822 wait for an LWLock (it does not actually have the lock yet).
6823 arg0 is the LWLock's tranche.
6824 arg1 is the requested lock mode, either exclusive or shared.</entry>
6825 </row>
6826 <row>
6827 <entry><literal>lwlock-condacquire</literal></entry>
6828 <entry><literal>(char *, LWLockMode)</literal></entry>
6829 <entry>Probe that fires when an LWLock was successfully acquired when the
6830 caller specified no waiting.
6831 arg0 is the LWLock's tranche.
6832 arg1 is the requested lock mode, either exclusive or shared.</entry>
6833 </row>
6834 <row>
6835 <entry><literal>lwlock-condacquire-fail</literal></entry>
6836 <entry><literal>(char *, LWLockMode)</literal></entry>
6837 <entry>Probe that fires when an LWLock was not successfully acquired when
6838 the caller specified no waiting.
6839 arg0 is the LWLock's tranche.
6840 arg1 is the requested lock mode, either exclusive or shared.</entry>
6841 </row>
6842 <row>
6843 <entry><literal>lock-wait-start</literal></entry>
6844 <entry><literal>(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</literal></entry>
6845 <entry>Probe that fires when a request for a heavyweight lock (lmgr lock)
6846 has begun to wait because the lock is not available.
6847 arg0 through arg3 are the tag fields identifying the object being
6848 locked. arg4 indicates the type of object being locked.
6849 arg5 indicates the lock type being requested.</entry>
6850 </row>
6851 <row>
6852 <entry><literal>lock-wait-done</literal></entry>
6853 <entry><literal>(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</literal></entry>
6854 <entry>Probe that fires when a request for a heavyweight lock (lmgr lock)
6855 has finished waiting (i.e., has acquired the lock).
6856 The arguments are the same as for <literal>lock-wait-start</literal>.</entry>
6857 </row>
6858 <row>
6859 <entry><literal>deadlock-found</literal></entry>
6860 <entry><literal>()</literal></entry>
6861 <entry>Probe that fires when a deadlock is found by the deadlock
6862 detector.</entry>
6863 </row>
6865 </tbody>
6866 </tgroup>
6867 </table>
6869 <table id="typedefs-table">
6870 <title>Defined Types Used in Probe Parameters</title>
6871 <tgroup cols="2">
6872 <thead>
6873 <row>
6874 <entry>Type</entry>
6875 <entry>Definition</entry>
6876 </row>
6877 </thead>
6879 <tbody>
6881 <row>
6882 <entry><type>LocalTransactionId</type></entry>
6883 <entry><type>unsigned int</type></entry>
6884 </row>
6885 <row>
6886 <entry><type>LWLockMode</type></entry>
6887 <entry><type>int</type></entry>
6888 </row>
6889 <row>
6890 <entry><type>LOCKMODE</type></entry>
6891 <entry><type>int</type></entry>
6892 </row>
6893 <row>
6894 <entry><type>BlockNumber</type></entry>
6895 <entry><type>unsigned int</type></entry>
6896 </row>
6897 <row>
6898 <entry><type>Oid</type></entry>
6899 <entry><type>unsigned int</type></entry>
6900 </row>
6901 <row>
6902 <entry><type>ForkNumber</type></entry>
6903 <entry><type>int</type></entry>
6904 </row>
6905 <row>
6906 <entry><type>bool</type></entry>
6907 <entry><type>unsigned char</type></entry>
6908 </row>
6910 </tbody>
6911 </tgroup>
6912 </table>
6915 </sect2>
6917 <sect2 id="using-trace-points">
6918 <title>Using Probes</title>
6920 <para>
6921 The example below shows a DTrace script for analyzing transaction
6922 counts in the system, as an alternative to snapshotting
6923 <structname>pg_stat_database</structname> before and after a performance test:
6924 <programlisting>
6925 #!/usr/sbin/dtrace -qs
6927 postgresql$1:::transaction-start
6929 @start["Start"] = count();
6930 self->ts = timestamp;
6933 postgresql$1:::transaction-abort
6935 @abort["Abort"] = count();
6938 postgresql$1:::transaction-commit
6939 /self->ts/
6941 @commit["Commit"] = count();
6942 @time["Total time (ns)"] = sum(timestamp - self->ts);
6943 self->ts=0;
6945 </programlisting>
6946 When executed, the example D script gives output such as:
6947 <screen>
6948 # ./txn_count.d `pgrep -n postgres` or ./txn_count.d &lt;PID&gt;
6951 Start 71
6952 Commit 70
6953 Total time (ns) 2312105013
6954 </screen>
6955 </para>
6957 <note>
6958 <para>
6959 SystemTap uses a different notation for trace scripts than DTrace does,
6960 even though the underlying trace points are compatible. One point worth
6961 noting is that at this writing, SystemTap scripts must reference probe
6962 names using double underscores in place of hyphens. This is expected to
6963 be fixed in future SystemTap releases.
6964 </para>
6965 </note>
6967 <para>
6968 You should remember that DTrace scripts need to be carefully written and
6969 debugged, otherwise the trace information collected might
6970 be meaningless. In most cases where problems are found it is the
6971 instrumentation that is at fault, not the underlying system. When
6972 discussing information found using dynamic tracing, be sure to enclose
6973 the script used to allow that too to be checked and discussed.
6974 </para>
6975 </sect2>
6977 <sect2 id="defining-trace-points">
6978 <title>Defining New Probes</title>
6980 <para>
6981 New probes can be defined within the code wherever the developer
6982 desires, though this will require a recompilation. Below are the steps
6983 for inserting new probes:
6984 </para>
6986 <procedure>
6987 <step>
6988 <para>
6989 Decide on probe names and data to be made available through the probes
6990 </para>
6991 </step>
6993 <step>
6994 <para>
6995 Add the probe definitions to <filename>src/backend/utils/probes.d</filename>
6996 </para>
6997 </step>
6999 <step>
7000 <para>
7001 Include <filename>pg_trace.h</filename> if it is not already present in the
7002 module(s) containing the probe points, and insert
7003 <literal>TRACE_POSTGRESQL</literal> probe macros at the desired locations
7004 in the source code
7005 </para>
7006 </step>
7008 <step>
7009 <para>
7010 Recompile and verify that the new probes are available
7011 </para>
7012 </step>
7013 </procedure>
7015 <formalpara>
7016 <title>Example:</title>
7017 <para>
7018 Here is an example of how you would add a probe to trace all new
7019 transactions by transaction ID.
7020 </para>
7021 </formalpara>
7023 <procedure>
7024 <step>
7025 <para>
7026 Decide that the probe will be named <literal>transaction-start</literal> and
7027 requires a parameter of type <type>LocalTransactionId</type>
7028 </para>
7029 </step>
7031 <step>
7032 <para>
7033 Add the probe definition to <filename>src/backend/utils/probes.d</filename>:
7034 <programlisting>
7035 probe transaction__start(LocalTransactionId);
7036 </programlisting>
7037 Note the use of the double underline in the probe name. In a DTrace
7038 script using the probe, the double underline needs to be replaced with a
7039 hyphen, so <literal>transaction-start</literal> is the name to document for
7040 users.
7041 </para>
7042 </step>
7044 <step>
7045 <para>
7046 At compile time, <literal>transaction__start</literal> is converted to a macro
7047 called <literal>TRACE_POSTGRESQL_TRANSACTION_START</literal> (notice the
7048 underscores are single here), which is available by including
7049 <filename>pg_trace.h</filename>. Add the macro call to the appropriate location
7050 in the source code. In this case, it looks like the following:
7052 <programlisting>
7053 TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
7054 </programlisting>
7055 </para>
7056 </step>
7058 <step>
7059 <para>
7060 After recompiling and running the new binary, check that your newly added
7061 probe is available by executing the following DTrace command. You
7062 should see similar output:
7063 <screen>
7064 # dtrace -ln transaction-start
7065 ID PROVIDER MODULE FUNCTION NAME
7066 18705 postgresql49878 postgres StartTransactionCommand transaction-start
7067 18755 postgresql49877 postgres StartTransactionCommand transaction-start
7068 18805 postgresql49876 postgres StartTransactionCommand transaction-start
7069 18855 postgresql49875 postgres StartTransactionCommand transaction-start
7070 18986 postgresql49873 postgres StartTransactionCommand transaction-start
7071 </screen>
7072 </para>
7073 </step>
7074 </procedure>
7076 <para>
7077 There are a few things to be careful about when adding trace macros
7078 to the C code:
7080 <itemizedlist>
7081 <listitem>
7082 <para>
7083 You should take care that the data types specified for a probe's
7084 parameters match the data types of the variables used in the macro.
7085 Otherwise, you will get compilation errors.
7086 </para>
7087 </listitem>
7090 <listitem>
7091 <para>
7092 On most platforms, if <productname>PostgreSQL</productname> is
7093 built with <option>--enable-dtrace</option>, the arguments to a trace
7094 macro will be evaluated whenever control passes through the
7095 macro, <emphasis>even if no tracing is being done</emphasis>. This is
7096 usually not worth worrying about if you are just reporting the
7097 values of a few local variables. But beware of putting expensive
7098 function calls into the arguments. If you need to do that,
7099 consider protecting the macro with a check to see if the trace
7100 is actually enabled:
7102 <programlisting>
7103 if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
7104 TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
7105 </programlisting>
7107 Each trace macro has a corresponding <literal>ENABLED</literal> macro.
7108 </para>
7109 </listitem>
7110 </itemizedlist>
7112 </para>
7114 </sect2>
7116 </sect1>
7118 </chapter>