Re: Explain buffers display units.

On Mon, Feb 15, 2010 at 7:58 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>>>  To me, buffers seem like discrete (and unitless)
>>> entities, and we handle them that way elsewhere in the system (see,
>>> e.g. pg_stat_database, pg_statio_all_tables).  I don't know that it's
>>> a good idea to display that same information here in a different
>>> format.
>
> This seems like an important point that you need to respond to.  Why
> should we print out this information in kB here when we display it as
> raw numbers elsewhere?  I can't see any reason at all.

I did respond to it. The whole point is that the text output is for a
human to read. It should be printed in human-readable units. Not some
arbitrary internal unit of accounting that they then have to do
arithmetic on to make sense of.

We do *not* display raw block numbers anywhere else. Generally I think
we should have a policy of outputing human-readable standard units of
memory whenever displaying a memory quantity. Actually I thought we
already had that policy, hence things like:

postgres=# show shared_buffers;
shared_buffers
----------------
28MB
(1 row)

postgres=# show checkpoint_timeout;
checkpoint_timeout
--------------------
5min
(1 row)

The other examples you name are all internal or machine-readable
fomats which have to be formatted somehow using sql queries or tools
if you want to inspect the values directly. The user is free to format
the output of the pg_stat* functions using pg_size_pretty() though
it's annoying that it's not in the same base unit that
pg_relation_size() outputs. but these are the only interface to these
internal counters so there's no way to know if they're being used for
human-readable output or for gathering raw data for statistics or
other purposes.

>>> I definitely do not want to do anything that loses accuracy.  This is
>>> probably accurate enough for most uses, but it's still not as accurate
>>> as just printing the raw numbers.
>>
>> I left the XML/JSON output in terms of blocks on the theory that tools
>> reading this data can look up the block size and convert all it wants.
>
> I think this is a really terrible idea.  You've got a lot of very
> specific formatting code in explain.c which anyone who wants to use
> the JSON and XML output will very possibly need to reimplement.  I
> have worked really hard to keep the text format in sync with all the
> others, and up until now they have been.

You're assuming the JSON and XML program is planning to display the
measurements? They might not be. They might be gathering them for
charting or for alerts or all kinds of other things. Even if they do
plan to output them they'll want to format it in way that makes sense
for the context it's used in which might include more or fewer digits
or plug into some widget which requires raw values and does the
formatting automatically.

Whereas the human-readable format should display values in a form
humans can parse, the machine-readable output should include the raw
measurements with enough information for the tool to make sense of it.
Probably the XML schema should include the units as an attribute for
each tag so tools don't have to hard-code knowledge about what unit
each tag is in.

--
greg