Skip to content

DOC-13899 Product Change- PR #147439 - ui: surface SQL commenter query tags in insights #19897

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

DOC-13899 Product Change- PR #147439 - ui: surface SQL commenter query tags in insights #19897

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d0f7710
In include file insights.md, (1) added section for Query tags and (2)…
florence-crl Jul 7, 2025
336c80f
Merge remote-tracking branch 'origin/main' into DOC-13899
florence-crl Jul 7, 2025
f9a6f79
Merge remote-tracking branch 'origin/main' into DOC-13899
florence-crl Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions src/current/_includes/v25.3/ui/insights.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,15 +122,50 @@ Start Time (UTC) | The timestamp when the statement execution started.
Elapsed Time | The time that elapsed to complete the statement execution.
User Name | The name of the user that invoked the statement execution.
Application Name | The name specified by the [`application_name`]({{ link_prefix }}show-vars.html#supported-variables) session setting.
Query Tags | The [query tags](#query-tags) extracted from comments in the statement query. These tags provide application context and can be used to correlate query performance with client-side application state.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: can* help provide application if set

Note: Users don't get this out of the box. They need to instrument the comment in their query.

Rows Processed | The total number of rows read and written.
Retries | The number of times the statement execution was [retried]({{ link_prefix }}transactions.html#automatic-retries).
Contention Time | The amount of time the statement execution spent waiting in [contention]({{ link_prefix }}performance-best-practices-overview.html#transaction-contention).
CPU Time | The amount of CPU time spent executing the statement. The CPU time represents the time spent and work done within SQL execution operators. <br /><br />{%- if page.cloud != true -%}The CPU time includes time spent in the [SQL layer]({% link {{ page.version.version }}/architecture/sql-layer.md %}). It does not include time spent in the [storage layer]({% link {{ page.version.version }}/architecture/storage-layer.md %}).{%- endif -%}{%- if page.cloud == true -%}The CPU time includes time spent in the [SQL layer](../stable/architecture/sql-layer.html). It does not include time spent in the [storage layer](../stable/architecture/storage-layer.html).
SQL CPU Time | The amount of CPU time spent executing the statement. The CPU time represents the time spent and work done within SQL execution operators. <br /><br />{%- if page.cloud != true -%}The CPU time includes time spent in the [SQL layer]({% link {{ page.version.version }}/architecture/sql-layer.md %}). It does not include time spent in the [storage layer]({% link {{ page.version.version }}/architecture/storage-layer.md %}).{%- endif -%}{%- if page.cloud == true -%}The CPU time includes time spent in the [SQL layer](../stable/architecture/sql-layer.html). It does not include time spent in the [storage layer](../stable/architecture/storage-layer.html).
{%- endif %}
Full Scan | Whether the execution performed a full scan of the table.
Transaction Fingerprint ID | The ID of the transaction fingerprint for the statement execution.
Latest Transaction Execution ID | The ID of the transaction execution for the statement execution.

#### Query tags

{% include_cached new-in.html version="25.3.0" %} The **Query Tags** column displays SQLcommenter query tags for statement executions. These tags provide application context, such as the application name, user ID, or feature flags, embedded in SQL comments that follow the [SQLcommenter specification](https://google.github.io/sqlcommenter/spec/). This information helps correlate slow query performance with specific application states. The **Query Tags** column is available in the **Statement Executions** view's **Statement Insights** table but is hidden by default. To display it, use the **Columns** selector.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

displays SQLcommenter query tags for statement executions

Can we say displays the comments embedded int he query as defined by the specification?

These tags provide application context, such as the application name, user ID, or feature flags, embedded in SQL comments that follow the

Users need to instrument this


Query tags are also included in the following locations:

- [**Statement Execution** details](#statement-execution-details) page
- All [log entries generated]({{ link_prefix }}logging-use-cases.html#sql_exec) during the execution of a SQL statement (prefixed with `querytag-`)
- [Traces]({{ link_prefix }}show-trace.html) (prefixed with `querytag-`)
- The `crdb_internal.cluster_execution_insights` and `crdb_internal.node_execution_insights` [virtual tables]({{ link_prefix }}crdb-internal.html), in a new `query_tags` JSONB column

This feature is disabled by default. To enable it, set the [`sql.sqlcommenter.enabled` cluster setting]({{ link_prefix }}cluster-settings.html#setting-sql-sqlcommenter-enabled) to `true`.

For example:

1. Execute the following statements. Set `pg_sleep` to a value greater than the [`sql.insights.latency_threshold` cluster setting]({{ link_prefix }}cluster-settings.html#setting-sql-insights-latency-threshold) to generate a [Slow Execution](#slow-execution) insight.

{% include_cached copy-clipboard.html %}
~~~ sql
SET CLUSTER SETTING sql.sqlcommenter.enabled=true;
SELECT pg_sleep(2) /*db_driver='test_driver',db_framework='test_framework',db_backend='cockroachdb'*/;
~~~

1. On the Insights page, in the **Columns** selector, check **Query Tags** and click **Apply**.
1. For the row where **Statement Execution** is `SELECT pg_sleep()`, scroll to the right to see the key-value pairs from the SQL comment displayed in the **Query Tags** column.

~~~
db_driver=test_driver
db_framework=test_framework
db_backend=cockroachdb
~~~

1. On the same row, click on the **Latest Statement Execution ID** (the first column on the left) to open the [**Statement Execution** details](#statement-execution-details) page. These key-value pairs also appear on the **Overview** tab under **Query Tags**.

### Statement Execution details

The statement execution details view provides more information on a statement execution insight.
Expand All @@ -144,7 +179,7 @@ Field/Column | Description
Start Time | The timestamp when the statement execution started.
End Time | The timestamp when the statement execution ended.
Elapsed Time | The time that elapsed during statement execution.
CPU Time | The amount of CPU time spent executing the statement. The CPU time represents the time spent and work done within SQL execution operators. {% if page.cloud != true -%}The CPU time includes time spent in the [SQL layer]({% link {{ page.version.version }}/architecture/sql-layer.md %}). It does not include time spent in the [storage layer]({% link {{ page.version.version }}/architecture/storage-layer.md %}).{% endif %}{% if page.cloud == true -%}The CPU time includes time spent in the [SQL layer](../stable/architecture/sql-layer.html). It does not include time spent in the [storage layer](../stable/architecture/storage-layer.html).{% endif %}
SQL CPU Time | The amount of CPU time spent executing the statement. The CPU time represents the time spent and work done within SQL execution operators. {% if page.cloud != true -%}The CPU time includes time spent in the [SQL layer]({% link {{ page.version.version }}/architecture/sql-layer.md %}). It does not include time spent in the [storage layer]({% link {{ page.version.version }}/architecture/storage-layer.md %}).{% endif %}{% if page.cloud == true -%}The CPU time includes time spent in the [SQL layer](../stable/architecture/sql-layer.html). It does not include time spent in the [storage layer](../stable/architecture/storage-layer.html).{% endif %}
Rows Read | The total number of rows read by the statement execution.
Rows Written | The total number of rows written by the statement execution.
Transaction Priority | The [priority]({{ link_prefix }}transactions.html#set-transaction-priority) of the transaction for the statement execution.
Expand All @@ -154,6 +189,7 @@ Session ID | The ID of the [session]({{ link_prefix }}ui-sessions-page.html) the
Transaction Fingerprint ID | The ID of the transaction fingerprint for the statement execution.
Transaction Execution ID | The ID of the transaction execution for the statement execution.
Statement Fingerprint ID | The fingerprint ID of the statement fingerprint for the statement execution.
Query Tags | The [query tags](#query-tags) extracted from comments in the statement query. These tags provide application context and can be used to correlate query performance with client-side application state.
Insights | The [insight type](#workload-insight-types).
Details | Provides details on the insight. For example, if the insight type is High Contention, **Time Spent Waiting** and **Description** are displayed. If the insight type is Failed Execution, **Error Code** and **Error Message** are displayed.

Expand Down
Loading