Add system view pg_wait_events

This new view, wrapped around a SRF, shows some information known about
wait events, as of:
- Name.
- Type (Activity, I/O, Extension, etc.).
- Description.

All the information retrieved comes from wait_event_names.txt, and the
description is the same as the documentation with filters applied to
remove any XML markups.  This view is useful when joined with
pg_stat_activity to get the description of a wait event reported.

Custom wait events for extensions are included in the view.

Original idea by Yves Colin.

Author: Bertrand Drouvot
Reviewed-by: Kyotaro Horiguchi, Masahiro Ikeda, Tom Lane, Michael
Paquier
Discussion: https://postgr.es/m/0e2ae164-dc89-03c3-cf7f-de86378053ac@gmail.com
This commit is contained in:
Michael Paquier 2023-08-20 15:35:02 +09:00
parent a2a6249cf1
commit 1e68e43d3f
19 changed files with 317 additions and 11 deletions

View File

@ -1103,7 +1103,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
&wait_event_types;
<para>
Here is an example of how wait events can be viewed:
Here are examples of how wait events can be viewed:
<programlisting>
SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event is NOT NULL;
@ -1112,6 +1112,18 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i
2540 | Lock | relation
6644 | LWLock | ProcArray
(2 rows)
</programlisting>
<programlisting>
SELECT a.pid, a.wait_event, w.description
FROM pg_stat_activity a JOIN
pg_wait_events w ON (a.wait_event_type = w.type AND
a.wait_event = w.name)
WHERE wait_event is NOT NULL and a.state = 'active';
-[ RECORD 1 ]------------------------------------------------------------------
pid | 686674
wait_event | WALInitSync
description | Waiting for a newly initialized WAL file to reach durable storage
</programlisting>
</para>

View File

@ -221,6 +221,11 @@
<entry>views</entry>
</row>
<row>
<entry><link linkend="view-pg-wait-events"><structname>pg_wait_events</structname></link></entry>
<entry>wait events</entry>
</row>
</tbody>
</tgroup>
</table>
@ -4825,4 +4830,63 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
</table>
</sect1>
<sect1 id="view-pg-wait-events">
<title><structname>pg_wait_events</structname></title>
<indexterm zone="view-pg-wait-events">
<primary>pg_wait_events</primary>
</indexterm>
<para>
The view <structname>pg_wait_events</structname> provides description about the
wait events.
</para>
<table>
<title><structname>pg_wait_events</structname> Columns</title>
<tgroup cols="1">
<thead>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
Column Type
</para>
<para>
Description
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>type</structfield> <type>text</type>
</para>
<para>
Wait event type
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>name</structfield> <type>text</type>
</para>
<para>
Wait event name
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>description</structfield> <type>text</type>
</para>
<para>
Wait event description
</para></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
</chapter>

View File

@ -134,7 +134,7 @@ storage/lmgr/lwlocknames.h: storage/lmgr/generate-lwlocknames.pl storage/lmgr/lw
$(MAKE) -C storage/lmgr lwlocknames.h lwlocknames.c
utils/activity/wait_event_types.h: utils/activity/generate-wait_event_types.pl utils/activity/wait_event_names.txt
$(MAKE) -C utils/activity wait_event_types.h pgstat_wait_event.c
$(MAKE) -C utils/activity wait_event_types.h pgstat_wait_event.c wait_event_funcs_data.c
# run this unconditionally to avoid needing to know its dependencies here:
submake-catalog-headers:
@ -311,6 +311,7 @@ maintainer-clean: distclean
storage/lmgr/lwlocknames.c \
storage/lmgr/lwlocknames.h \
utils/activity/pgstat_wait_event.c \
utils/activity/wait_event_funcs_data.c \
utils/activity/wait_event_types.h \
utils/adt/jsonpath_gram.c \
utils/adt/jsonpath_gram.h \

View File

