I am not sure if the wait_event vs state relationship needs to
be documented specifically. I can think of another discrepancy
such as query_id = NULL and state = active, which occurs when
the query is still being parsed and jumbled and a query_id is not yet
available. There are probably other ephemeral discrepancies
across all these fields.
Another common pattern is joining pg_stat_activity and pg_locks,
and that will have the same problem. Of course, these are different
views being joined, so maybe there isn't an expectation of 100%
accuracy, but worth calling this out as well.
If we do need to document anything, which I am not convinced we should,
it should be more generic.
--
Sami Imseih
Amazon Web Services (AWS)