Thread: mxid_age() and age(xid) appear undocumented

mxid_age() and age(xid) appear undocumented

From
David Rowley
Date:
I see d692308cf494f6126 mentions mxid_age() in passing, but there
appears to be no formal definition of either of these functions.

Should there be?

-- 
 David Rowley                   http://www.2ndQuadrant.com/
 PostgreSQL Development, 24x7 Support, Training & Services


Re: mxid_age() and age(xid) appear undocumented

From
Robert Haas
Date:
On Sun, Jul 1, 2018 at 11:18 PM, David Rowley
<david.rowley@2ndquadrant.com> wrote:
> I see d692308cf494f6126 mentions mxid_age() in passing, but there
> appears to be no formal definition of either of these functions.
>
> Should there be?

It seems like a good idea to me.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company


Re: mxid_age() and age(xid) appear undocumented

From
Peter Geoghegan
Date:
On Thu, Jul 5, 2018 at 12:36 PM, Robert Haas <robertmhaas@gmail.com> wrote:
> On Sun, Jul 1, 2018 at 11:18 PM, David Rowley
> <david.rowley@2ndquadrant.com> wrote:
>> I see d692308cf494f6126 mentions mxid_age() in passing, but there
>> appears to be no formal definition of either of these functions.
>>
>> Should there be?
>
> It seems like a good idea to me.

+1


-- 
Peter Geoghegan


Re: mxid_age() and age(xid) appear undocumented

From
Bruce Momjian
Date:
On Thu, Jul  5, 2018 at 01:30:22PM -0700, Peter Geoghegan wrote:
> On Thu, Jul 5, 2018 at 12:36 PM, Robert Haas <robertmhaas@gmail.com> wrote:
> > On Sun, Jul 1, 2018 at 11:18 PM, David Rowley
> > <david.rowley@2ndquadrant.com> wrote:
> >> I see d692308cf494f6126 mentions mxid_age() in passing, but there
> >> appears to be no formal definition of either of these functions.
> >>
> >> Should there be?
> >
> > It seems like a good idea to me.
> 
> +1

I looked into this and all the 4-byte xid functions are marked as
deprecated for the 8-byte variants.  I don't think documenting 4-byte
mxid_age() and age(xid) makes sense anymore, and I don't see their value
enough to create 8-byte versions, so I just added C comments that they
were undocumented, in the attached patch.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

Attachment

Re: mxid_age() and age(xid) appear undocumented

From
Peter Geoghegan
Date:
On Mon, Nov 13, 2023 at 4:43 PM Bruce Momjian <bruce@momjian.us> wrote:
> I looked into this and all the 4-byte xid functions are marked as
> deprecated for the 8-byte variants.  I don't think documenting 4-byte
> mxid_age() and age(xid) makes sense anymore, and I don't see their value
> enough to create 8-byte versions, so I just added C comments that they
> were undocumented, in the attached patch.

I'm sympathetic to the goal of making 4 byte XIDs an on-disk
implementation detail that is all but completely hidden from users.
However, there are practical problems with taking that to its logical
extreme. At least right now.

These functions are in fact documented -- albeit only partially. There
are references to both in "Routine Vacuuming". Moreover, those
references are rather useful; they're the basis of many
monitoring/alerting queries. If anything, I'd recommend adding more
documentation for these two functions.

We also continue to show 32-bit XIDs (alongside 32-bit relfrozenxid)
in the output of VACUUM VERBOSE/autovacuum log messages. (Though that
issue can be fixed fairly easily.)

The bottom line is that there is only one way to figure out the age of
a table right now, and it involves 32-bit XIDs/MXIDs, and these two
functions. And, if we were to change something in this area, we'd
definitely need to provide for the needs of those monitoring queries I
mentioned.

--
Peter Geoghegan



Re: mxid_age() and age(xid) appear undocumented

From
Nikolay Samokhvalov
Date:
On Mon, Nov 13, 2023 at 5:01 PM Peter Geoghegan <pg@bowt.ie> wrote:
>
> On Mon, Nov 13, 2023 at 4:43 PM Bruce Momjian <bruce@momjian.us> wrote:
> > I looked into this and all the 4-byte xid functions are marked as
> > deprecated for the 8-byte variants.  I don't think documenting 4-byte
> > mxid_age() and age(xid) makes sense anymore, and I don't see their value
> > enough to create 8-byte versions, so I just added C comments that they
> > were undocumented, in the attached patch.
>
> I'm sympathetic to the goal of making 4 byte XIDs an on-disk
> implementation detail that is all but completely hidden from users.
> However, there are practical problems with taking that to its logical
> extreme. At least right now.
>
> These functions are in fact documented -- albeit only partially. There
> are references to both in "Routine Vacuuming". Moreover, those
> references are rather useful; they're the basis of many
> monitoring/alerting queries. If anything, I'd recommend adding more
> documentation for these two functions.
>
> We also continue to show 32-bit XIDs (alongside 32-bit relfrozenxid)
> in the output of VACUUM VERBOSE/autovacuum log messages. (Though that
> issue can be fixed fairly easily.)
>
> The bottom line is that there is only one way to figure out the age of
> a table right now, and it involves 32-bit XIDs/MXIDs, and these two
> functions. And, if we were to change something in this area, we'd
> definitely need to provide for the needs of those monitoring queries I
> mentioned.

Also, the doc page [1] mentions mxid_age(), but doesn't provide a
snippet to use it. The regular XID wraparound section above has such a
snippet. As a consequence, almost nobody monitors for MultiXact
wraparound – I noticed it recently once again, exploring numerous blog
posts and tools on this topic to write a howto [2] in my collection.

