| From: | Anthonin Bonnefoy <anthonin(dot)bonnefoy(at)datadoghq(dot)com> |
|---|---|
| To: | PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org> |
| Subject: | Add PQTRACE env to enable protocol tracing in libpq |
| Date: | 2026-07-31 09:00:54 |
| Message-ID: | CAO6_XqrOuYe8J1vOuErx0XarkF3e96fCO4fAHWOK-6amJ_UCew@mail.gmail.com |
| Views: | Whole Thread | Raw Message | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-hackers |
Hi,
Currently, libpq provides PQtrace to enable protocol tracing. However,
this can only be enabled by calling the PQtrace function, and there's
currently no way to use it with psql.
This patchset introduces a new PQTRACE option in libpq, allowing to
use protocol tracing in psql:
PQTRACE="-" psql
2026-07-30 14:33:06.654865 F 8 SSLRequest 1234 5679
2026-07-30 14:33:06.656358 B 1 SSLResponse N
...
2026-07-30 14:33:06.659056 B 5 ReadyForQuery I
postgres=#
PQTRACE can also be used in libpq_pipeline to replace the custom code,
simplifying it and adding test coverage on startup packets.
There are some limitations:
- multiple connections writing on the same file will overwrite each
other, so it is not supported.
- PQtrace won't be enabled on cancel connections if the target is a
file. If the target is stdout, PQtrace is enabled as 0004 modifies
fe-trace.c so lines are written in a single fwrite, preventing
possible interleaving.
Given that the goal is mostly to provide a quick and easy way to debug
protocol behavior, those limitations seem acceptable. With this
option, it will also be possible to create a test harness similar to
regress, where SQL scripts can be tested against expected traces and
outputs.
The patchset has the following files:
0001: Create the pqTraceOutputNbyte and use it for BackendKeyData and
CancelRequest to print the backend key as hex string.
Given that the BackendKeyData is a random key, there's not much
meaning to show the printable chars.
0002: Add additional regress masking for StartupMessage and
ParameterValue. Since those messages will appear in regression tests,
some of their values need to be masked.
0003: Add a mismatch length check on pqTraceOutputNoTypeByteMessage,
similar to what's already done in pqTraceOutputMessage.
0004: Make PQtrace write lines atomically. Instead of doing multiple
fprintf for a single line, a line is now buffered in a PQExpBuffer and
written as a single fwrite.
This will allow multiple connections tracing on stdout to print
without interleaving.
0005: Add the PQTRACE option to libpq.
0006: Switch libpq_pipeline to use PQTRACE. This simplifies
libpq_pipeline, and also adds startup messages to the expected traces.
This was originally posted on [0], but the original thread was about
fixing BackendKeyData tracing, so it seems better to create a
dedicated thread for this.
Regards,
Anthonin Bonnefoy
| Attachment | Content-Type | Size |
|---|---|---|
| v1-0003-Add-mismatch-length-check-on-pqTraceOutputNoTypeB.patch | application/octet-stream | 1.5 KB |
| v1-0001-Print-cancel-key-as-a-hex-string-in-trace.patch | application/octet-stream | 2.4 KB |
| v1-0002-Add-more-regress-masks-in-pqtrace.patch | application/octet-stream | 4.2 KB |
| v1-0004-Make-pqtrace-write-lines-atomically.patch | application/octet-stream | 38.6 KB |
| v1-0005-Add-PQTRACE-env-to-enable-protocol-tracing-in-lib.patch | application/octet-stream | 6.6 KB |
| v1-0006-Add-trace-of-startup-packets-in-libpq_pipeline-te.patch | application/octet-stream | 17.6 KB |
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Hayato Kuroda (Fujitsu) | 2026-07-31 09:12:00 | RE: 030_pg_recvlogical fails because the same PID is assigned |
| Previous Message | Peter Smith | 2026-07-31 08:44:13 | Re: Support EXCEPT for TABLES IN SCHEMA publications |