pgstat documentation tables
Right now we have a single table on
http://www.postgresql.org/docs/devel/static/monitoring-stats.html#MONITORING-STATS-VIEWS
that lists all our statistics views. It makes for difficult to parse
descriptions like "One row only, showing cluster-wide statistics from
the background writer: number of scheduled checkpoints, requested
checkpoints, buffers written by checkpoints and cleaning scans, and
the number of times the background writer stopped a cleaning scan
because it had written too many buffers. Also includes statistics
about the shared buffer pool, including buffers written by backends
(that is, not by the background writer), how many times those backends
had to execute their own fsync calls (normally the background writer
handles those even when the backend does its own write), total buffers
allocated, and time of last statistics reset."
I'd like to turn that into one table for each view, with two columns,
one being the name the other one being the description. That'll also
make it possible to expand on the descriptions without making it
completley unreadable, should we want to.
Comments?Objections?
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On 01/15/2012 03:51 AM, Magnus Hagander wrote:
I'd like to turn that into one table for each view, with two columns,
one being the name the other one being the description. That'll also
make it possible to expand on the descriptions without making it
completley unreadable, should we want to.
Scott Mead's pg_stat_activity refactoring patch already was forced
toward doing something similar for its documentation to be readable
(maybe exactly the same as you were thinking, can't tell because my
SGML-fu is weak) . I feel doing this for every view in there is
inevitable, just a matter of when to bite on the problem. This whole
section is barely usable in its current form. I strongly hope the
pg_stat_activity patch goes in, which will be close to a compelling
event to motivate fixing the rest of them in a similar way. I would
advocate leading with that one until it seems right, then adopting the
same style of reorg to the rest until they're all converted.
--
Greg Smith 2ndQuadrant US greg@2ndQuadrant.com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.com
On Sun, Jan 15, 2012 at 10:35, Greg Smith <greg@2ndquadrant.com> wrote:
On 01/15/2012 03:51 AM, Magnus Hagander wrote:
I'd like to turn that into one table for each view, with two columns,
one being the name the other one being the description. That'll also
make it possible to expand on the descriptions without making it
completley unreadable, should we want to.Scott Mead's pg_stat_activity refactoring patch already was forced toward
doing something similar for its documentation to be readable (maybe exactly
the same as you were thinking, can't tell because my SGML-fu is weak) . I
feel doing this for every view in there is inevitable, just a matter of when
to bite on the problem. This whole section is barely usable in its current
form. I strongly hope the pg_stat_activity patch goes in, which will be
close to a compelling event to motivate fixing the rest of them in a similar
way. I would advocate leading with that one until it seems right, then
adopting the same style of reorg to the rest until they're all converted.
Yes, the pg_stat_activity patch will make it more important - but I
want to do it for *all* of them...
I'll be happy to do the mechanical work on turning them into table,
but yes, I was planning to look at the pg_stat_activity patch first
all along :)
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Magnus Hagander <magnus@hagander.net> writes:
Right now we have a single table on
http://www.postgresql.org/docs/devel/static/monitoring-stats.html#MONITORING-STATS-VIEWS
that lists all our statistics views ...
I'd like to turn that into one table for each view,
Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.
regards, tom lane
On 01/15/2012 12:20 PM, Tom Lane wrote:
Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.
Yes, that's a perfect precedent. I think the easiest path forward here
is to tweak the updated pg_stat_activity documentation, since that's
being refactoring first anyway. That can be reformatted until it looks
just like the system catalog documentation. And then once that's done,
the rest of them can be converted over to follow the same style. I'd be
willing to work on doing that in a way that improves what is documented,
too. The difficulty of working with the existing tables has been the
deterrent for improving that section to me.
--
Greg Smith 2ndQuadrant US greg@2ndQuadrant.com Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.com
Bruce had a patch to turn SGML descriptions of system view into comments
via some Perl program or something. He posted it many moons ago and I
haven't seen an updated version. Bruce, do you have something to say on
this topic?
--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support
On sön, 2012-01-15 at 12:20 -0500, Tom Lane wrote:
Magnus Hagander <magnus@hagander.net> writes:
Right now we have a single table on
http://www.postgresql.org/docs/devel/static/monitoring-stats.html#MONITORING-STATS-VIEWS
that lists all our statistics views ...
I'd like to turn that into one table for each view,Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.
If the tables had proper table and column comments, you might even be
able to generate the SGML documentation automatically.
On Mon, Jan 16, 2012 at 19:41, Peter Eisentraut <peter_e@gmx.net> wrote:
On sön, 2012-01-15 at 12:20 -0500, Tom Lane wrote:
Magnus Hagander <magnus@hagander.net> writes:
Right now we have a single table on
http://www.postgresql.org/docs/devel/static/monitoring-stats.html#MONITORING-STATS-VIEWS
that lists all our statistics views ...
I'd like to turn that into one table for each view,Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.If the tables had proper table and column comments, you might even be
able to generate the SGML documentation automatically.
Well, I'd expect some of those columns to get (at least over time)
significantly more detailed information than they have now. Certainly
more than you'd put in comments in the catalogs. And having some sort
of combination there seems to overcomplicate things...
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Mon, Jan 16, 2012 at 01:01:50PM -0300, Alvaro Herrera wrote:
Bruce had a patch to turn SGML descriptions of system view into comments
via some Perl program or something. He posted it many moons ago and I
haven't seen an updated version. Bruce, do you have something to say on
this topic?
Yes, I was waiting to get feedback on that but it seems the 9.2 release
slipped right by me on that. I guess I will try to pick it up for 9.3.
How do people feel about pulling text out of the SGML docs and loading
it into the database as table and column comments?
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
Bruce Momjian <bruce@momjian.us> writes:
How do people feel about pulling text out of the SGML docs and loading
it into the database as table and column comments?
I'm not thrilled by that proposal. The length limits on comments are
very much shorter than what is sensible to use in catalogs.sgml (at
least if you want the comments to look passable in \d displays). And
I don't want people trying to serve two different use-cases when they
write those.
Perhaps it'd work to pull column comments from the C header files
--- any same-line comment in catalog/pg_*.h is probably short enough to
serve this purpose usefully.regards, tom lane
On Feb 8, 2012 5:32 AM, "Tom Lane" <tgl@sss.pgh.pa.us> wrote:
Bruce Momjian <bruce@momjian.us> writes:
How do people feel about pulling text out of the SGML docs and loading
it into the database as table and column comments?I'm not thrilled by that proposal. The length limits on comments are
very much shorter than what is sensible to use in catalogs.sgml (at
least if you want the comments to look passable in \d displays). And
I don't want people trying to serve two different use-cases when they
write those.
Yes, I'd rather see longer than shorter descriptions in the docs, and this
would turn that backwards...
Perhaps it'd work to pull column comments from the C header files --- any same-line comment in catalog/pg_*.h is probably short enough to serve this purpose usefully.
That could work a lot better..
/Magnus
On Tue, Feb 07, 2012 at 11:29:12PM -0500, Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
How do people feel about pulling text out of the SGML docs and loading
it into the database as table and column comments?I'm not thrilled by that proposal. The length limits on comments are
very much shorter than what is sensible to use in catalogs.sgml (at
least if you want the comments to look passable in \d displays). And
I don't want people trying to serve two different use-cases when they
write those.
I was thinking of just grabbing the first X characters from the SGML
comments.
Perhaps it'd work to pull column comments from the C header files --- any same-line comment in catalog/pg_*.h is probably short enough to serve this purpose usefully.
Yes, that would be simpler.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
On Wed, Feb 8, 2012 at 17:13, Bruce Momjian <bruce@momjian.us> wrote:
On Tue, Feb 07, 2012 at 11:29:12PM -0500, Tom Lane wrote:
Bruce Momjian <bruce@momjian.us> writes:
How do people feel about pulling text out of the SGML docs and loading
it into the database as table and column comments?I'm not thrilled by that proposal. The length limits on comments are
very much shorter than what is sensible to use in catalogs.sgml (at
least if you want the comments to look passable in \d displays). And
I don't want people trying to serve two different use-cases when they
write those.I was thinking of just grabbing the first X characters from the SGML
comments.
So that it wouldn't necessarily even make for a complete sentence?
That seems like a really bad idea...
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Mon, Jan 16, 2012 at 02:03, Greg Smith <greg@2ndquadrant.com> wrote:
On 01/15/2012 12:20 PM, Tom Lane wrote:
Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.Yes, that's a perfect precedent. I think the easiest path forward here is
to tweak the updated pg_stat_activity documentation, since that's being
refactoring first anyway. That can be reformatted until it looks just like
the system catalog documentation. And then once that's done, the rest of
them can be converted over to follow the same style. I'd be willing to work
on doing that in a way that improves what is documented, too. The
difficulty of working with the existing tables has been the deterrent for
improving that section to me.
I've applied a patch that does this now. Hopefully, I didn't create
too many spelling errors or such :-)
I also applied a separate patch that folded the list of functions into
the list of views, since that's where they are called, as a way to
reduce duplicate documentation. I did it as a spearate patch to make
it easier to back out if people think that was a bad idea...
I didn't add any new documentation at this point - I wanted to get
this patch in before it starts conflicting with work others are
potentially doing. I also noticed there were some stats functions that
were undocumented - the view fields were listed, but not the functions
themselves. I haven't added those either...
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Sat, Feb 25, 2012 at 9:33 AM, Magnus Hagander <magnus@hagander.net> wrote:
On Mon, Jan 16, 2012 at 02:03, Greg Smith <greg@2ndquadrant.com> wrote:
On 01/15/2012 12:20 PM, Tom Lane wrote:
Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.Yes, that's a perfect precedent. I think the easiest path forward here is
to tweak the updated pg_stat_activity documentation, since that's being
refactoring first anyway. That can be reformatted until it looks just like
the system catalog documentation. And then once that's done, the rest of
them can be converted over to follow the same style. I'd be willing to work
on doing that in a way that improves what is documented, too. The
difficulty of working with the existing tables has been the deterrent for
improving that section to me.I've applied a patch that does this now. Hopefully, I didn't create
too many spelling errors or such :-)I also applied a separate patch that folded the list of functions into
the list of views, since that's where they are called, as a way to
reduce duplicate documentation. I did it as a spearate patch to make
it easier to back out if people think that was a bad idea...
I think it's a little awkward this way; maybe it would be better as a
separate table column. Or maybe it was better the way it was; I'm not
sure. Or maybe we could have a separate table that just gives the
equivalences between stats table-column pairs and functions. Of those
ideas, I think I like "separate table in the same column" the best.
Also, I wonder if we should promote section 27.2.2.1. Other Statistics
Functions to 27.2.3.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
On Mon, Feb 27, 2012 at 04:44, Robert Haas <robertmhaas@gmail.com> wrote:
On Sat, Feb 25, 2012 at 9:33 AM, Magnus Hagander <magnus@hagander.net> wrote:
On Mon, Jan 16, 2012 at 02:03, Greg Smith <greg@2ndquadrant.com> wrote:
On 01/15/2012 12:20 PM, Tom Lane wrote:
Please follow the style already used for system catalogs; ie I think
there should be a summary table with one entry per view, and then a
separate description and table-of-columns for each view.Yes, that's a perfect precedent. I think the easiest path forward here is
to tweak the updated pg_stat_activity documentation, since that's being
refactoring first anyway. That can be reformatted until it looks just like
the system catalog documentation. And then once that's done, the rest of
them can be converted over to follow the same style. I'd be willing to work
on doing that in a way that improves what is documented, too. The
difficulty of working with the existing tables has been the deterrent for
improving that section to me.I've applied a patch that does this now. Hopefully, I didn't create
too many spelling errors or such :-)I also applied a separate patch that folded the list of functions into
the list of views, since that's where they are called, as a way to
reduce duplicate documentation. I did it as a spearate patch to make
it easier to back out if people think that was a bad idea...I think it's a little awkward this way; maybe it would be better as a
separate table column. Or maybe it was better the way it was; I'm not
The problem with a separate column is that it makes the table very
wide (some of those functions have very long name). And it won't be
possible to get an auto-linebreak in the function names, because
they're too long.
sure. Or maybe we could have a separate table that just gives the
equivalences between stats table-column pairs and functions. Of those
ideas, I think I like "separate table in the same column" the best.
That one would at least work. You mean basically:
|pg_stat_database.xact_commit|pg_stat_get_db_xact_commit|
|pg_stat_database.xact_rollback|pg_stat_get_db_xact_rollback|
etc etc for each column/function, right?
Also, I wonder if we should promote section 27.2.2.1. Other Statistics
Functions to 27.2.3.
I was considering that, but given that 27.2.2 is "viewing statistics",
it does seem like a sub-section to that.. Though maybe if we make the
lis tof views into their own section *as well*, so we have one sectoin
for "how to view it", one for "views" and one for "other functions" it
would make more sense.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Mon, Feb 27, 2012 at 5:22 AM, Magnus Hagander <magnus@hagander.net> wrote:
The problem with a separate column is that it makes the table very
wide (some of those functions have very long name).
Yeah, that's one thing I don't like about what you actually did,
either - it made some of the tables much wider.
sure. Or maybe we could have a separate table that just gives the
equivalences between stats table-column pairs and functions. Of those
ideas, I think I like "separate table in the same column" the best.That one would at least work. You mean basically:
|pg_stat_database.xact_commit|pg_stat_get_db_xact_commit|
|pg_stat_database.xact_rollback|pg_stat_get_db_xact_rollback|etc etc for each column/function, right?
Yeah.
Also, I wonder if we should promote section 27.2.2.1. Other Statistics
Functions to 27.2.3.I was considering that, but given that 27.2.2 is "viewing statistics",
it does seem like a sub-section to that.. Though maybe if we make the
lis tof views into their own section *as well*, so we have one sectoin
for "how to view it", one for "views" and one for "other functions" it
would make more sense.
My thought was that a good half of those "other statistics functions"
don't have all that much to do with viewing anything, so the logical
argument for that section to need to be under "viewing statistics"
seems a bit weak.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
On Mon, Feb 27, 2012 at 14:36, Robert Haas <robertmhaas@gmail.com> wrote:
On Mon, Feb 27, 2012 at 5:22 AM, Magnus Hagander <magnus@hagander.net> wrote:
The problem with a separate column is that it makes the table very
wide (some of those functions have very long name).Yeah, that's one thing I don't like about what you actually did,
either - it made some of the tables much wider.
Uh, can you give me an example of one? While they will all become
wider if you actually need to, I don't see any of those tables as wide
enough to cause any trouble that automatic linebreaks don't fix?
sure. Or maybe we could have a separate table that just gives the
equivalences between stats table-column pairs and functions. Of those
ideas, I think I like "separate table in the same column" the best.That one would at least work. You mean basically:
|pg_stat_database.xact_commit|pg_stat_get_db_xact_commit|
|pg_stat_database.xact_rollback|pg_stat_get_db_xact_rollback|etc etc for each column/function, right?
Yeah.
Ok, I'll see if I can put something like that together and see what it
looks like. Unless somebody else objects to that way?
Also, I wonder if we should promote section 27.2.2.1. Other Statistics
Functions to 27.2.3.I was considering that, but given that 27.2.2 is "viewing statistics",
it does seem like a sub-section to that.. Though maybe if we make the
lis tof views into their own section *as well*, so we have one sectoin
for "how to view it", one for "views" and one for "other functions" it
would make more sense.My thought was that a good half of those "other statistics functions"
don't have all that much to do with viewing anything, so the logical
argument for that section to need to be under "viewing statistics"
seems a bit weak.
True.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
On Mon, Feb 27, 2012 at 11:32 AM, Magnus Hagander <magnus@hagander.net> wrote:
On Mon, Feb 27, 2012 at 14:36, Robert Haas <robertmhaas@gmail.com> wrote:
On Mon, Feb 27, 2012 at 5:22 AM, Magnus Hagander <magnus@hagander.net> wrote:
The problem with a separate column is that it makes the table very
wide (some of those functions have very long name).Yeah, that's one thing I don't like about what you actually did,
either - it made some of the tables much wider.Uh, can you give me an example of one? While they will all become
wider if you actually need to, I don't see any of those tables as wide
enough to cause any trouble that automatic linebreaks don't fix?
It's not so much that they become wide enough to line-wrap; it's just
that it's harder to read. For example, table 27-5,
pg_stat_database_conflicts view, is now about twice the width that it
was before, and the additional sentence is mostly junk, because 95% of
people reading this won't care a whit. Plus, for those who do care,
the phrasing of the sentence (this value can also be returned
directly...) isn't really altogether clear, at least IMHO.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
Robert Haas <robertmhaas@gmail.com> writes:
On Mon, Feb 27, 2012 at 11:32 AM, Magnus Hagander <magnus@hagander.net> wrote:
On Mon, Feb 27, 2012 at 14:36, Robert Haas <robertmhaas@gmail.com> wrote:
Yeah, that's one thing I don't like about what you actually did,
either - it made some of the tables much wider.
Uh, can you give me an example of one? While they will all become
wider if you actually need to, I don't see any of those tables as wide
enough to cause any trouble that automatic linebreaks don't fix?
It's not so much that they become wide enough to line-wrap; it's just
that it's harder to read.
Something else to keep in mind is that PDF-format docs are not terribly
forgiving of wide tables --- have you looked at what these look like in
PDF?
regards, tom lane
