Postgres Pro
Downloads
Home   >   mailing lists

Thread: few more wait events to add to docs

few more wait events to add to docs

From
Jeremy Schneider
Date:
It's possible I'm misreading this, but I'm thinking that commits cc5f8136 and ab9e0e71 added a few tranches which we need to add to the docs.

session_dsa, session_record_table, session_typmod_table, and shared_tuplestore

https://www.postgresql.org/docs/current/monitoring-stats.html#WAIT-EVENT-TABLE

-Jeremy

-- 
Jeremy Schneider
Database Engineer
Amazon Web Services

Re: few more wait events to add to docs

From
Alvaro Herrera
Date:
On 2019-Mar-05, Jeremy Schneider wrote:

> It's possible I'm misreading this, but I'm thinking that commits
> cc5f8136 and ab9e0e71 added a few tranches which we need to add to the docs.
> 
> session_dsa, session_record_table, session_typmod_table, and
> shared_tuplestore
> 
> https://www.postgresql.org/docs/current/monitoring-stats.html#WAIT-EVENT-TABLE

https://postgr.es/m/CAB7nPqSU1=-3fQVZ+ncgm5VmRO4LSzjgQSmoYgwiZs2HvpyKBA@mail.gmail.com
:-)

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: few more wait events to add to docs

From
Thomas Munro
Date:
On Wed, Mar 6, 2019 at 2:18 PM Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
> On 2019-Mar-05, Jeremy Schneider wrote:
> > It's possible I'm misreading this, but I'm thinking that commits
> > cc5f8136 and ab9e0e71 added a few tranches which we need to add to the docs.
> >
> > session_dsa, session_record_table, session_typmod_table, and
> > shared_tuplestore
> >
> > https://www.postgresql.org/docs/current/monitoring-stats.html#WAIT-EVENT-TABLE
>
> https://postgr.es/m/CAB7nPqSU1=-3fQVZ+ncgm5VmRO4LSzjgQSmoYgwiZs2HvpyKBA@mail.gmail.com

Here's some missing documentation.

Hmm, yeah.  I wish these were alphabetised, I wish there was an
automated warning about this, I wish these tranches were declared a
better way that by adding code in RegisterLWLockTranches().

-- 
Thomas Munro
https://enterprisedb.com
Attachment

Re: few more wait events to add to docs

From
Michael Paquier
Date:
On Wed, Mar 06, 2019 at 02:21:15PM +1300, Thomas Munro wrote:
> Here's some missing documentation.

The addition looks fine to me.

> Hmm, yeah.  I wish these were alphabetised, I wish there was an
> automated warning about this, I wish these tranches were declared a
> better way that by adding code in RegisterLWLockTranches().

Why not using this occasion to reorganize the LWLock and Lock sections
so as their entries are fully alphabetized then?  I have made an
effort in this direction in 5ef037c for all the sections except these
two.  And honestly getting all these organized would really help
documentation readers.
--
Michael
Attachment

Re: few more wait events to add to docs

From
Jeremy Schneider
Date:
On 3/5/19 18:49, Michael Paquier wrote:
Why not using this occasion to reorganize the LWLock and Lock sections
so as their entries are fully alphabetized then?  I have made an
effort in this direction in 5ef037c for all the sections except these
two.  And honestly getting all these organized would really help
documentation readers.

Right now, the LWLock documentation implicitly follows a predictable pattern, so it's not really that hard to check for completeness.  I'm not sure to what extent you want to alphabetize, but I think the current structure isn't bad:

LWLock order in documentation:
1) CamelCase LWLocks: individually named - see lwlocknames.txt
2) lowercase LWLocks: tranches
2a) SLRUs - see SimpleLruInit() callers on doxygen
2b) Shared Buffer (buffer_content, buffer_io)
2c) Individually Named - see RegisterLWLockTranches() in lwlock.c

[see attached screenshot image... spoiler alert, it'll be a slide in my talk at PgConf NY]

If anything, I think we might just want to add comments to RegisterLWLockTranches() and lwlocknames.txt with links to the doc file that needs to be updated whenever a new tranche is added.

Not sure the best place for a comment on SLRUs (is SimpleLruInit a good place?)... but I'm kindof hopeful that we're not adding many more new SLRUs anyway and that people would bias toward leveraging the buffer cache when possible.

I'd rather make this pattern explicit in the docs than lose it... it greatly helps me understand what some particular wait event is, and where I need to look in the code to find it.

-Jeremy

-- 
Jeremy Schneider
Database Engineer
Amazon Web Services
Attachment

Re: few more wait events to add to docs

From
Michael Paquier
Date:
On Wed, Mar 06, 2019 at 11:08:12AM -0800, Jeremy Schneider wrote:
> LWLock order in documentation:
> 1) CamelCase LWLocks: individually named - see lwlocknames.txt
> 2) lowercase LWLocks: tranches
> 2a) SLRUs - see SimpleLruInit() callers on doxygen
> 2b) Shared Buffer (buffer_content, buffer_io)
> 2c) Individually Named - see RegisterLWLockTranches() in lwlock.c

Hm, OK.  Perhaps I lack some user insight on the matter.  Thanks for
the feedback!  Still there are some areas where we could make the
micro-ordering better.  For example replication_slot_io and buffer_io
are I/O specific still they get in the middle of the page, still we
want buffer_content close by.

One thing that I think we could do is reorganize at least
alphabetically the section for "Lock".  Each item does not really rely
on others.  What do you think?

> If anything, I think we might just want to add comments to
> RegisterLWLockTranches() and lwlocknames.txt with links to the doc file
> that needs to be updated whenever a new tranche is added.

Yes, that would surely help.

> Not sure the best place for a comment on SLRUs (is SimpleLruInit a good
> place?)... but I'm kindof hopeful that we're not adding many more new
> SLRUs anyway and that people would bias toward leveraging the buffer
> cache when possible.

A reference at the top of SimpleLruInit() sounds good to me.
--
Michael
Attachment

Re: few more wait events to add to docs

From
Michael Paquier
Date:
On Thu, Mar 07, 2019 at 11:25:10AM +0900, Michael Paquier wrote:
> On Wed, Mar 06, 2019 at 11:08:12AM -0800, Jeremy Schneider wrote:
>> If anything, I think we might just want to add comments to
>> RegisterLWLockTranches() and lwlocknames.txt with links to the doc file
>> that needs to be updated whenever a new tranche is added.
>
> Yes, that would surely help.
>
>> Not sure the best place for a comment on SLRUs (is SimpleLruInit a good
>> place?)... but I'm kindof hopeful that we're not adding many more new
>> SLRUs anyway and that people would bias toward leveraging the buffer
>> cache when possible.
>
> A reference at the top of SimpleLruInit() sounds good to me.

Thinking more about that, a comment at the top of SimpleLruInit() and
RegisterLWLockTranches() are both good things.

So please find attached a patch which does the following things to
address this thread:
- Reorder the list of events in the Lock section in alphabetical order
(not LWLock!).
- Add the missing event entries, which is what Thomas has provided.
- Add more documentation to mention the doc updates.

Thoughts?
--
Michael
Attachment