@ -1342,3 +1342,6 @@ CREATE VIEW pg_stat_subscription_stats AS
ss.stats_reset
FROM pg_subscription as s,
pg_stat_get_subscription_stats(s.oid) as ss;
CREATE VIEW pg_wait_events AS
SELECT * FROM pg_get_wait_events();

View File

@ -1,2 +1,3 @@
/pgstat_wait_event.c
/wait_event_types.h
/wait_event_funcs_data.c

View File

@ -32,10 +32,14 @@ OBJS = \
pgstat_subscription.o \
pgstat_wal.o \
pgstat_xact.o \
wait_event.o
wait_event.o \
wait_event_funcs.o
include $(top_srcdir)/src/backend/common.mk
wait_event_funcs.o: wait_event_funcs_data.c
wait_event_funcs_data.c: wait_event_types.h
wait_event.o: pgstat_wait_event.c
pgstat_wait_event.c: wait_event_types.h
touch $@
@ -44,4 +48,4 @@ wait_event_types.h: $(top_srcdir)/src/backend/utils/activity/wait_event_names.tx
$(PERL) $(srcdir)/generate-wait_event_types.pl --code $<
maintainer-clean: clean
rm -f wait_event_types.h pgstat_wait_event.c
rm -f wait_event_types.h pgstat_wait_event.c wait_event_funcs_data.c

View File

@ -4,6 +4,7 @@
# Generate wait events support files from wait_event_names.txt:
# - wait_event_types.h (if --code is passed)
# - pgstat_wait_event.c (if --code is passed)
# - wait_event_funcs_data.c (if --code is passed)
# - wait_event_types.sgml (if --docs is passed)
#
# Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
@ -98,8 +99,10 @@ if ($gen_code)
# multiple times.
my $htmp = "$output_path/wait_event_types.h.tmp$$";
my $ctmp = "$output_path/pgstat_wait_event.c.tmp$$";
my $wctmp = "$output_path/wait_event_funcs_data.c.tmp$$";
open my $h, '>', $htmp or die "Could not open $htmp: $!";
open my $c, '>', $ctmp or die "Could not open $ctmp: $!";
open my $wc, '>', $wctmp or die "Could not open $wctmp: $!";
my $header_comment =
'/*-------------------------------------------------------------------------
@ -129,12 +132,14 @@ if ($gen_code)
printf $c $header_comment, 'pgstat_wait_event.c';
printf $wc $header_comment, 'wait_event_funcs_data.c';
# Generate the pgstat_wait_event.c and wait_event_types.h files
# uc() is being used to force the comparison to be case-insensitive.
foreach my $waitclass (sort { uc($a) cmp uc($b) } keys %hashwe)
{
# Don't generate .c and .h files for Extension, LWLock and
# Lock, these are handled independently.
# Don't generate the pgstat_wait_event.c and wait_event_types.h files
# for Extension, LWLock and Lock, these are handled independently.
next
if ( $waitclass eq 'WaitEventExtension'
|| $waitclass eq 'WaitEventLWLock'
@ -183,14 +188,57 @@ if ($gen_code)
printf $c "}\n\n";
}
# Generate wait_event_funcs_data.c, building the contents of a static
# C structure holding all the information about the wait events.
# uc() is being used to force the comparison to be case-insensitive,
# even though it is not required here.
foreach my $waitclass (sort { uc($a) cmp uc($b) } keys %hashwe)
{
my $last = $waitclass;
$last =~ s/^WaitEvent//;
foreach my $wev (@{ $hashwe{$waitclass} })
{
my $new_desc = substr $wev->[2], 1, -2;
# Escape single quotes.
$new_desc =~ s/'/\\'/g;
# Replace the "quote" markups by real ones.
$new_desc =~ s/<quote>(.*?)<\/quote>/\\"$1\\"/g;
# Remove SGML markups.
$new_desc =~ s/<.*?>(.*?)<.*?>/$1/g;
# Tweak contents about links <xref linkend="text"/>
# on GUCs,
while (my ($capture) =
$new_desc =~ m/<xref linkend="guc-(.*?)"\/>/g)
{
$capture =~ s/-/_/g;
$new_desc =~ s/<xref linkend="guc-.*?"\/>/$capture/g;
}
# Then remove any reference to
# "see <xref linkend="text"/>".
$new_desc =~ s/; see.*$//;
# Build one element of the C structure holding the
# wait event info, as of (type, name, description).
printf $wc "\t{\"%s\", \"%s\", \"%s\"},\n", $last, $wev->[1],
$new_desc;
}
}
printf $h "#endif /* WAIT_EVENT_TYPES_H */\n";
close $h;
close $c;
close $wc;
rename($htmp, "$output_path/wait_event_types.h")
|| die "rename: $htmp to $output_path/wait_event_types.h: $!";
rename($ctmp, "$output_path/pgstat_wait_event.c")
|| die "rename: $ctmp to $output_path/pgstat_wait_event.c: $!";
rename($wctmp, "$output_path/wait_event_funcs_data.c")
|| die "rename: $wctmp to $output_path/wait_event_funcs_data.c: $!";
}
# Generate the .sgml file.
elsif ($gen_docs)
@ -249,7 +297,7 @@ Usage: perl [--output <path>] [--code ] [ --sgml ] input_file
Options:
--outdir Output directory (default '.')
--code Generate wait_event_types.h and pgstat_wait_event.c.
--code Generate C and header files.
--sgml Generate wait_event_types.sgml.
generate-wait_event_types.pl generates the SGML documentation and code

