From 3c6faf55f0fdcbf89dfa8aac85e7d03f9aa02c95 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Tue, 9 Jun 2026 18:32:02 -0400 Subject: [PATCH 1/6] Distributed tracing --- .../monitor-and-alert/_index.md | 6 + .../ysql-distributed-tracing.md | 169 ++++++++++++++++++ 2 files changed, 175 insertions(+) create mode 100644 docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md b/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md index 5d53433059ab..e31c4285ef20 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md @@ -38,6 +38,12 @@ type: indexpage href="active-session-history-monitor/" icon="fa-thin fa-monitor-waveform">}} + {{}} + {{}} and currently instruments the **YSQL (Postgres) layer only**. Tracing inside tablet servers is not included in this release. + +## How it works + +YSQL distributed tracing follows the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. Your application (or a SQL comment or session setting) supplies a `traceparent` value. YugabyteDB creates spans for the query lifecycle and exports them to an OTel collector over OTLP/HTTP. + +Each traced query produces a **trace** made up of **spans**. Spans are nested to show where time is spent—for example, planning, execution, commit, and individual RPC calls to `PgClientService`. + +When tracing is disabled (the default), there is no measurable performance impact. When tracing is enabled for a query, other queries and other YSQL backends are not affected. + +## Prerequisites + +- YSQL must be enabled on the cluster. +- An OTLP/HTTP endpoint must be reachable from each YB-TServer node. YugabyteDB does not export traces unless `otel_collector_traces_endpoint` is set. +- Because distributed tracing is a preview feature, add `otel_collector_traces_endpoint` to the [allowed_preview_flags_csv](../../../reference/configuration/yb-tserver/#allowed-preview-flags-csv) list before setting it. + +## Set up tracing + +The following example uses [Jaeger](https://www.jaegertracing.io/) as the trace backend. Jaeger accepts OTLP over HTTP on port 4318. + +### 1. Start Jaeger + +Run Jaeger all-in-one with OTLP enabled: + +```sh +docker run --rm --name jaeger \ + -e COLLECTOR_OTLP_ENABLED=true \ + -p 16686:16686 \ + -p 4318:4318 \ + jaegertracing/all-in-one:1.61 +``` + +Open the Jaeger UI at [http://localhost:16686](http://localhost:16686). + +### 2. Configure YugabyteDB + +Set the following YB-TServer flags on each node in the cluster. Changing these flags requires a YB-TServer restart. + +| Flag | Description | +| :--- | :---------- | +| [allowed_preview_flags_csv](../../../reference/configuration/yb-tserver/#allowed-preview-flags-csv) | Must include `otel_collector_traces_endpoint`. | +| otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported—for example, `http://:4318/v1/traces`. Setting this flag enables tracing infrastructure in each YSQL backend process. | +| otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. Default: `2048`. | +| otel_batch_schedule_delay_ms | Milliseconds between batch exports. Default: `5000`. Lower values reduce export latency but increase export frequency. | +| otel_batch_max_export_batch_size | Maximum spans per export batch. Default: `512`. | + +For a local single-node cluster started with yugabyted: + +```sh +./bin/yugabyted start \ + --tserver_flags "allowed_preview_flags_csv=otel_collector_traces_endpoint,otel_collector_traces_endpoint=http://127.0.0.1:4318/v1/traces" +``` + +If you use YugabyteDB Anywhere, set the flags using [Edit configuration flags](../../../yugabyte-platform/manage-deployments/edit-config-flags/#modify-configuration-flags). + +{{< note title="Note" >}} + +If `otel_collector_traces_endpoint` is not set, attempting to use the `yb_dist_tracecontext` configuration parameter returns an error indicating that distributed tracing is not enabled. + +{{}} + +### 3. Trace a query + +After the cluster is running with tracing configured, enable tracing for individual queries using one of the following methods. + +#### SQL comment (per query) + +Prepend or append a block comment that contains a W3C `traceparent` value. The comment must be the **first** block comment at the start of the query, or the **last** block comment at the end of the query. + +```sql +/*traceparent='00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'*/ +SELECT * FROM orders WHERE customer_id = 500; +``` + +You can also place the comment at the end of the statement: + +```sql +SELECT * FROM orders WHERE customer_id = 500 +/*traceparent='00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'*/; +``` + +If another block comment appears before a leading `traceparent` comment, or after a trailing `traceparent` comment, the `traceparent` is not parsed. + +#### Configuration parameter (per session or transaction) + +Set the `yb_dist_tracecontext` parameter to trace every query in the session or transaction: + +```sql +BEGIN; +SET LOCAL yb_dist_tracecontext = 'traceparent=''00-00000000000000000000000000000001-0000000000000005-01'''; +SELECT * FROM users WHERE id = 10; +UPDATE accounts SET balance = balance - 100 WHERE id = 10; +COMMIT; +``` + +If both the parameter and a SQL comment supply a `traceparent`, the parameter takes priority and a warning is emitted. + +To stop tracing for the session: + +```sql +RESET yb_dist_tracecontext; +``` + +### 4. View traces + +Run a traced query, wait a few seconds for spans to be batched and exported (controlled by `otel_batch_schedule_delay_ms`), then open the Jaeger UI. + +1. Select **Service** `ysql`. +2. Click **Find Traces**. +3. Open a trace to see spans such as `query`, `parse`, `plan`, `execute`, `commit`, and RPC spans. + +## Trace data + +### Process attributes + +Each YSQL backend exports process metadata with every trace: + +| Attribute | Description | +| :-------- | :---------- | +| service.name | Always `ysql`. | +| service.instance.id | UUID of the YB-TServer node running the YSQL backend. | +| process.pid | Operating-system PID of the YSQL backend process. | + +### Span attributes + +Every span includes standard OpenTelemetry fields such as operation name, span ID, parent span ID, trace ID, start time, duration, span kind, and status. + +Additional attributes depend on the span type: + +| Span | Additional attributes | +| :--- | :-------------------- | +| Root (`query`) | `query.text` (truncated to 256 characters), `user.id` (PostgreSQL role OID) | +| RPC (for example, `rpc yb.tserver.PgClientService.Perform`) | `rpc.table_names` — tables accessed by the RPC | + +Typical span names include: + +- Query lifecycle: `query`, `parse`, `rewrite`, `plan`, `execute`, `commit`, `abort` +- Extended query protocol: `ext.parse`, `ext.bind`, `ext.execute`, `ext.sync`, `ext.describe`, `ext.flush` +- RPC calls: `rpc yb.tserver.PgClientService.Perform` and related RPC operation names + +## Join application traces + +Because YugabyteDB accepts W3C `traceparent` values, you can continue a trace started in application code. Pass the same `traceparent` in a SQL comment or `yb_dist_tracecontext` parameter so database spans appear as children of your application's root span in your observability backend. + +## Related topics + +- [Monitor with Active Session History](active-session-history-monitor/) — sample-based view of database wait events +- [Query tuning](query-tuning/) — optimize query performance with EXPLAIN, pg_stat_statements, and related tools +- [Jaeger integration](../../../integrations/jaeger/) — use YCQL as Jaeger trace storage (separate from YSQL query tracing) From 9408b0688992b2474161fd052b42e64c43b783b7 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 10 Jun 2026 01:09:07 -0400 Subject: [PATCH 2/6] tidyups --- .../ysql-distributed-tracing.md | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md index 6e5c980125e3..e67a43e8ce52 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md @@ -16,15 +16,15 @@ rightNav: hideH4: true --- -When a YSQL query is slow, the time can be spent in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as **OpenTelemetry (OTel)** traces so you can inspect a waterfall view of query execution in tools such as Jaeger, Grafana Tempo, or Honeycomb. +When a YSQL query is slow, the time can be spent in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as OpenTelemetry (OTel) traces so you can inspect a waterfall view of query execution in tools such as Jaeger, Grafana Tempo, or Honeycomb. -Distributed tracing is {{}} and currently instruments the **YSQL (Postgres) layer only**. Tracing inside tablet servers is not included in this release. +Distributed tracing is {{}} and is currently only available for YSQL. Tracing inside tablet servers is not included in this release. ## How it works YSQL distributed tracing follows the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. Your application (or a SQL comment or session setting) supplies a `traceparent` value. YugabyteDB creates spans for the query lifecycle and exports them to an OTel collector over OTLP/HTTP. -Each traced query produces a **trace** made up of **spans**. Spans are nested to show where time is spent—for example, planning, execution, commit, and individual RPC calls to `PgClientService`. +Each traced query produces a _trace_ made up of _spans_. Spans are nested to show where time is spent. For example, planning, execution, commit, and individual RPC calls to `PgClientService`. When tracing is disabled (the default), there is no measurable performance impact. When tracing is enabled for a query, other queries and other YSQL backends are not affected. @@ -38,7 +38,7 @@ When tracing is disabled (the default), there is no measurable performance impac The following example uses [Jaeger](https://www.jaegertracing.io/) as the trace backend. Jaeger accepts OTLP over HTTP on port 4318. -### 1. Start Jaeger +### Start Jaeger Run Jaeger all-in-one with OTLP enabled: @@ -52,14 +52,13 @@ docker run --rm --name jaeger \ Open the Jaeger UI at [http://localhost:16686](http://localhost:16686). -### 2. Configure YugabyteDB +### Configure YugabyteDB Set the following YB-TServer flags on each node in the cluster. Changing these flags requires a YB-TServer restart. | Flag | Description | | :--- | :---------- | -| [allowed_preview_flags_csv](../../../reference/configuration/yb-tserver/#allowed-preview-flags-csv) | Must include `otel_collector_traces_endpoint`. | -| otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported—for example, `http://:4318/v1/traces`. Setting this flag enables tracing infrastructure in each YSQL backend process. | +| otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported. For example, `http://:4318/v1/traces`. Setting this flag enables tracing infrastructure in each YSQL backend process. | | otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. Default: `2048`. | | otel_batch_schedule_delay_ms | Milliseconds between batch exports. Default: `5000`. Lower values reduce export latency but increase export frequency. | | otel_batch_max_export_batch_size | Maximum spans per export batch. Default: `512`. | @@ -79,13 +78,13 @@ If `otel_collector_traces_endpoint` is not set, attempting to use the `yb_dist_t {{}} -### 3. Trace a query +### Trace a query After the cluster is running with tracing configured, enable tracing for individual queries using one of the following methods. #### SQL comment (per query) -Prepend or append a block comment that contains a W3C `traceparent` value. The comment must be the **first** block comment at the start of the query, or the **last** block comment at the end of the query. +Prepend or append a block comment that contains a W3C `traceparent` value. The comment must be the _first_ block comment at the start of the query, or the _last_ block comment at the end of the query. ```sql /*traceparent='00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'*/ @@ -121,7 +120,7 @@ To stop tracing for the session: RESET yb_dist_tracecontext; ``` -### 4. View traces +### View traces Run a traced query, wait a few seconds for spans to be batched and exported (controlled by `otel_batch_schedule_delay_ms`), then open the Jaeger UI. @@ -164,6 +163,6 @@ Because YugabyteDB accepts W3C `traceparent` values, you can continue a trace st ## Related topics -- [Monitor with Active Session History](active-session-history-monitor/) — sample-based view of database wait events -- [Query tuning](query-tuning/) — optimize query performance with EXPLAIN, pg_stat_statements, and related tools -- [Jaeger integration](../../../integrations/jaeger/) — use YCQL as Jaeger trace storage (separate from YSQL query tracing) +- [Monitor with Active Session History](../active-session-history-monitor/) - sample-based view of database wait events +- [Query tuning](../query-tuning/) - optimize query performance with EXPLAIN, pg_stat_statements, and related tools +- [Jaeger integration](../../../integrations/jaeger/) - use YCQL as Jaeger trace storage (separate from YSQL query tracing) From e8cff6b9eb97c38213bb5c2eaadae47f860a3fa3 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 10 Jun 2026 10:08:41 -0400 Subject: [PATCH 3/6] comments --- .../monitor-and-alert/_index.md | 2 +- .../ysql-distributed-tracing.md | 42 +++++++++---------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md b/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md index e31c4285ef20..8af0ad6baef4 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/_index.md @@ -39,7 +39,7 @@ type: indexpage icon="fa-thin fa-monitor-waveform">}} {{}} diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md index e67a43e8ce52..4518f43bb163 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md @@ -1,7 +1,7 @@ --- -title: YSQL distributed tracing -linkTitle: YSQL distributed tracing -headerTitle: YSQL distributed tracing +title: YSQL Distributed Tracing +linkTitle: YSQL Distributed Tracing +headerTitle: YSQL Distributed Tracing description: Export OpenTelemetry traces for YSQL query execution. headcontent: Trace YSQL queries with OpenTelemetry menu: @@ -16,23 +16,34 @@ rightNav: hideH4: true --- -When a YSQL query is slow, the time can be spent in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as OpenTelemetry (OTel) traces so you can inspect a waterfall view of query execution in tools such as Jaeger, Grafana Tempo, or Honeycomb. +YSQL queries spends time in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as OpenTelemetry (OTel) traces so you can inspect a waterfall view of query execution in tools such as [Jaeger](/stable/integrations/jaeger/), [Grafana Tempo](https://grafana.com/oss/tempo/), or [Honeycomb](https://www.honeycomb.io). -Distributed tracing is {{}} and is currently only available for YSQL. Tracing inside tablet servers is not included in this release. +Distributed Tracing is {{}} and is currently only available for YSQL. Tracing inside tablet servers is not included in this release. ## How it works -YSQL distributed tracing follows the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. Your application (or a SQL comment or session setting) supplies a `traceparent` value. YugabyteDB creates spans for the query lifecycle and exports them to an OTel collector over OTLP/HTTP. +YSQL Distributed Tracing follows the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. Your application (or a SQL comment or session setting) supplies a `traceparent` value. YugabyteDB creates spans for the query lifecycle and exports them to an OTel collector over OTLP/HTTP. Each traced query produces a _trace_ made up of _spans_. Spans are nested to show where time is spent. For example, planning, execution, commit, and individual RPC calls to `PgClientService`. When tracing is disabled (the default), there is no measurable performance impact. When tracing is enabled for a query, other queries and other YSQL backends are not affected. +## Configure Distributed Tracing + +To configure Distributed Tracing, set the following YB-TServer flags on each node in the cluster. Changing these flags requires a YB-TServer restart. + +| Flag | Description | Default | +| :--- | :---------- | :------ | +| otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported. For example, `http://:4318/v1/traces`.
Setting this flag enables tracing infrastructure in each YSQL backend process. | Empty | +| otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. | `2048` | +| otel_batch_schedule_delay_ms | Milliseconds between batch exports. Lower values reduce export latency but increase export frequency. | `5000` | +| otel_batch_max_export_batch_size | Maximum spans per export batch. | `512` | + ## Prerequisites - YSQL must be enabled on the cluster. -- An OTLP/HTTP endpoint must be reachable from each YB-TServer node. YugabyteDB does not export traces unless `otel_collector_traces_endpoint` is set. -- Because distributed tracing is a preview feature, add `otel_collector_traces_endpoint` to the [allowed_preview_flags_csv](../../../reference/configuration/yb-tserver/#allowed-preview-flags-csv) list before setting it. +- The OTLP/HTTP endpoint must be reachable from each YB-TServer node. +- Because Distributed Tracing is a preview feature, add `otel_collector_traces_endpoint` to the [allowed_preview_flags_csv](../../../reference/configuration/yb-tserver/#allowed-preview-flags-csv) list before setting it. ## Set up tracing @@ -52,17 +63,6 @@ docker run --rm --name jaeger \ Open the Jaeger UI at [http://localhost:16686](http://localhost:16686). -### Configure YugabyteDB - -Set the following YB-TServer flags on each node in the cluster. Changing these flags requires a YB-TServer restart. - -| Flag | Description | -| :--- | :---------- | -| otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported. For example, `http://:4318/v1/traces`. Setting this flag enables tracing infrastructure in each YSQL backend process. | -| otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. Default: `2048`. | -| otel_batch_schedule_delay_ms | Milliseconds between batch exports. Default: `5000`. Lower values reduce export latency but increase export frequency. | -| otel_batch_max_export_batch_size | Maximum spans per export batch. Default: `512`. | - For a local single-node cluster started with yugabyted: ```sh @@ -74,7 +74,7 @@ If you use YugabyteDB Anywhere, set the flags using [Edit configuration flags](. {{< note title="Note" >}} -If `otel_collector_traces_endpoint` is not set, attempting to use the `yb_dist_tracecontext` configuration parameter returns an error indicating that distributed tracing is not enabled. +If `otel_collector_traces_endpoint` is not set, attempting to use the [yb_dist_tracecontext](#configuration-parameter-per-session-or-transaction) configuration parameter returns an error indicating that Distributed Tracing is not enabled. {{}} @@ -102,7 +102,7 @@ If another block comment appears before a leading `traceparent` comment, or afte #### Configuration parameter (per session or transaction) -Set the `yb_dist_tracecontext` parameter to trace every query in the session or transaction: +Set the `yb_dist_tracecontext` YSQL [configuration parameter](../../../reference/configuration/yb-tserver/#postgresql-configuration-parameters) to trace every query in a session or transaction: ```sql BEGIN; From 8fcb41a834b5eda3030ea5f132cbe7c9e0da86d7 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 10 Jun 2026 10:14:22 -0400 Subject: [PATCH 4/6] note on version --- .../monitor-and-alert/ysql-distributed-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md index 4518f43bb163..c61c71686346 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md @@ -18,7 +18,7 @@ rightNav: YSQL queries spends time in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as OpenTelemetry (OTel) traces so you can inspect a waterfall view of query execution in tools such as [Jaeger](/stable/integrations/jaeger/), [Grafana Tempo](https://grafana.com/oss/tempo/), or [Honeycomb](https://www.honeycomb.io). -Distributed Tracing is {{}} and is currently only available for YSQL. Tracing inside tablet servers is not included in this release. +Distributed Tracing is {{}} and available in v2025.2.4.0 and later, and is currently only available for YSQL. Tracing inside tablet servers is not included in this release. ## How it works From d0e9528d65a9b740d15b1e21235c4cf4a06ce2c6 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 10 Jun 2026 15:42:04 -0400 Subject: [PATCH 5/6] comments --- .../ysql-distributed-tracing.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md index c61c71686346..b83f6a1b1195 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md @@ -16,13 +16,13 @@ rightNav: hideH4: true --- -YSQL queries spends time in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as OpenTelemetry (OTel) traces so you can inspect a waterfall view of query execution in tools such as [Jaeger](/stable/integrations/jaeger/), [Grafana Tempo](https://grafana.com/oss/tempo/), or [Honeycomb](https://www.honeycomb.io). +YSQL queries spend time in many places: parsing, planning, execution, transaction commit, and RPC calls to tablet servers. YugabyteDB can export timing data for these stages as OpenTelemetry (OTel) traces so you can inspect a waterfall view of query execution in tools such as [Jaeger](/stable/integrations/jaeger/), [Grafana Tempo](https://grafana.com/oss/tempo/), or [Honeycomb](https://www.honeycomb.io). Distributed Tracing is {{}} and available in v2025.2.4.0 and later, and is currently only available for YSQL. Tracing inside tablet servers is not included in this release. ## How it works -YSQL Distributed Tracing follows the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. Your application (or a SQL comment or session setting) supplies a `traceparent` value. YugabyteDB creates spans for the query lifecycle and exports them to an OTel collector over OTLP/HTTP. +YSQL Distributed Tracing follows the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. Your application supplies a `traceparent` value. YugabyteDB creates spans for the query lifecycle and exports them to an OTel collector over OTLP/HTTP. Each traced query produces a _trace_ made up of _spans_. Spans are nested to show where time is spent. For example, planning, execution, commit, and individual RPC calls to `PgClientService`. @@ -35,9 +35,9 @@ To configure Distributed Tracing, set the following YB-TServer flags on each nod | Flag | Description | Default | | :--- | :---------- | :------ | | otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported. For example, `http://:4318/v1/traces`.
Setting this flag enables tracing infrastructure in each YSQL backend process. | Empty | -| otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. | `2048` | +| otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. Must be greater than 0 and at least as large as `otel_batch_max_export_batch_size`. | `2048` | | otel_batch_schedule_delay_ms | Milliseconds between batch exports. Lower values reduce export latency but increase export frequency. | `5000` | -| otel_batch_max_export_batch_size | Maximum spans per export batch. | `512` | +| otel_batch_max_export_batch_size | Maximum spans per export batch. Must be greater than 0 and no larger than `otel_batch_max_queue_size`. | `512` | ## Prerequisites @@ -84,7 +84,7 @@ After the cluster is running with tracing configured, enable tracing for individ #### SQL comment (per query) -Prepend or append a block comment that contains a W3C `traceparent` value. The comment must be the _first_ block comment at the start of the query, or the _last_ block comment at the end of the query. +Prepend or append a block comment that contains a W3C `traceparent` value. The comment must be the _first_ block comment at the start of the query, or the _last_ block comment at the end of the query. If the comment is not the first or last, the `traceparent` is not parsed. ```sql /*traceparent='00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'*/ @@ -98,11 +98,11 @@ SELECT * FROM orders WHERE customer_id = 500 /*traceparent='00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'*/; ``` -If another block comment appears before a leading `traceparent` comment, or after a trailing `traceparent` comment, the `traceparent` is not parsed. - #### Configuration parameter (per session or transaction) -Set the `yb_dist_tracecontext` YSQL [configuration parameter](../../../reference/configuration/yb-tserver/#postgresql-configuration-parameters) to trace every query in a session or transaction: +Set the `yb_dist_tracecontext` YSQL [configuration parameter](../../../reference/configuration/yb-tserver/#postgresql-configuration-parameters). + +For example, to trace every query in the current transaction: ```sql BEGIN; @@ -112,14 +112,14 @@ UPDATE accounts SET balance = balance - 100 WHERE id = 10; COMMIT; ``` -If both the parameter and a SQL comment supply a `traceparent`, the parameter takes priority and a warning is emitted. - To stop tracing for the session: ```sql RESET yb_dist_tracecontext; ``` +Note: If you provide both a `traceparent` parameter _and_ SQL comment, the parameter takes priority and a warning is emitted. + ### View traces Run a traced query, wait a few seconds for spans to be batched and exported (controlled by `otel_batch_schedule_delay_ms`), then open the Jaeger UI. From 69583f6bdc0ab85108149067f8ce54c636b868c4 Mon Sep 17 00:00:00 2001 From: Dwight Hodge Date: Wed, 10 Jun 2026 17:06:42 -0400 Subject: [PATCH 6/6] comments --- .../monitor-and-alert/ysql-distributed-tracing.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md index b83f6a1b1195..b2b03c5c6caa 100644 --- a/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md +++ b/docs/content/stable/launch-and-manage/monitor-and-alert/ysql-distributed-tracing.md @@ -35,7 +35,7 @@ To configure Distributed Tracing, set the following YB-TServer flags on each nod | Flag | Description | Default | | :--- | :---------- | :------ | | otel_collector_traces_endpoint | OTLP/HTTP URL where spans are exported. For example, `http://:4318/v1/traces`.
Setting this flag enables tracing infrastructure in each YSQL backend process. | Empty | -| otel_batch_max_queue_size | Maximum spans buffered before export. Spans beyond this limit are dropped. Must be greater than 0 and at least as large as `otel_batch_max_export_batch_size`. | `2048` | +| otel_batch_max_queue_size | Maximum number of spans buffered in the queue. Spans beyond this limit are dropped. Must be greater than 0 and at least as large as `otel_batch_max_export_batch_size`. | `2048` | | otel_batch_schedule_delay_ms | Milliseconds between batch exports. Lower values reduce export latency but increase export frequency. | `5000` | | otel_batch_max_export_batch_size | Maximum spans per export batch. Must be greater than 0 and no larger than `otel_batch_max_queue_size`. | `512` | @@ -118,7 +118,11 @@ To stop tracing for the session: RESET yb_dist_tracecontext; ``` -Note: If you provide both a `traceparent` parameter _and_ SQL comment, the parameter takes priority and a warning is emitted. +{{< note title="Parameter takes precedence" >}} + +If you provide both a `traceparent` parameter _and_ SQL comment, the parameter takes priority and a warning is emitted. + +{{< /note >}} ### View traces