Skip to content

Commit 6223358

Browse files
committed
In query-behavior-troubleshooting.md, added section for Log traces for transactions.
1 parent f9a6f79 commit 6223358

File tree

1 file changed

+36
-1
lines changed

1 file changed

+36
-1
lines changed

src/current/v25.3/query-behavior-troubleshooting.md

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ You can identify high-latency SQL statements on the [**Insights**]({% link {{ pa
2929

3030
You can also enable the [slow query log]({% link {{ page.version.version }}/logging-use-cases.md %}#sql_perf) to log all queries whose latency exceeds a configured threshold, as well as queries that perform a full table or index scan.
3131

32-
You can collect richer diagnostics of a high-latency statement by creating a [diagnostics bundle]({% link {{ page.version.version }}/ui-statements-page.md %}#diagnostics) when a statement fingerprint exceeds a certain latency.
32+
You can collect richer diagnostics of a high-latency statement by creating a [diagnostics bundle]({% link {{ page.version.version }}/ui-statements-page.md %}#diagnostics) when a statement fingerprint exceeds a certain latency. Identify slow transactions in an active workload by [selectively logging traces of transactions](#log-traces-for-transactions) that exceed a configured latency threshold.
3333

3434
{{site.data.alerts.callout_info}}
3535
{% include {{ page.version.version }}/prod-deployment/resolution-untuned-query.md %}
@@ -109,6 +109,41 @@ docker run -d --name jaeger \
109109
-p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one:latest
110110
~~~
111111

112+
### Log traces for transactions
113+
114+
CockroachDB allows you to trace [transactions]({% link {{ page.version.version }}/transactions.md %}) to help troubleshoot performance issues. [Tracing]({% link {{ page.version.version }}/show-trace.md %}#trace-description) is controlled through two cluster settings that govern when a transaction trace is captured and emitted.
115+
116+
#### Trace sampling and emission
117+
118+
To enable tracing for a subset of transactions and emit relevant traces to the [`SQL_EXEC` logging channel]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels), configure the following cluster settings:
119+
120+
- {% include_cached new-in.html version="v25.3.0" %}[`sql.trace.txn.sample_rate`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-trace-txn-sample-rate): Specifies the probability (between `0.0` and `1.0`) that a given transaction will have tracing enabled. A value of `0.1` means that approximately 10% of transactions are traced. The default is `1`, meaning 100% transactions are sampled.
121+
- [`sql.trace.txn.enable_threshold`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-sql-trace-txn-enable-threshold): Specifies a duration threshold. A trace is emitted only if a sampled transaction's execution time exceeds this value.
122+
123+
To emit a trace to the logs, both conditions must be met:
124+
125+
1. The transaction is selected based on the sampling probability.
126+
1. Its execution duration exceeds the configured threshold.
127+
128+
This approach minimizes overhead by tracing a fraction of the workload and emitting traces only for transactions of potential interest.
129+
130+
#### Configuration example
131+
132+
{% include_cached copy-clipboard.html %}
133+
~~~ sql
134+
-- Enable trace sampling at 1%
135+
SET CLUSTER SETTING sql.trace.txn.sample_rate = 0.01;
136+
137+
-- Emit traces for sampled transactions that exceed 1s
138+
SET CLUSTER SETTING sql.trace.txn.enable_threshold = '1s';
139+
~~~
140+
141+
With this configuration, approximately 1% of transactions are traced, and only those running longer than 1s will have their traces written to the logs. In the `SQL_EXEC` log, a line similar to the following precedes the trace:
142+
143+
~~~
144+
SQL txn took 2.004362083s, exceeding threshold of 1s:
145+
~~~
146+
112147
<a id="query-is-always-slow"></a>
113148

114149
### Queries are always slow

0 commit comments

Comments
 (0)