# 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:

```sql
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.
