Re: pgstat documentation tables

On Mon, Feb 27, 2012 at 04:44, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> On Sat, Feb 25, 2012 at 9:33 AM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>> On Mon, Jan 16, 2012 at 02:03, Greg Smith <greg(at)2ndquadrant(dot)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/