In other words, maybe there should be not only a reference doc for the
function itself present in the doc (the lack of it seems to be an
issue for all older versions), but also a snippet to control MultiXact
ID wraparound – while it's still a potential problem, it would be good
to have both a function reference doc and a how-to-use-it doc.

[1] https://www.postgresql.org/docs/current/routine-vacuuming.html#VACUUM-FOR-MULTIXACT-WRAPAROUND
[2]
https://gitlab.com/postgres-ai/postgresql-consulting/postgres-howtos/-/blob/main/0044_how_to_monitor_transaction_id_wraparound_risks.md



Re: mxid_age() and age(xid) appear undocumented

From
Andres Freund
Date:
Hi,

On 2023-11-13 17:00:43 -0800, Peter Geoghegan wrote:
> On Mon, Nov 13, 2023 at 4:43 PM Bruce Momjian <bruce@momjian.us> wrote:
> > I looked into this and all the 4-byte xid functions are marked as
> > deprecated for the 8-byte variants.  I don't think documenting 4-byte
> > mxid_age() and age(xid) makes sense anymore, and I don't see their value
> > enough to create 8-byte versions, so I just added C comments that they
> > were undocumented, in the attached patch.
> 
> I'm sympathetic to the goal of making 4 byte XIDs an on-disk
> implementation detail that is all but completely hidden from users.
> However, there are practical problems with taking that to its logical
> extreme. At least right now.
> 
> These functions are in fact documented -- albeit only partially. There
> are references to both in "Routine Vacuuming". Moreover, those
> references are rather useful; they're the basis of many
> monitoring/alerting queries. If anything, I'd recommend adding more
> documentation for these two functions.

+1


> We also continue to show 32-bit XIDs (alongside 32-bit relfrozenxid)
> in the output of VACUUM VERBOSE/autovacuum log messages. (Though that
> issue can be fixed fairly easily.)

I'm not sure it should be fixed, as long as we track horizons (in memory and
relfrozenxid) etc in 32 bit.  That seems like it'd just make it harder to
understand things.


> The bottom line is that there is only one way to figure out the age of
> a table right now, and it involves 32-bit XIDs/MXIDs, and these two
> functions.

Yes. I'm -many on deprecating these functions, until we've actually improved
the situation.


> And, if we were to change something in this area, we'd
> definitely need to provide for the needs of those monitoring queries I
> mentioned.

I think it'd be a bad idea to "deprecate" existing working queries, with the
replacement being a more complicated way to represent the same information.

Greetings,

Andres Freund



Re: mxid_age() and age(xid) appear undocumented

From
Bruce Momjian
Date:
On Mon, Nov 13, 2023 at 05:32:24PM -0800, Andres Freund wrote:
> Hi,
> 
> On 2023-11-13 17:00:43 -0800, Peter Geoghegan wrote:
> > On Mon, Nov 13, 2023 at 4:43 PM Bruce Momjian <bruce@momjian.us> wrote:
> > > I looked into this and all the 4-byte xid functions are marked as
> > > deprecated for the 8-byte variants.  I don't think documenting 4-byte
> > > mxid_age() and age(xid) makes sense anymore, and I don't see their value
> > > enough to create 8-byte versions, so I just added C comments that they
> > > were undocumented, in the attached patch.
> > 
> > I'm sympathetic to the goal of making 4 byte XIDs an on-disk
> > implementation detail that is all but completely hidden from users.
> > However, there are practical problems with taking that to its logical
> > extreme. At least right now.
> > 
> > These functions are in fact documented -- albeit only partially. There
> > are references to both in "Routine Vacuuming". Moreover, those
> > references are rather useful; they're the basis of many
> > monitoring/alerting queries. If anything, I'd recommend adding more
> > documentation for these two functions.
> 
> +1

Seems people still like these functions, so here is a patch to properly
document them.  :-)

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

Attachment

Re: mxid_age() and age(xid) appear undocumented

From
Bruce Momjian
Date:
On Fri, Nov 17, 2023 at 01:39:46PM -0500, Bruce Momjian wrote:
> On Mon, Nov 13, 2023 at 05:32:24PM -0800, Andres Freund wrote:
> > Hi,
> > 
> > On 2023-11-13 17:00:43 -0800, Peter Geoghegan wrote:
> > > On Mon, Nov 13, 2023 at 4:43 PM Bruce Momjian <bruce@momjian.us> wrote:
> > > > I looked into this and all the 4-byte xid functions are marked as
> > > > deprecated for the 8-byte variants.  I don't think documenting 4-byte
> > > > mxid_age() and age(xid) makes sense anymore, and I don't see their value
> > > > enough to create 8-byte versions, so I just added C comments that they
> > > > were undocumented, in the attached patch.
> > > 
> > > I'm sympathetic to the goal of making 4 byte XIDs an on-disk
> > > implementation detail that is all but completely hidden from users.
> > > However, there are practical problems with taking that to its logical
> > > extreme. At least right now.
> > > 
> > > These functions are in fact documented -- albeit only partially. There
> > > are references to both in "Routine Vacuuming". Moreover, those
> > > references are rather useful; they're the basis of many
> > > monitoring/alerting queries. If anything, I'd recommend adding more
> > > documentation for these two functions.
> > 
> > +1
> 
> Seems people still like these functions, so here is a patch to properly
> document them.  :-)

Patch applied back to PG 16.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.