Skip to content
bucker

SQL comments and trace links: what they expose

Bucker can link a database sample (a blocker, a long-running statement) to the exact trace that issued it. It does this by reading a traceparent that your own application writes into its SQL. This is off by default, and nothing in Bucker turns it on. You enable it in your own code, per project and environment; the instrumentation_patch_propose tool can open a draft pull request that does it, and a person reviews and merges that pull request.

What the comment contains

A sqlcommenter comment, only on statements issued inside a sampled trace:

SELECT * FROM users WHERE id = $1 /*traceparent='00-<trace id>-<span id>-01'*/

The only thing Bucker reads from it is the trace id (and span id). Other sqlcommenter keys (route template, release, service name) may be present if your SDK adds them; Bucker does not read, store or show them.

Where the comment lands

The comment is part of the statement text, so it is visible to your database and to anything that sees statement text, not only to Bucker:

  • pg_stat_activity.query, to any role with pg_read_all_stats or the same user;
  • the slow-statement log and auto_explain output;
  • possibly pg_stat_statements text (the first text seen is kept; check your server and version);
  • your pooler, proxy and cloud provider's query logs.

A trace id is opaque. It is not a user, an account or a credential, but it identifies one request in your tracing data, so treat anyone who can read statement text as someone who can name your traces. The comment never carries user ids, emails or parameter values from Bucker, and you should not add them to it.

What Bucker does with it

  • It reads application_name, or a statement text a reader passes in, and accepts only a well-formed, sampled W3C traceparent (version 00, lowercase hex). Anything else links nothing.
  • Statement text is not collected by the activity sampler: it selects the query id, not the query. The comment is read where text is already in hand, and only the trace id is kept, on the sample row.
  • A trace id is shown as a link only when that trace has a span in the same project. A comment naming someone else's trace, or a trace Bucker has not received, shows nothing.
  • If two different traces appear in one text, nothing is linked.

Cost and behavior

  • Comments do not change fingerprints: Bucker normalises them away, and pg_stat_statements computes queryid from the parse tree.
  • Per-execution text can defeat a client-side prepared-statement cache in some drivers. That is one reason injection follows trace sampling: only sampled requests pay it.
  • OpenTelemetry marks SQL commenter propagation as a development feature that should not be on by default. Roll it out on one service first.

Turning it off

Remove the option from your instrumentation (addSqlCommenterCommentToQueries, enable_commenter, or the Prisma comments plugin). New statements carry no comment at once; samples already linked keep their trace id until they age out under the sample retention.

Correlation by statement fingerprint does not depend on any of this.