DOC-13899 Product Change- PR #147439 - ui: surface SQL commenter query tags in insights #19897
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
… corrected SQL CPU Time column name.
Files changed:
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
florence-crl
requested review from
mikeCRL,
angles-n-daemons,
kyle-a-wong and
kevin-v-ngo
and removed request for
mikeCRL
angles-n-daemons
approved these changes
Jul 8, 2025
kyle-a-wong
approved these changes
Jul 10, 2025
kevin-v-ngo
requested changes
Jul 14, 2025
| @@ -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. | |||
There was a problem hiding this comment.
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.
| {%- 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. |
There was a problem hiding this comment.
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
mikeCRL
approved these changes
Jul 15, 2025
There was a problem hiding this comment.
Left some suggestions.
Also want to be sure you're aware of the various capitalizations of SQLcommenter: Google's blog uses Sqlcommenter, the repo uses sqlcommenter, and their docs are mixed, often using SQL commenter with a space. Not an easy call which one to use, and I can even see an argument for leaving as SQLcommenter.
| {%- 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. |
There was a problem hiding this comment.
Suggested change
| {% 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. | |
| {% include_cached new-in.html version="25.3" %} 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. |
|
|
||
| Query tags are also included in the following locations: | ||
|
|
||
| - [**Statement Execution** details](#statement-execution-details) page |
There was a problem hiding this comment.
Suggested change
| - [**Statement Execution** details](#statement-execution-details) page | |
| - The [**Statement Execution** details](#statement-execution-details) page |
to match the structure of the other list items by using a more complete phrase
|
|
||
| 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: |
There was a problem hiding this comment.
I think this should be more specific about what the following instructions will do, e.g.
Suggested change
| For example: | |
| To test this functionality, you can generate a SQL query with a [Slow Execution](#slow-execution), then view it on the Insights page: |
Comment on lines
+150
to
+156
| 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'*/; | ||
| ~~~ |
There was a problem hiding this comment.
A suggestion, for your consideration, to check the latency threshold first, and then split the other two statements into their own steps, explaining each.
Suggested change
| 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. Enable SQLcommenter query tagging: | |
| {% include_cached copy-clipboard.html %} | |
| ~~~ sql | |
| SET CLUSTER SETTING sql.sqlcommenter.enabled=true; | |
| ~~~ | |
| 1. Check the value of cluster setting [`sql.insights.latency_threshold`]({{ link_prefix }}cluster-settings.html#setting-sql-insights-latency-threshold): | |
| {% include_cached copy-clipboard.html %} | |
| ~~~ sql | |
| SHOW CLUSTER SETTING sql.insights.latency_threshold; | |
| ~~~ | |
| 1. Execute the following statement, using a `pg_sleep` value greater than the `latency_threshold`: | |
| {% include_cached copy-clipboard.html %} | |
| ~~~ sql | |
| SELECT pg_sleep(2) /*db_driver='test_driver',db_framework='test_framework',db_backend='cockroachdb'*/; | |
| ~~~ |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes DOC-13899 DOC-13614
In include file insights.md, (1) added section for Query tags and (2) corrected SQL CPU Time column name.
Rendered preview