View File

@ -23,6 +23,7 @@ backend_sources += files(
# seems nicer to not add that as an include path for the whole backend.
waitevent_sources = files(
'wait_event.c',
'wait_event_funcs.c',
)
wait_event = static_library('wait_event_names',

View File

@ -264,6 +264,46 @@ GetWaitEventExtensionIdentifier(uint16 eventId)
}
/*
* Returns a list of currently defined custom wait event names for extensions.
* The result is a palloc'd array, with the number of elements saved in
* *nwaitevents.
*/
char **
GetWaitEventExtensionNames(int *nwaitevents)
{
char **waiteventnames;
WaitEventExtensionEntryByName *hentry;
HASH_SEQ_STATUS hash_seq;
int index;
int els;
LWLockAcquire(WaitEventExtensionLock, LW_SHARED);
/* Now we can safely count the number of entries */
els = hash_get_num_entries(WaitEventExtensionHashByName);
/* Allocate enough space for all entries */
waiteventnames = palloc(els * sizeof(char *));
/* Now scan the hash table to copy the data */
hash_seq_init(&hash_seq, WaitEventExtensionHashByName);
index = 0;
while ((hentry = (WaitEventExtensionEntryByName *) hash_seq_search(&hash_seq)) != NULL)
{
waiteventnames[index] = pstrdup(hentry->wait_event_name);
index++;
}
LWLockRelease(WaitEventExtensionLock);
Assert(index == els);
*nwaitevents = index;
return waiteventnames;
}
/*
* Configure wait event reporting to report wait events to *wait_event_info.
* *wait_event_info needs to be valid until pgstat_reset_wait_event_storage()

View File

@ -0,0 +1,93 @@
/*------------------------------------------------------------------------
*
* wait_event_funcs.c
* Functions for accessing wait event data.
*
* Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
*
* IDENTIFICATION
* src/backend/utils/activity/wait_event_funcs.c
*
*------------------------------------------------------------------------
*/
#include "postgres.h"
#include "funcapi.h"
#include "utils/builtins.h"
#include "utils/wait_event.h"
/*
* Each wait event has one corresponding entry in this structure, fed to
* the SQL function of this file.
*/
static const struct
{
const char *type;
const char *name;
const char *description;
}
waitEventData[] =
{
#include "wait_event_funcs_data.c"
/* end of list */
{NULL, NULL, NULL}
};
/*
* pg_get_wait_events
*
* List information about wait events (type, name and description).
*/
Datum
pg_get_wait_events(PG_FUNCTION_ARGS)
{
#define PG_GET_WAIT_EVENTS_COLS 3
ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo;
char **waiteventnames;
int nbextwaitevents;
/* Build tuplestore to hold the result rows */
InitMaterializedSRF(fcinfo, 0);
/* Iterate over the list of wait events */
for (int idx = 0; waitEventData[idx].type != NULL; idx++)
{
Datum values[PG_GET_WAIT_EVENTS_COLS] = {0};
bool nulls[PG_GET_WAIT_EVENTS_COLS] = {0};
values[0] = CStringGetTextDatum(waitEventData[idx].type);
values[1] = CStringGetTextDatum(waitEventData[idx].name);
values[2] = CStringGetTextDatum(waitEventData[idx].description);
tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc, values, nulls);
}
/* Handle custom wait events for extensions */
waiteventnames = GetWaitEventExtensionNames(&nbextwaitevents);
for (int idx = 0; idx < nbextwaitevents; idx++)
{
StringInfoData buf;
Datum values[PG_GET_WAIT_EVENTS_COLS] = {0};
bool nulls[PG_GET_WAIT_EVENTS_COLS] = {0};
values[0] = CStringGetTextDatum("Extension");
values[1] = CStringGetTextDatum(waiteventnames[idx]);
initStringInfo(&buf);
appendStringInfo(&buf,
"Waiting for custom wait event \"%s\" defined by extension module",
waiteventnames[idx]);
values[2] = CStringGetTextDatum(buf.data);
tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc, values, nulls);
}
return (Datum) 0;
}

