Thread: wait event documentation
Right now, the information on wait events is organized into one giant table inside https://www.postgresql.org/docs/devel/static/monitoring-stats.html#monitoring-stats-views -- the wait event type is inserted into the lefthand column of the table using moreRows="...", which is awkward to maintain and has already provoked several fixup commits after people (including me) messed it up. And indeed it seems to be slightly messed up at the moment, too; the LWLock section needs moreRows++. Instead of continuing to repair this every time it gets broken, I propose that we break this into one table that lists all the wait_event_type values -- LWLock, Lock, BufferPin, Activity, Client, Extension, IPC, Timeout, and IO -- and then a second table for each type that has multiple wait events listing all of the wait events for that type. I also propose hoisting this out of section 28.2.3 - Viewing Statistics - and making it a new toplevel section of chapter 28. So between the current "28.3 Viewing Locks" and the current "28.4 Progress Reporting" we'd add a new section "Wait Events" and link to that from 28.2.3. That would also give us a place to include any general text that we want to have regarding wait events, apart from the tables. Thoughts? -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
From: pgsql-hackers-owner@postgresql.org
> [mailto:pgsql-hackers-owner@postgresql.org] On Behalf Of Robert Haas
> Instead of continuing to repair this every time it gets broken, I propose
> that we break this into one table that lists all the wait_event_type values
> -- LWLock, Lock, BufferPin, Activity, Client, Extension, IPC, Timeout, and
> IO -- and then a second table for each type that has multiple wait events
> listing all of the wait events for that type.
>
> I also propose hoisting this out of section 28.2.3 - Viewing Statistics
> - and making it a new toplevel section of chapter 28. So between the current
> "28.3 Viewing Locks" and the current "28.4 Progress Reporting" we'd add
> a new section "Wait Events" and link to that from 28.2.3. That would also
> give us a place to include any general text that we want to have regarding
> wait events, apart from the tables.
+1
I'm visually impaired and using screen reader software which reads text by Synthetic speech. It was not easy for me to
navigatea large table to find the first row of a particular wait event type. With your proposal, I'll be able to move
amongtables with a single key press ("T" and "Shift + T".) I'd also be happy about separating the section for wait
eventsas you propose, because navigating in a long section is cumbersome.
Regards
Takayuki Tsunakawa
On 2017/04/03 22:32, Robert Haas wrote: > Right now, the information on wait events is organized into one giant > table inside https://www.postgresql.org/docs/devel/static/monitoring-stats.html#monitoring-stats-views > -- the wait event type is inserted into the lefthand column of the > table using moreRows="...", which is awkward to maintain and has > already provoked several fixup commits after people (including me) > messed it up. And indeed it seems to be slightly messed up at the > moment, too; the LWLock section needs moreRows++. > > Instead of continuing to repair this every time it gets broken, I > propose that we break this into one table that lists all the > wait_event_type values -- LWLock, Lock, BufferPin, Activity, Client, > Extension, IPC, Timeout, and IO -- and then a second table for each > type that has multiple wait events listing all of the wait events for > that type. > > I also propose hoisting this out of section 28.2.3 - Viewing > Statistics - and making it a new toplevel section of chapter 28. So > between the current "28.3 Viewing Locks" and the current "28.4 > Progress Reporting" we'd add a new section "Wait Events" and link to > that from 28.2.3. That would also give us a place to include any > general text that we want to have regarding wait events, apart from > the tables. > > Thoughts? +1. By the way, wonder if it wouldn't make sense to take the whole Table 28.1. Dynamic Statistics Views into a new section (perhaps before 28.2 Viewing Locks or after), since those views display information different from what the statistics collector component collects and publishes (those in the Table 28.2. Collected Statistics Views). Thanks, Amit
On Mon, Apr 3, 2017 at 11:57 PM, Amit Langote <Langote_Amit_f8@lab.ntt.co.jp> wrote: > By the way, wonder if it wouldn't make sense to take the whole Table 28.1. > Dynamic Statistics Views into a new section (perhaps before 28.2 Viewing > Locks or after), since those views display information different from what > the statistics collector component collects and publishes (those in the > Table 28.2. Collected Statistics Views). It seems a little short for that, doesn't it? I mean, I'm not against it on principle, but we don't want to hoist a 5-line table into a section by itself. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
On Tue, Apr 4, 2017 at 9:05 PM, Robert Haas <robertmhaas@gmail.com> wrote: > On Mon, Apr 3, 2017 at 11:57 PM, Amit Langote > <Langote_Amit_f8@lab.ntt.co.jp> wrote: >> By the way, wonder if it wouldn't make sense to take the whole Table 28.1. >> Dynamic Statistics Views into a new section (perhaps before 28.2 Viewing >> Locks or after), since those views display information different from what >> the statistics collector component collects and publishes (those in the >> Table 28.2. Collected Statistics Views). > > It seems a little short for that, doesn't it? I mean, I'm not against > it on principle, but we don't want to hoist a 5-line table into a > section by itself. I was thinking that if we move Table 28.1 to a new section, Tables 28.3 (pg_stat_activity) to 28.8 (pg_stat_ssl) will go too. Thanks, Amit