Horton

Thread

Commits

  1. doc: Re-order Table 28.2 "Collected Statistics Views"

  2. doc: Re-order Table 28.35 "Per-Backend Statistics Functions"

  3. doc: Re-order Table 28.12 "Wait Events of type LWLock"

  4. doc: Re-order sections of "28.4. Progress Reporting"

  1. [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-08-01T23:40:26Z

    Hi Hackers.

I noticed that there are quite a few items in Chapter 28.2 "The
Cumulative Statistics System" [1] which have no obvious order.

e.g.

- The views (28.2.3 -> 28.2.23) don't seem to be in any order that I
could work out. Why not alphabetical?

- [2] Table 2.1 "Dynamic Statistics View" views are not in alphabetical order?

- [2] Table 2.2 "Collected Statistics View" views are not in alphabetical order?

- [3] Table 28.34 "Additional Statistics Functions" the
'pg_stat_clear_snapshot' is the only one not in order?

- [3] Table 28.35 "Per-Backend Statistics Functions" the
'pg_stat_get_backend_idset' is the only one not in order?

~~

So it doesn't seem as readable as it could be. If other people think
the same, I can write a patch for it.

Thoughts?

------
[1] https://www.postgresql.org/docs/devel/monitoring-stats.html
[2] https://www.postgresql.org/docs/devel/monitoring-stats.html#MONITORING-STATS-VIEWS
[3] https://www.postgresql.org/docs/devel/monitoring-stats.html#MONITORING-STATS-FUNCTIONS

Kind Regards,
Peter Smith.
Fujitsu Australia.

  2. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-08-30T00:19:56Z

    On Tue, Aug 2, 2022 at 9:40 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> Hi Hackers.
>
> I noticed that there are quite a few items in Chapter 28.2 "The
> Cumulative Statistics System" [1] which have no obvious order.
>
> e.g.
>
> - The views (28.2.3 -> 28.2.23) don't seem to be in any order that I
> could work out. Why not alphabetical?
>
> - [2] Table 2.1 "Dynamic Statistics View" views are not in alphabetical order?
>
> - [2] Table 2.2 "Collected Statistics View" views are not in alphabetical order?
>
> - [3] Table 28.34 "Additional Statistics Functions" the
> 'pg_stat_clear_snapshot' is the only one not in order?
>
> - [3] Table 28.35 "Per-Backend Statistics Functions" the
> 'pg_stat_get_backend_idset' is the only one not in order?
>
> ~~
>
> So it doesn't seem as readable as it could be. If other people think
> the same, I can write a patch for it.
>

I received no feedback when I reported this about a month ago, so I
went ahead and made patches to fix the problem anyway.

PSA. Note that no content was harmed in the making of these patches -
I only moved things around to be ordered.

IMO these docs look better now.

Thoughts?

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  3. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-10-06T05:07:52Z

    A rebase was needed.

PSA v2*.

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  4. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-10-24T01:51:26Z

    A rebase was needed.

PSA v3*.

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  5. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-10-24T01:53:16Z

    Sorry, I forgot the attachments in the previous post. PSA.

On Mon, Oct 24, 2022 at 12:51 PM Peter Smith <smithpb2250@gmail.com> wrote:
>
> A rebase was needed.
>
> PSA v3*.
>
> ------
> Kind Regards,
> Peter Smith.
> Fujitsu Australia

  6. Re: [DOCS] Stats views and functions not in order?

    Tom Lane <tgl@sss.pgh.pa.us> — 2022-11-06T18:50:32Z

    Peter Smith <smithpb2250@gmail.com> writes:
> Sorry, I forgot the attachments in the previous post. PSA.

I spent a bit of time looking at this.  I agree that a lot of the
current ordering choices here look like they were made with the
advice of a dartboard, and there's a number of things that are
pretty blatantly just sloppy merging (like the out-of-order
wait-event items).  However, I'm not a big fan of "alphabetical
order at all costs", because that frequently leads to ordering
decisions that are not a lot better than random from a semantic
standpoint.  For example, I resist the idea that it's sensible
to put pg_stat_all_indexes before pg_stat_all_tables.
I'm unconvinced that putting pg_stat_sys_tables and
pg_stat_user_tables far away from pg_stat_all_tables is great,
either.

So ... how do we proceed?

One thing I'm unhappy about that you didn't address is that
the subsection ordering in "28.4. Progress Reporting" could
hardly have been invented even with a dartboard.  Perhaps it
reflects development order, but that's a poor excuse.
I'd be inclined to alphabetize by SQL command name, but maybe
leave Base Backup to the end since it's not a SQL command.

			regards, tom lane

  7. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-11-08T00:18:36Z

    On Mon, Nov 7, 2022 at 5:50 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Peter Smith <smithpb2250@gmail.com> writes:
> > Sorry, I forgot the attachments in the previous post. PSA.
>
> I spent a bit of time looking at this.  I agree that a lot of the
> current ordering choices here look like they were made with the
> advice of a dartboard, and there's a number of things that are
> pretty blatantly just sloppy merging (like the out-of-order
> wait-event items).  However, I'm not a big fan of "alphabetical
> order at all costs", because that frequently leads to ordering
> decisions that are not a lot better than random from a semantic
> standpoint.  For example, I resist the idea that it's sensible
> to put pg_stat_all_indexes before pg_stat_all_tables.
> I'm unconvinced that putting pg_stat_sys_tables and
> pg_stat_user_tables far away from pg_stat_all_tables is great,
> either.
>

Thanks for taking the time to look at my patch. The "at all costs"
approach was not the intention - I was just trying only to apply some
sane ordering where I did not recognize a reason for the current
order.

> So ... how do we proceed?
>

To proceed with the existing patches I need some guidance on exactly
which of the changes can be considered improvements versus which ones
are maybe just trading one 'random' order for another.

How about below?

Table 28.1. Dynamic Statistics Views -- Alphabetical order would be a
small improvement here, right?

Table 28.2. Collected Statistics Views -- Leave this one unchanged
(per your comments above).

Table 28.12 Wait Events of type LWLock -- Seems a clear case of bad
merging. Alphabetical order is surely needed here, right?

Table 28.34 Additional Statistic Functions -- Alphabetical order would
be a small improvement here, right?

Table 28.35 Per-Backend Statistics Functions --  Alphabetical order
would be a small improvement here, right?

> One thing I'm unhappy about that you didn't address is that
> the subsection ordering in "28.4. Progress Reporting" could
> hardly have been invented even with a dartboard.  Perhaps it
> reflects development order, but that's a poor excuse.
> I'd be inclined to alphabetize by SQL command name, but maybe
> leave Base Backup to the end since it's not a SQL command.
>

Yes, I had previously only looked at the content of section 28.2
because I didn't want to get carried away by changing too much until
there was some support for doing the first part.

Now PSA a separate patch for fixing section "28.4. Progress Reporting"
order as suggested.

-----
Kind Regards,
Peter Smith.
Fujitsu Australia.

  8. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-11-09T23:03:42Z

    On Mon, Nov 7, 2022 at 5:19 PM Peter Smith <smithpb2250@gmail.com> wrote:

> On Mon, Nov 7, 2022 at 5:50 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >
> > Peter Smith <smithpb2250@gmail.com> writes:
> > > Sorry, I forgot the attachments in the previous post. PSA.
> >
> > I spent a bit of time looking at this.  I agree that a lot of the
> > current ordering choices here look like they were made with the
> > advice of a dartboard, and there's a number of things that are
> > pretty blatantly just sloppy merging (like the out-of-order
> > wait-event items).  However, I'm not a big fan of "alphabetical
> > order at all costs", because that frequently leads to ordering
> > decisions that are not a lot better than random from a semantic
> > standpoint.  For example, I resist the idea that it's sensible
> > to put pg_stat_all_indexes before pg_stat_all_tables.
> > I'm unconvinced that putting pg_stat_sys_tables and
> > pg_stat_user_tables far away from pg_stat_all_tables is great,
> > either.
> >
>
> Thanks for taking the time to look at my patch. The "at all costs"
> approach was not the intention - I was just trying only to apply some
> sane ordering where I did not recognize a reason for the current
> order.
>
> > So ... how do we proceed?
> >
>
> To proceed with the existing patches I need some guidance on exactly
> which of the changes can be considered improvements versus which ones
> are maybe just trading one 'random' order for another.
>
> How about below?
>
> Table 28.1. Dynamic Statistics Views -- Alphabetical order would be a
> small improvement here, right?
>

The present ordering seems mostly OK, though just like the "Progress"
update below the bottom 6 pg_stat_progress_* entries should be
alphabetized; but leaving them as a group at the end seems desirable.

Move pg_stat_recovery_prefetch either after subscription or after activity
- the replication/received/subscription stuff all seems like it should be
grouped together.  As well as the security related ssl/gssapi.


> Table 28.2. Collected Statistics Views -- Leave this one unchanged
> (per your comments above).
>

I would suggest moving the 3 pg_statio_*_tables rows between the
pg_stat_*_tables and the pg_stat_xact_*_tables groups.

Everything pertaining to cluster, database, tables, indexes, functions.
slru and replication slots should likewise shift to the (near) top in the
cluster/database grouping.


> Table 28.12 Wait Events of type LWLock -- Seems a clear case of bad
> merging. Alphabetical order is surely needed here, right?
>

+1 Agreed.

>
> Table 28.34 Additional Statistic Functions -- Alphabetical order would
> be a small improvement here, right?
>

No.  All "reset" items should be grouped at the end like they are.  I don't
see an alternative ordering among them that is clearly superior.  Same for
the first four.


>
> Table 28.35 Per-Backend Statistics Functions --  Alphabetical order
> would be a small improvement here, right?
>
>
This one I would rearrange alphabetically.  Or, at least, I have a
different opinion of what would make a decent order but it doesn't seem all
that clearly better than alphabetical.


> > I'd be inclined to alphabetize by SQL command name, but maybe
> > leave Base Backup to the end since it's not a SQL command.
> >
>
> Yes, I had previously only looked at the content of section 28.2
> because I didn't want to get carried away by changing too much until
> there was some support for doing the first part.
>
> Now PSA a separate patch for fixing section "28.4. Progress Reporting"
> order as suggested.
>
>
This seems like a clear win.

David J.

  9. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-11-16T01:38:56Z

    On Thu, Nov 10, 2022 at 10:04 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
...
>> > So ... how do we proceed?
>> >
>>
>> To proceed with the existing patches I need some guidance on exactly
>> which of the changes can be considered improvements versus which ones
>> are maybe just trading one 'random' order for another.
>>
>> How about below?
>>
>> Table 28.1. Dynamic Statistics Views -- Alphabetical order would be a
>> small improvement here, right?
>
>
> The present ordering seems mostly OK, though just like the "Progress" update below the bottom 6 pg_stat_progress_* entries should be alphabetized; but leaving them as a group at the end seems desirable.
>
> Move pg_stat_recovery_prefetch either after subscription or after activity - the replication/received/subscription stuff all seems like it should be grouped together.  As well as the security related ssl/gssapi.
>
>>
>> Table 28.2. Collected Statistics Views -- Leave this one unchanged
>> (per your comments above).
>
>
> I would suggest moving the 3 pg_statio_*_tables rows between the pg_stat_*_tables and the pg_stat_xact_*_tables groups.
>
> Everything pertaining to cluster, database, tables, indexes, functions.  slru and replication slots should likewise shift to the (near) top in the cluster/database grouping.
>
>>
>> Table 28.12 Wait Events of type LWLock -- Seems a clear case of bad
>> merging. Alphabetical order is surely needed here, right?
>
>
> +1 Agreed.
>>
>>
>> Table 28.34 Additional Statistic Functions -- Alphabetical order would
>> be a small improvement here, right?
>
>
> No.  All "reset" items should be grouped at the end like they are.  I don't see an alternative ordering among them that is clearly superior.  Same for the first four.
>
>>
>>
>> Table 28.35 Per-Backend Statistics Functions --  Alphabetical order
>> would be a small improvement here, right?
>>
>
> This one I would rearrange alphabetically.  Or, at least, I have a different opinion of what would make a decent order but it doesn't seem all that clearly better than alphabetical.
>
>>
>> > I'd be inclined to alphabetize by SQL command name, but maybe
>> > leave Base Backup to the end since it's not a SQL command.
>> >
>>
>> Yes, I had previously only looked at the content of section 28.2
>> because I didn't want to get carried away by changing too much until
>> there was some support for doing the first part.
>>
>> Now PSA a separate patch for fixing section "28.4. Progress Reporting"
>> order as suggested.
>>
>
> This seems like a clear win.
>
> David J.

Thanks for the review and table ordering advice. AFAICT I have made
all the changes according to the suggestions.

Each re-ordering was done as a separate patch (so maybe they can be
pushed separately, in case some but not all are OK). PSA.

~~

I was also wondering (but have not yet done) if the content *outside*
the tables should be reordered to match the table 28.1/28.2 order.

e.g. Currently it is not quite the same:

CURRENT
28.2.3. pg_stat_activity
28.2.4. pg_stat_replication
28.2.5. pg_stat_replication_slots
28.2.6. pg_stat_wal_receiver
28.2.7. pg_stat_recovery_prefetch
28.2.8. pg_stat_subscription
28.2.9. pg_stat_subscription_stats
28.2.10. pg_stat_ssl
28.2.11. pg_stat_gssapi

28.2.12. pg_stat_archiver
28.2.13. pg_stat_bgwriter
28.2.14. pg_stat_wal
28.2.15. pg_stat_database
28.2.16. pg_stat_database_conflicts
28.2.17. pg_stat_all_tables
28.2.18. pg_stat_all_indexes
28.2.19. pg_statio_all_tables
28.2.20. pg_statio_all_indexes
28.2.21. pg_statio_all_sequences
28.2.22. pg_stat_user_functions
28.2.23. pg_stat_slru

SUGGESTED
28.2.3. pg_stat_activity
28.2.4. pg_stat_replication
28.2.6. pg_stat_wal_receiver
28.2.7. pg_stat_recovery_prefetch
28.2.8. pg_stat_subscription
28.2.10. pg_stat_ssl
28.2.11. pg_stat_gssapi

28.2.12. pg_stat_archiver
28.2.13. pg_stat_bgwriter
28.2.14. pg_stat_wal
28.2.15. pg_stat_database
28.2.16. pg_stat_database_conflicts
28.2.23. pg_stat_slru
28.2.5. pg_stat_replication_slots
28.2.17. pg_stat_all_tables
28.2.18. pg_stat_all_indexes
28.2.19. pg_statio_all_tables
28.2.20. pg_statio_all_indexes
28.2.21. pg_statio_all_sequences
28.2.22. pg_stat_user_functions
28.2.9. pg_stat_subscription_stats

Thoughts?

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  10. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-11-16T21:46:41Z

    On Tue, Nov 15, 2022 at 6:39 PM Peter Smith <smithpb2250@gmail.com> wrote:

>
> I was also wondering (but have not yet done) if the content *outside*
> the tables should be reordered to match the table 28.1/28.2 order.
>
> Thoughts?
>
>
I would love to do away with the ToC listing of view names in 28.2
altogether.

Also, make it so each view ends up being its own separate page.

The name of the views in the table should then be the hyperlinks to those
pages.

Basically the way Chapter 54.1 works.  Though the interplay between the top
Chapter 54 and 54.1 is a bit repetitive.

https://www.postgresql.org/docs/current/views.html

I wonder whether having the table be structured but the ToC be purely
alphabetical would be considered a good idea...

The tables need hyperlinks regardless.  I wouldn't insist on changing the
ordering to match the table, especially with the hyperlinks, but I also
wouldn't reject it.  Figuring out how to make them one-per-page would be
time better spent though.

David J.

  11. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-11-23T08:36:31Z

    On Thu, Nov 17, 2022 at 8:46 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Tue, Nov 15, 2022 at 6:39 PM Peter Smith <smithpb2250@gmail.com> wrote:
>>
>>
>> I was also wondering (but have not yet done) if the content *outside*
>> the tables should be reordered to match the table 28.1/28.2 order.
>>
>> Thoughts?
>>

Thanks for the feedback/suggestions

>
> I would love to do away with the ToC listing of view names in 28.2 altogether.
>

OK, done. See patch 0006. To prevent all the views sections from
participating in the ToC I simply changed them to <sect3> instead of
<sect2>. I’m not 100% sure if this was a brilliant modification or a
total hack, but it does do exactly what you wanted.

> Also, make it so each view ends up being its own separate page.
>

I did not do this. AFAIK those views of chapter 54 get rendered to
separate pages only because they are top-level <sect1>. So I do not
know how to put all these stats views onto different pages without
radically changing the document structure. Anyway – doing this would
be incompatible with my <sect3> changes of patch 0006 (see above).


> The name of the views in the table should then be the hyperlinks to those pages.
>

OK done. See patch 0005. All the view names (in column one of the
tables) are hyperlinked to the views the same way as Chapter 54 does.
The tables are a lot cleaner now. A couple of inconsistent view ids
were also corrected.

> Basically the way Chapter 54.1 works.  Though the interplay between the top Chapter 54 and 54.1 is a bit repetitive.
>
> https://www.postgresql.org/docs/current/views.html
>
> I wonder whether having the table be structured but the ToC be purely alphabetical would be considered a good idea...
>
> The tables need hyperlinks regardless.  I wouldn't insist on changing the ordering to match the table, especially with the hyperlinks, but I also wouldn't reject it.  Figuring out how to make them one-per-page would be time better spent though.
>

PSA new patches. Now there are 6 of them. If some of the earlier
patches are agreeable can those ones please be committed? (because I
think this patch may be susceptible to needing a big rebase if
anything in those tables changes).

------
Kind Regards,
Peter Smith.
Fujitsu Australia.

  12. Re: [DOCS] Stats views and functions not in order?

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-11-25T12:09:09Z

    On 23.11.22 09:36, Peter Smith wrote:
> PSA new patches. Now there are 6 of them. If some of the earlier
> patches are agreeable can those ones please be committed? (because I
> think this patch may be susceptible to needing a big rebase if
> anything in those tables changes).

I have committed

v6-0001-Re-order-sections-of-28.4.-Progress-Reporting.patch
v6-0003-Re-order-Table-28.12-Wait-Events-of-type-LWLock.patch
v6-0004-Re-order-Table-28.35-Per-Backend-Statistics-Funct.patch

which seemed to have clear consensus.

v6-0002-Re-order-Table-28.2-Collected-Statistics-Views.patch

This one also seems ok, need a bit more time to look it over.

v6-0005-Cleanup-view-name-hyperlinks-for-Tables-28.1-and-.patch
v6-0006-Remove-all-stats-views-from-the-ToC-of-28.2.patch

I wasn't sure yet whether these had been reviewed yet, sine they were 
late additions to the patch series.

  13. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-11-25T15:10:43Z

    On Fri, Nov 25, 2022 at 5:09 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:

> On 23.11.22 09:36, Peter Smith wrote:
>

> v6-0005-Cleanup-view-name-hyperlinks-for-Tables-28.1-and-.patch
> v6-0006-Remove-all-stats-views-from-the-ToC-of-28.2.patch
>
> I wasn't sure yet whether these had been reviewed yet, sine they were
> late additions to the patch series.
>
>
They have not been reviewed.

If it's a matter of either-or I'd really prefer one page per grouping over
getting rid of the table-of-contents.  But I suspect there has to be some
way to add an sgml element to the markup to force a new page and would
prefer to confirm or refute that prior to committing 0006.

0005 seems a win either way though I haven't reviewed it yet.

David J.

  14. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-11-26T03:43:38Z

    On Wed, Nov 23, 2022 at 1:36 AM Peter Smith <smithpb2250@gmail.com> wrote:

> On Thu, Nov 17, 2022 at 8:46 AM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
>
> > Also, make it so each view ends up being its own separate page.
> >
>
> I did not do this. AFAIK those views of chapter 54 get rendered to
> separate pages only because they are top-level <sect1>. So I do not
> know how to put all these stats views onto different pages without
> radically changing the document structure. Anyway – doing this would
> be incompatible with my <sect3> changes of patch 0006 (see above).
>
>
I did some experimentation and reading on this today.  Short answer - turn
each view into a refentry under a dedicated sect2 where the table resides.

David J.

<chapter>
[...]
<sect1> <!--The Cumulative Statistics System -->
[...]
<sect2>
<title>Statistics Views</title>
 <para>Table of Statistics Views...</para>

 <refentry id="monitoring-pg-stat-activity-view">
 <refnamediv><refname>pg_stat_activity</refname><refpurpose>Purpose</refpurpose></refnamediv>
 <refsect1>
  <title><structname>pg_stat_activity</structname></title>

  <indexterm>
   <primary>pg_stat_activity</primary>
  </indexterm>

 </refsect1></refentry>

</sect2> <!-- Statistics Views -->

</sect1>
</chapter>

I was doing quite a bit of experimentation and basically gutted the actual
page to make that easier.  The end result looked basically like below.

Chapter 28. Monitoring Database Activity

Table of Contents

28.1. Standard Unix Tools
28.2. The Cumulative Statistics System

    28.2.1. Statistics Collection Configuration
    28.2.2. Viewing Statistics
    28.2.3. Statistics Views

A database administrator frequently wonders, “What is the system doing
right now?” This chapter discusses how to find that out.

Several tools are available for monitoring database activity and analyzing
performance. Most of this chapter is devoted to describing PostgreSQL's
cumulative statistics system, but one should not neglect regular Unix
monitoring programs such as ps, top, iostat, and vmstat. Also, once one has
identified a poorly-performing query, further investigation might be needed
using PostgreSQL's EXPLAIN command. Section 14.1 discusses EXPLAIN and
other methods for understanding the behavior of an individual query.

============== Page for 28.2 (sect1) ==============
28.2. The Cumulative Statistics System

28.2.1. Statistics Collection Configuration
28.2.2. Viewing Statistics
28.2.3. Statistics Views

PostgreSQL's cumulative statistics system supports collection and reporting
of information about server activity. Presently, accesses to tables and
indexes in both disk-block and individual-row terms are counted. The total
number of rows in each table, and information about vacuum and analyze
actions for each table are also counted. If enabled, calls to user-defined
functions and the total time spent in each one are counted as well.

PostgreSQL also supports reporting dynamic information about exactly what
is going on in the system right now, such as the exact command currently
being executed by other server processes, and which other connections exist
in the system. This facility is independent of the cumulative statistics
system.
28.2.1. Statistics Collection Configuration

Since collection of statistics adds some overhead to query execution, the
system can be configured to collect or not collect information. This is
controlled by configuration parameters that are normally set in
postgresql.conf. (See Chapter 20 for details about setting configuration
parameters.)

The parameter track_activities enables monitoring of the current command
being executed by any server process.

The parameter track_counts controls whether cumulative statistics are
collected about table and index accesses.

The parameter track_functions enables tracking of usage of user-defined
functions.

The parameter track_io_timing enables monitoring of block read and write
times.

The parameter track_wal_io_timing enables monitoring of WAL write times.

Normally these parameters are set in postgresql.conf so that they apply to
all server processes, but it is possible to turn them on or off in
individual sessions using the SET command. (To prevent ordinary users from
hiding their activity from the administrator, only superusers are allowed
to change these parameters with SET.)

Cumulative statistics are collected in shared memory. Every PostgreSQL
process collects statistics locally, then updates the shared data at
appropriate intervals. When a server, including a physical replica, shuts
down cleanly, a permanent copy of the statistics data is stored in the
pg_stat subdirectory, so that statistics can be retained across server
restarts. In contrast, when starting from an unclean shutdown (e.g., after
an immediate shutdown, a server crash, starting from a base backup, and
point-in-time recovery), all statistics counters are reset.
28.2.2. Viewing Statistics

test
28.2.3. Statistics Views

Table of Statistics Views...

===============
file:///usr/local/pgsql/share/doc/html/monitoring-pg-stat-activity-view.html
=============
(no ToC entry but the Next link in our footer does point to here)

pg_stat_activity

pg_stat_activity — Purpose
pg_stat_activity


The pg_stat_activity view will have one row per server process, showing
information related to the current activity of that process.

Here is an example of how wait events can be viewed:

SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE
wait_event is NOT NULL;
 pid  | wait_event_type | wait_event
------+-----------------+------------
 2540 | Lock            | relation
 6644 | LWLock          | ProcArray
(2 rows)

  15. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-11-28T00:07:02Z

    On Fri, Nov 25, 2022 at 11:09 PM Peter Eisentraut
<peter.eisentraut@enterprisedb.com> wrote:
>
> On 23.11.22 09:36, Peter Smith wrote:
> > PSA new patches. Now there are 6 of them. If some of the earlier
> > patches are agreeable can those ones please be committed? (because I
> > think this patch may be susceptible to needing a big rebase if
> > anything in those tables changes).
>
> I have committed
>
> v6-0001-Re-order-sections-of-28.4.-Progress-Reporting.patch
> v6-0003-Re-order-Table-28.12-Wait-Events-of-type-LWLock.patch
> v6-0004-Re-order-Table-28.35-Per-Backend-Statistics-Funct.patch
>
> which seemed to have clear consensus.
>
> v6-0002-Re-order-Table-28.2-Collected-Statistics-Views.patch
>
> This one also seems ok, need a bit more time to look it over.
>
> v6-0005-Cleanup-view-name-hyperlinks-for-Tables-28.1-and-.patch
> v6-0006-Remove-all-stats-views-from-the-ToC-of-28.2.patch
>
> I wasn't sure yet whether these had been reviewed yet, sine they were
> late additions to the patch series.

Thank you for pushing those ones.

PSA the remaining patches re-posted so cfbot can keep working

v6-0002 --> v7-0001
v6-0005 -> v7-0002
v6-0006 -> v7-0003

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  16. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-11-28T00:10:30Z

    On Sat, Nov 26, 2022 at 2:43 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Wed, Nov 23, 2022 at 1:36 AM Peter Smith <smithpb2250@gmail.com> wrote:
>>
>> On Thu, Nov 17, 2022 at 8:46 AM David G. Johnston
>> <david.g.johnston@gmail.com> wrote:
>>
>> > Also, make it so each view ends up being its own separate page.
>> >
>>
>> I did not do this. AFAIK those views of chapter 54 get rendered to
>> separate pages only because they are top-level <sect1>. So I do not
>> know how to put all these stats views onto different pages without
>> radically changing the document structure. Anyway – doing this would
>> be incompatible with my <sect3> changes of patch 0006 (see above).
>>
>
> I did some experimentation and reading on this today.  Short answer - turn each view into a refentry under a dedicated sect2 where the table resides.

Thanks very much for your suggestion.

I will look at redoing the v7-0003 patch using that approach when I
get some more time (maybe in a day or so),

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  17. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-11-29T07:29:48Z

    On Sat, Nov 26, 2022 at 2:43 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Wed, Nov 23, 2022 at 1:36 AM Peter Smith <smithpb2250@gmail.com> wrote:
>>
>> On Thu, Nov 17, 2022 at 8:46 AM David G. Johnston
>> <david.g.johnston@gmail.com> wrote:
>>
>> > Also, make it so each view ends up being its own separate page.
>> >
>>
>> I did not do this. AFAIK those views of chapter 54 get rendered to
>> separate pages only because they are top-level <sect1>. So I do not
>> know how to put all these stats views onto different pages without
>> radically changing the document structure. Anyway – doing this would
>> be incompatible with my <sect3> changes of patch 0006 (see above).
>>
>
> I did some experimentation and reading on this today.  Short answer - turn each view into a refentry under a dedicated sect2 where the table resides.
>
> David J.
>
> <chapter>
> [...]
> <sect1> <!--The Cumulative Statistics System -->
> [...]
> <sect2>
> <title>Statistics Views</title>
>  <para>Table of Statistics Views...</para>
>
>  <refentry id="monitoring-pg-stat-activity-view">
>  <refnamediv><refname>pg_stat_activity</refname><refpurpose>Purpose</refpurpose></refnamediv>
>  <refsect1>
>   <title><structname>pg_stat_activity</structname></title>
>
>   <indexterm>
>    <primary>pg_stat_activity</primary>
>   </indexterm>
>
>  </refsect1></refentry>
>
> </sect2> <!-- Statistics Views -->
>
> </sect1>
> </chapter>
>
> I was doing quite a bit of experimentation and basically gutted the actual page to make that easier.  The end result looked basically like below.
>
> Chapter 28. Monitoring Database Activity
>
> Table of Contents
>
> 28.1. Standard Unix Tools
> 28.2. The Cumulative Statistics System
>
>     28.2.1. Statistics Collection Configuration
>     28.2.2. Viewing Statistics
>     28.2.3. Statistics Views
>

PSA v8* patches.

Here, patches 0001 and 0002 are unchanged, but 0003 has many changes
per David's suggestion [1] to change all these views to <refentry>
blocks.

So, I've done pretty much the same as per the above advice, except:
- I just called the <refpurpose> text for all these views "View"
- I changed the <refsect1> <title> to be "Description". This renders
nicer (without the double text of the view name) and is also more in
keeping with the example I found here [2].

End result seems OK. YMMV.

~

Note that the refentry order within the monitoring.sgml is unchanged
from the previous <sect2> section order, so it's neither alphabetical
nor is it in the same order as within the tables. This is noticeable
only if you pay attention to the NEXT/PREV links at the bottom of the
browser page... so I'm not sure if it's worth shuffling these refentry
blocks into some better order or not?

------
[1] David's restructure suggestion
https://www.postgresql.org/message-id/CAKFQuwYkM5UZT%2B6tG%2BNgZvDcd5VavS%2BxNHsGsWC8jS-KJsxh7w%40mail.gmail.com
[2] Example of a refentry https://tdg.docbook.org/tdg/3.1/refentry.html

Kind Regards,
Peter Smith.
Fujitsu Australia

  18. Re: [DOCS] Stats views and functions not in order?

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-12-01T09:20:34Z

    On 29.11.22 08:29, Peter Smith wrote:
> PSA v8* patches.
> 
> Here, patches 0001 and 0002 are unchanged, but 0003 has many changes
> per David's suggestion [1] to change all these views to <refentry>
> blocks.

I don't understand what order 0001 is trying to achieve.  I know we 
didn't necessarily want to go fully alphabetic, but if we're going to 
spend time on this, let's come up with a system that the next 
contributor who adds a view will be able to understand and follow.

As an aside, I find the mixing of pg_stat_* and pg_statio_* views 
visually distracting.  It was easier to read before when they were in 
separate blocks.

I think something like this would be manageable:

<!-- everything related to global objects, alphabetically -->
pg_stat_archiver
pg_stat_bgwriter
pg_stat_database
pg_stat_database_conflicts
pg_stat_replication_slots
pg_stat_slru
pg_stat_subscription_stats
pg_stat_wal

<!-- all "stat" for schema objects, by "importance" -->
pg_stat_all_tables
pg_stat_sys_tables
pg_stat_user_tables
pg_stat_xact_all_tables
pg_stat_xact_sys_tables
pg_stat_xact_user_tables
pg_stat_all_indexes
pg_stat_sys_indexes
pg_stat_user_indexes
pg_stat_user_functions
pg_stat_xact_user_functions

<!-- all "statio" for schema objects, by "importance" -->
pg_statio_all_tables
pg_statio_sys_tables
pg_statio_user_tables
pg_statio_all_indexes
pg_statio_sys_indexes
pg_statio_user_indexes
pg_statio_all_sequences
pg_statio_sys_sequences
pg_statio_user_sequences


In any case, the remaining patches are new and need further review, so 
I'll move this to the next CF.

  19. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-12-01T14:35:15Z

    On Thu, Dec 1, 2022 at 2:20 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:

> On 29.11.22 08:29, Peter Smith wrote:
> > PSA v8* patches.
> >
> > Here, patches 0001 and 0002 are unchanged, but 0003 has many changes
> > per David's suggestion [1] to change all these views to <refentry>
> > blocks.
>
> I don't understand what order 0001 is trying to achieve.


The rule behind 0001 is:

All global object stats
All table object stats (stat > statio > xact; all > sys > user)
All index object stats
All sequence object stats
All function object stats


> As an aside, I find the mixing of pg_stat_* and pg_statio_* views
> visually distracting.  It was easier to read before when they were in
> separate blocks.
>

I found that having the statio at the end of each object type block added a
natural partitioning for tables and indexes that the existing order lacked
and that made reading the table be more "wall-of-text-ish", and thus more
difficult to read, than necessary.

I'm not opposed to the following though.  The object-type driven order just
feels more useful but I really cannot justify it beyond that.

I'm not particularly enamored with the existing single large table but
don't have a better structure to offer at this time.


> I think something like this would be manageable:
>
> <!-- everything related to global objects, alphabetically -->
> pg_stat_archiver
> pg_stat_bgwriter
> pg_stat_database
> pg_stat_database_conflicts
> pg_stat_replication_slots
> pg_stat_slru
> pg_stat_subscription_stats
> pg_stat_wal
>

WAL being adjacent to archiver/bgwriter seemed reasonable so I left that
alone.
Replication and Subscription being adjacent seemed reasonable so I left
that alone.
Thus slru ended up last, with database* remaining as-is.

At 8 items, with a group size average of 2, pure alphabetical is also
reasonable.


> <!-- all "stat" for schema objects, by "importance" -->
>
> <!-- all "statio" for schema objects, by "importance" -->
>
>
David J.

  20. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-12-07T01:36:05Z

    I'd like to "fix" this but IIUC there is no consensus yet about what
order is best for patch 0001, right?

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  21. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-12-07T02:57:30Z

    On Tue, Dec 6, 2022 at 6:36 PM Peter Smith <smithpb2250@gmail.com> wrote:

> I'd like to "fix" this but IIUC there is no consensus yet about what
> order is best for patch 0001, right?
>
>
I'm planning on performing a more thorough review of 0003 and 0004 tomorrow.

As for 0001 - go with Peter E.'s suggested ordering.

David J.

  22. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2022-12-07T16:26:12Z

    On Tue, Dec 6, 2022 at 7:57 PM David G. Johnston <david.g.johnston@gmail.com>
wrote:

> On Tue, Dec 6, 2022 at 6:36 PM Peter Smith <smithpb2250@gmail.com> wrote:
>
>> I'd like to "fix" this but IIUC there is no consensus yet about what
>> order is best for patch 0001, right?
>>
>>
> I'm planning on performing a more thorough review of 0003 and 0004
> tomorrow.
>
>
Compiled just fine.

I do think every row of the views table should be hyperlinked.  None of the
"xact" ones are for some reason.  For the sys/user ones just point to the
same place as the corresponding "all" link.

pg_stat_subscription_stats needs to be moved up to the "globals" section.

There are a bunch of trailing ". See" in the descriptions now that need to
be cleaned up. (0002)

David J.

  23. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2022-12-08T02:30:16Z

    Thanks for the ongoing feedback.

PSA patches for v9*

v9-0001 - Now the table rows are ordered per PeterE's suggestions [1]

v9-0002 - All the review comments from DavidJ [2] are addressed

v9-0003 - Unchanged since v8.

------
[1] https://www.postgresql.org/message-id/cfdb0030-8f62-ed6d-4246-8d9bf855bc48%40enterprisedb.com
[2] https://www.postgresql.org/message-id/CAKFQuwby7xWHek8%3D6UPaNXrhGA-i0B2zMOmBoGHgc4yaO8NH_w%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia.

  24. Re: [DOCS] Stats views and functions not in order?

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-01-02T08:17:28Z

    On 08.12.22 03:30, Peter Smith wrote:
> PSA patches for v9*
> 
> v9-0001 - Now the table rows are ordered per PeterE's suggestions [1]

committed

> v9-0002 - All the review comments from DavidJ [2] are addressed

I'm not sure about this one.  It removes the "see [link] for details" 
phrases and instead makes the view name a link.  I think this loses the 
cue that there is more information elsewhere.  Otherwise, one could 
think that, say, the entry about pg_stat_activity is the primary source 
and the link just links to itself.  Also keep in mind that people use 
media where links are not that apparent (PDF), so the presence of a link 
by itself cannot be the only cue about the flow of the information.

  25. Re: [DOCS] Stats views and functions not in order?

    vignesh C <vignesh21@gmail.com> — 2023-01-04T07:07:59Z

    On Mon, 2 Jan 2023 at 13:47, Peter Eisentraut
<peter.eisentraut@enterprisedb.com> wrote:
>
> On 08.12.22 03:30, Peter Smith wrote:
> > PSA patches for v9*
> >
> > v9-0001 - Now the table rows are ordered per PeterE's suggestions [1]
>
> committed
>
> > v9-0002 - All the review comments from DavidJ [2] are addressed
>
> I'm not sure about this one.  It removes the "see [link] for details"
> phrases and instead makes the view name a link.  I think this loses the
> cue that there is more information elsewhere.  Otherwise, one could
> think that, say, the entry about pg_stat_activity is the primary source
> and the link just links to itself.  Also keep in mind that people use
> media where links are not that apparent (PDF), so the presence of a link
> by itself cannot be the only cue about the flow of the information.

I'm not sure if anything is pending for v9-0003, if there is something
pending, please post an updated patch for the same.

Regards,
Vignesh

  26. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2023-01-11T06:11:38Z

    On Wed, Jan 4, 2023 at 6:08 PM vignesh C <vignesh21@gmail.com> wrote:
>
> On Mon, 2 Jan 2023 at 13:47, Peter Eisentraut
> <peter.eisentraut@enterprisedb.com> wrote:
> >
> > On 08.12.22 03:30, Peter Smith wrote:
> > > PSA patches for v9*
> > >
> > > v9-0001 - Now the table rows are ordered per PeterE's suggestions [1]
> >
> > committed

Thanks for pushing.

> >
> > > v9-0002 - All the review comments from DavidJ [2] are addressed
> >
> > I'm not sure about this one.  It removes the "see [link] for details"
> > phrases and instead makes the view name a link.  I think this loses the
> > cue that there is more information elsewhere.  Otherwise, one could
> > think that, say, the entry about pg_stat_activity is the primary source
> > and the link just links to itself.  Also keep in mind that people use
> > media where links are not that apparent (PDF), so the presence of a link
> > by itself cannot be the only cue about the flow of the information.
>

PSA new patch for v10-0001

v9-0001 --> pushed, thanks!
v9-0002 --> I removed this based on the reject reason above
v9-0003 --> v10-0001

> I'm not sure if anything is pending for v9-0003, if there is something
> pending, please post an updated patch for the same.
>

Thanks for the reminder. PSA v10.

------
Kind Regards,
Peter Smith.
Fujitsu Australia

  27. Re: [DOCS] Stats views and functions not in order?

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-01-18T10:36:18Z

    On 11.01.23 07:11, Peter Smith wrote:
> v9-0003 --> v10-0001
> 
>> I'm not sure if anything is pending for v9-0003, if there is something
>> pending, please post an updated patch for the same.
> 
> Thanks for the reminder. PSA v10.

So this patch changes some sections describing system views to 
refentry's.  What is the reason for that?  refentry's are basically man 
pages; do we want man pages for each system view?

Maybe (*), but then we should also do the same to all the other system 
views, all the system catalogs, everything else.  Just changing a few in 
a single place seems odd.

(*) -- but also maybe not?

  28. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2023-01-18T15:07:33Z

    On Wed, Jan 18, 2023 at 3:36 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:

> On 11.01.23 07:11, Peter Smith wrote:
> > v9-0003 --> v10-0001
> >
> >> I'm not sure if anything is pending for v9-0003, if there is something
> >> pending, please post an updated patch for the same.
> >
> > Thanks for the reminder. PSA v10.
>
> So this patch changes some sections describing system views to
> refentry's.  What is the reason for that?  refentry's are basically man
> pages; do we want man pages for each system view?
>

I didn't really consider the effect this might have on man pages.  I knew
it would produce the desired effect in the HTML and assumed it would
produce an acceptable effect in the PDF.  I was going for the html effect
of having these views chunked into their own pages, any other changes being
non-detrimental.  And inspecting the DocBook configurations learned that
sect1 and refentry had this effect.  Using sect1 is not possible in this
part of the documentation.


>
> Maybe (*), but then we should also do the same to all the other system
> views, all the system catalogs, everything else.  Just changing a few in
> a single place seems odd.
>
> (*) -- but also maybe not?
>
>
I could see those who use man pages being pleased with having access to
these core building blocks of the system at ready access.  I am not one of
those people, using the website exclusively.  If there is a champion of man
pages here that wants to ensure that changes in this area work well there
this patch would be better for it.

I really want a one-page-per-view output on the website in this section.
This is the only way I could see getting to that point (as noted upthread,
system catalogs don't have this problem because they are able to be
marked up as sect1) .  The existing side-effect is, for me, an acceptable
trade-off situation.  If you want to provide a statement for why these are
special, it's because they are in the System Monitoring chapter instead of
System Internals and the man pages don't cover system internals...

I'm not opposed to alternative markup that gets the pagination job done,
though it likely involves tool-chain configuration/modifications. There is
a nearby thread where this is being done presently so maybe if refentry is
a commit-blocker there is still hope, but it is presently outside my
capability.  I'm after the pagination and have no current preference as to
how it is technically accomplished.

David J.

  29. Re: [DOCS] Stats views and functions not in order?

    Tom Lane <tgl@sss.pgh.pa.us> — 2023-01-18T15:38:35Z

    "David G. Johnston" <david.g.johnston@gmail.com> writes:
> ...  I was going for the html effect
> of having these views chunked into their own pages, any other changes being
> non-detrimental.

But is that a result we want?  It will for example break any bookmarks
that people might have for these documentation entries.  It will also
pretty thoroughly break the cross-version navigation links in this
part of the docs.

Maybe the benefit is worth those costs, but I'm entirely not convinced
of that.  I think we need to tread pretty lightly when rearranging
longstanding documentation-layout decisions.

			regards, tom lane

  30. Re: [DOCS] Stats views and functions not in order?

    David G. Johnston <david.g.johnston@gmail.com> — 2023-01-18T15:55:28Z

    On Wed, Jan 18, 2023 at 8:38 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> > ...  I was going for the html effect
> > of having these views chunked into their own pages, any other changes
> being
> > non-detrimental.
>
> But is that a result we want?  It will for example break any bookmarks
> that people might have for these documentation entries.  It will also
> pretty thoroughly break the cross-version navigation links in this
> part of the docs.


> Maybe the benefit is worth those costs, but I'm entirely not convinced
> of that.  I think we need to tread pretty lightly when rearranging
> longstanding documentation-layout decisions.
>
>
Fair points.

The external linking can be solved with redirect rules, as I believe we've
done before, and fairly recently.  Even if not I think when they see why
the break happened they will be happy for the improved user experience.

I do think it is important enough a change to warrant breaking the
cross-version navigation links.  I can imagine a linking scheme that would
still work but I'm doubtful that this is important enough to expend the
development effort.

David J.

  31. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2023-01-18T23:45:35Z

    On Thu, Jan 19, 2023 at 2:55 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Wed, Jan 18, 2023 at 8:38 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>
>> "David G. Johnston" <david.g.johnston@gmail.com> writes:
>> > ...  I was going for the html effect
>> > of having these views chunked into their own pages, any other changes being
>> > non-detrimental.
>>
>> But is that a result we want?  It will for example break any bookmarks
>> that people might have for these documentation entries.  It will also
>> pretty thoroughly break the cross-version navigation links in this
>> part of the docs.
>>
>>
>> Maybe the benefit is worth those costs, but I'm entirely not convinced
>> of that.  I think we need to tread pretty lightly when rearranging
>> longstanding documentation-layout decisions.
>>
>

David already gave a good summary [1], but since I was the OP here is
the background of v10-0001 from my PoV.

~

The original $SUBJECT requirements evolved to also try to make each
view appear on a separate page after that was suggested by DavidJ [2].
I was unable to achieve per-page views "without radically changing the
document structure." [3], but DavidJ found a way [4] to do it using
refentry. I then wrote the patch v8-0003 using that strategy, which
after more rebasing became the v10-0001 you see today.

I did prefer the view-per-page results (although I also only use HTML
docs). But my worry is that there seem still to be a few unknowns
about how this might affect other (not the HTML) renderings of the
docs. If you think that risk is too great, or if you feel this patch
will cause unwarranted link/bookmark grief, then I am happy to just
drop it.

------
[1] DJ overview -
https://www.postgresql.org/message-id/CAKFQuwaVm%3D6d_sw9Wrp4cdSm5_k%3D8ZVx0--v2v4BH4KnJtqXqg%40mail.gmail.com
[2] DJ suggested view-per-page -
https://www.postgresql.org/message-id/CAKFQuwa9JtoCBVc6CJb7NC5FqMeEAy_A8X4H8t6kVaw7fz9LTw%40mail.gmail.com
[3] PS don't know how to do it -
https://www.postgresql.org/message-id/CAHut%2BPv5Efz1TLWOLSoFvoyC0mq%2Bs92yFSd534ctWSdjEFtKCw%40mail.gmail.com
[4] DJ how to do it using refentry -
https://www.postgresql.org/message-id/CAKFQuwYkM5UZT%2B6tG%2BNgZvDcd5VavS%2BxNHsGsWC8jS-KJsxh7w%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia

  32. Re: [DOCS] Stats views and functions not in order?

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-01-27T11:30:00Z

    On 19.01.23 00:45, Peter Smith wrote:
> The original $SUBJECT requirements evolved to also try to make each
> view appear on a separate page after that was suggested by DavidJ [2].
> I was unable to achieve per-page views "without radically changing the
> document structure." [3], but DavidJ found a way [4] to do it using
> refentry. I then wrote the patch v8-0003 using that strategy, which
> after more rebasing became the v10-0001 you see today.
> 
> I did prefer the view-per-page results (although I also only use HTML
> docs). But my worry is that there seem still to be a few unknowns
> about how this might affect other (not the HTML) renderings of the
> docs. If you think that risk is too great, or if you feel this patch
> will cause unwarranted link/bookmark grief, then I am happy to just
> drop it.

I'm wary of making semantic markup changes to achieve an ad-hoc 
presentation effects.  Sometimes it's necessary, but it should be 
considered carefully and globally.

We could change the chunking boundary to be sect2 globally.  This is 
easily configurable (chunk.section.depth).

Thinking about it now, maybe this is what we need.  As the documentation 
grows, as it clearly does, the depth of the structure increases and 
pages get longer.  This can also be seen in other chapters.

Of course, this would need to be tested and checked in more detail.

  33. Re: [DOCS] Stats views and functions not in order?

    Peter Smith <smithpb2250@gmail.com> — 2023-01-30T06:12:33Z

    On Fri, Jan 27, 2023 at 10:30 PM Peter Eisentraut
<peter.eisentraut@enterprisedb.com> wrote:
>
> On 19.01.23 00:45, Peter Smith wrote:
> > The original $SUBJECT requirements evolved to also try to make each
> > view appear on a separate page after that was suggested by DavidJ [2].
> > I was unable to achieve per-page views "without radically changing the
> > document structure." [3], but DavidJ found a way [4] to do it using
> > refentry. I then wrote the patch v8-0003 using that strategy, which
> > after more rebasing became the v10-0001 you see today.
> >
> > I did prefer the view-per-page results (although I also only use HTML
> > docs). But my worry is that there seem still to be a few unknowns
> > about how this might affect other (not the HTML) renderings of the
> > docs. If you think that risk is too great, or if you feel this patch
> > will cause unwarranted link/bookmark grief, then I am happy to just
> > drop it.
>
> I'm wary of making semantic markup changes to achieve an ad-hoc
> presentation effects.  Sometimes it's necessary, but it should be
> considered carefully and globally.
>
> We could change the chunking boundary to be sect2 globally.  This is
> easily configurable (chunk.section.depth).
>
> Thinking about it now, maybe this is what we need.  As the documentation
> grows, as it clearly does, the depth of the structure increases and
> pages get longer.  This can also be seen in other chapters.
>
> Of course, this would need to be tested and checked in more detail.
>

This chunk configuration idea sounds a better approach. If somebody
else wants to champion that change separately then I can maybe help to
review it.

Meanwhile, this pagination topic has strayed far away from the
original $SUBJECT, so I guess since there is nothing else pending this
thread's CF entry [1] can just be marked as "Committed" now?

------
[1] https://commitfest.postgresql.org/41/3904/

Kind Regards,
Peter Smith.
Fujitsu Australia

  34. Re: [DOCS] Stats views and functions not in order?

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2023-01-30T10:42:12Z

    On 30.01.23 07:12, Peter Smith wrote:
> Meanwhile, this pagination topic has strayed far away from the
> original $SUBJECT, so I guess since there is nothing else pending this
> thread's CF entry [1] can just be marked as "Committed" now?

done

  35. Re: [DOCS] Stats views and functions not in order?

    Alvaro Herrera <alvherre@alvh.no-ip.org> — 2023-02-01T09:26:34Z

    On 2023-Jan-30, Peter Smith wrote:

> On Fri, Jan 27, 2023 at 10:30 PM Peter Eisentraut
> <peter.eisentraut@enterprisedb.com> wrote:

> > We could change the chunking boundary to be sect2 globally.  This is
> > easily configurable (chunk.section.depth).

> > Thinking about it now, maybe this is what we need.  As the documentation
> > grows, as it clearly does, the depth of the structure increases and
> > pages get longer.  This can also be seen in other chapters.

> This chunk configuration idea sounds a better approach. If somebody
> else wants to champion that change separately then I can maybe help to
> review it.

Changing the chunking depth will change every single doc URL, though, so
the website will need some work to ensure there's a good transition
mechanism for the "this page in older/newer versions" functionality.

It sounds doable, but someone will need to craft it and test it.  (Maybe
it would work to populate a table with all URLs at each side of the
divide, and its equivalent at the other side.)

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/