View File

@ -5417,6 +5417,12 @@
proargmodes => '{i,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o,o}',
proargnames => '{pid,datid,pid,usesysid,application_name,state,query,wait_event_type,wait_event,xact_start,query_start,backend_start,state_change,client_addr,client_hostname,client_port,backend_xid,backend_xmin,backend_type,ssl,sslversion,sslcipher,sslbits,ssl_client_dn,ssl_client_serial,ssl_issuer_dn,gss_auth,gss_princ,gss_enc,gss_delegation,leader_pid,query_id}',
prosrc => 'pg_stat_get_activity' },
{ oid => '8403', descr => 'describe wait events',
proname => 'pg_get_wait_events', procost => '10', prorows => '250',
proretset => 't', provolatile => 'v', prorettype => 'record',
proargtypes => '', proallargtypes => '{text,text,text}',
proargmodes => '{o,o,o}', proargnames => '{type,name,description}',
prosrc => 'pg_get_wait_events' },
{ oid => '3318',
descr => 'statistics: information about progress of backends running maintenance command',
proname => 'pg_stat_get_progress_info', prorows => '100', proretset => 't',

View File

@ -1,6 +1,6 @@
# Copyright (c) 2022-2023, PostgreSQL Global Development Group
wait_event_output = ['wait_event_types.h', 'pgstat_wait_event.c']
wait_event_output = ['wait_event_types.h', 'pgstat_wait_event.c', 'wait_event_funcs_data.c']
wait_event_target = custom_target('wait_event_names',
input: files('../../backend/utils/activity/wait_event_names.txt'),
output: wait_event_output,
@ -11,7 +11,7 @@ wait_event_target = custom_target('wait_event_names',
],
build_by_default: true,
install: true,
install_dir: [dir_include_server / 'utils', false],
install_dir: [dir_include_server / 'utils', false, false],
)
wait_event_types_h = wait_event_target[0]

View File

@ -63,6 +63,7 @@ extern void WaitEventExtensionShmemInit(void);
extern Size WaitEventExtensionShmemSize(void);
extern uint32 WaitEventExtensionNew(const char *wait_event_name);
extern char **GetWaitEventExtensionNames(int *nwaitevents);
/* ----------
* pgstat_report_wait_start() -

View File

@ -47,6 +47,12 @@ $result = $node->poll_query_until(
is($result, 1,
'dynamic bgworker has reported "worker_spi_main" as wait event');
# Check the wait event used by the dynamic bgworker appears in pg_wait_events
$result = $node->safe_psql('postgres',
q[SELECT count(*) > 0 from pg_wait_events where type = 'Extension' and name = 'worker_spi_main';]
);
is($result, 't', '"worker_spi_main" is reported in pg_wait_events');
note "testing bgworkers loaded with shared_preload_libraries";
# Create the database first so as the workers can connect to it when

View File

@ -2631,6 +2631,10 @@ pg_views| SELECT n.nspname AS schemaname,
FROM (pg_class c
LEFT JOIN pg_namespace n ON ((n.oid = c.relnamespace)))
WHERE (c.relkind = 'v'::"char");
pg_wait_events| SELECT type,
name,
description
FROM pg_get_wait_events() pg_get_wait_events(type, name, description);
SELECT tablename, rulename, definition FROM pg_rules
WHERE schemaname = 'pg_catalog'
ORDER BY tablename, rulename;

View File

@ -134,6 +134,22 @@ select name, setting from pg_settings where name like 'enable%';
enable_tidscan | on
(21 rows)
-- There are always wait event descriptions for various types.
select type, count(*) > 0 as ok FROM pg_wait_events
group by type order by type COLLATE "C";
type | ok
-----------+----
Activity | t
BufferPin | t
Client | t
Extension | t
IO | t
IPC | t
LWLock | t
Lock | t
Timeout | t
(9 rows)
-- Test that the pg_timezone_names and pg_timezone_abbrevs views are
-- more-or-less working. We can't test their contents in any great detail
-- without the outputs changing anytime IANA updates the underlying data,

View File

@ -55,6 +55,10 @@ select count(*) = 0 as ok from pg_stat_wal_receiver;
-- a regression test run.
select name, setting from pg_settings where name like 'enable%';
-- There are always wait event descriptions for various types.
select type, count(*) > 0 as ok FROM pg_wait_events
group by type order by type COLLATE "C";
-- Test that the pg_timezone_names and pg_timezone_abbrevs views are
-- more-or-less working. We can't test their contents in any great detail
-- without the outputs changing anytime IANA updates the underlying data,

View File

@ -588,7 +588,8 @@ sub GenerateFiles
'src/include/utils/wait_event_types.h',
'src/backend/utils/activity/wait_event_names.txt'))
{
print "Generating pgstat_wait_event.c and wait_event_types.h...\n";
print
"Generating pgstat_wait_event.c, wait_event_types.h and wait_event_funcs_data.c...\n";
my $activ = 'src/backend/utils/activity';
system(
"perl $activ/generate-wait_event_types.pl --outdir $activ --code $activ/wait_event_names.txt"

View File

@ -55,6 +55,7 @@ if exist src\include\catalog\header-stamp del /q src\include\catalog\header-stam
if exist doc\src\sgml\version.sgml del /q doc\src\sgml\version.sgml
if %DIST%==1 if exist src\backend\utils\activity\pgstat_wait_event.c del /q src\backend\utils\activity\pgstat_wait_event.c
if %DIST%==1 if exist src\backend\utils\activity\wait_event_funcs_data.c del /q src\backend\utils\activity\wait_event_funcs_data.c
if %DIST%==1 if exist src\backend\utils\activity\wait_event_types.h del /q src\backend\utils\activity\wait_event_types.h
if %DIST%==1 if exist src\backend\utils\fmgroids.h del /q src\backend\utils\fmgroids.h
if %DIST%==1 if exist src\backend\utils\fmgrprotos.h del /q src\backend\utils\fmgrprotos.h