diff --git a/src/current/_includes/v25.3/ui/insights.md b/src/current/_includes/v25.3/ui/insights.md index c3aeb5d162f..699037606d0 100644 --- a/src/current/_includes/v25.3/ui/insights.md +++ b/src/current/_includes/v25.3/ui/insights.md @@ -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. 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.

{%- 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.

{%- 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. + +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. @@ -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. @@ -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.