console: label each SQL request with its query key in Sentry and the statement log - #40075

Motivation

Sentry's browser tracing records one http.client span per fetch, and every Console SQL request is a POST to /api/sql. The query's label only travels in the query_key URL parameter, so a sampled page load cannot tell which query made it slow. Only fetchClusters, the replicas query and the environment health checks have named spans today.

Description

Two commits. Both name a request by its query key's scopes, for example clusters.list.

1. A Sentry span per request. executeSqlV2 records a db.sql.query span named after the scopes of the request's query key, for example clusters.list, with db.system: materialize. Sentry groups spans with a db op by name in its Queries view.

• Name. Only the scope of each key part goes into the name, because other parts can hold IDs and object names. A key with no scoped part is named unscoped query.
• Parent. The span starts only under an existing span (onlyIfParent), such as a page load or a navigation. A query that polls in the background never starts a trace of its own, so sampling and the number of traces are unchanged.
• Interval. It covers the request and parsing the response, after the environment's address resolves.
• Status. A request the caller aborted, such as a React Query cancellation, is cancelled. A timeout is deadline_exceeded. Any other failure is internal_error.
• startInactiveSpan, not startSpan. In the browser, startSpan with an async callback keeps its scope pushed until the promise settles, and the stack then pops whichever scope is on top. Parallel requests would nest under each other.

2. The same label in the SQL text. Each query gets a trailing comment such as /*console_query='clusters.list'*/. The statement log already records how long every Console query took on the server, in every environment. With the label in the text, a slow query can be traced to the Console feature that sent it. It can also be grouped by label in mz_recent_activity_log, for example with (regexp_match(sql, 'console_query=''([^'']+)'''))[1].

• Placement. The comment goes last because, on a recent main build, the statement log dropped leading comments and cut the text at the statement's ;. Trailing ;s are removed first.
• Characters. Anything outside [A-Za-z0-9_.-] in the label is replaced with _, so no label can end the comment.
• Who sees it. Query History hides the Console's own queries unless "show console introspection" is on, so customers see the label only when they ask for those queries. They can also see it in their own mz_recent_activity_log.
• Only the sql column. redacted_sql, and with it mz_recent_activity_log_redacted, is rebuilt from the parsed statement and has no comments. Anyone who can only read the redacted view won't see the label.
• sql_hash changes once. Every Console statement's text, and so its sql_hash, changes when this deploys. Anything that compares Console statements by hash across that release will see them as new statements.
• Not covered. V1 executeSql, the SQL Shell and subscribes are unchanged. useSqlTyped already puts a leading --queryKey comment, which the statement log drops. The V1 mock handler matches on that comment, so moving it is left for a follow-up.

User-visible effect: Console queries in the statement log, and in Query History with console introspection shown, end with a console_query comment naming the query.

Tests

executeSqlV2.test.ts gains:

• A test that the queries sent to the server carry the label.
• labelSql cases for trailing semicolons, a trailing line comment, and characters that could end the comment.
• queryKeyLabel and spanErrorStatus cases.
• Three tests against a real Sentry client that read the transactions it would send:
  • the span is named after the query key under an active span
  • no trace is started without one
  • an aborted request is cancelled

Each was checked to fail with the behavior removed.

Open questions

• Span volume. Every SQL request inside a sampled trace now carries two spans: this one and the http.client fetch span. If our Sentry plan bills by span, that adds roughly one span per SQL request in sampled page loads and navigations.
• Existing wrapper spans. fetchClusters and fetchClusterReplicas wrap executeSqlV2 in startSpan spans that can start root traces for background polls. With this change they duplicate its name. Remove them in a follow-up?
• Shared names. Requests made inside one queryFn with keys that differ only in unscoped parts share a name. For example, the deployment lineage lookup and the utilization query both read as replicaUtilization.

🤖 Generated with Claude Code