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

Author: michaelpq

doc/src/sgml/monitoring.sgml

@@ -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>
 

doc/src/sgml/system-views.sgml

@@ -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>

src/backend/Makefile

@@ -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 \

src/backend/catalog/system_views.sql

@@ -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();

src/backend/utils/activity/.gitignore

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

src/backend/utils/activity/Makefile

@@ -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

src/backend/utils/activity/generate-wait_event_types.pl

@@ -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 @@
 	# 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 @@
 
 	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 @@
 		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 @@ sub usage
 
 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

src/backend/utils/activity/meson.build

@@ -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',

src/backend/utils/activity/wait_event.c

@@ -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()