> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Query tracing

> Trace a Cube API request through to the queries it runs on your data source.

Cube can tag the queries it sends to your data source with a `trace_id` SQL
comment, letting you match a query in your data source's query history back to
the API request that caused it.

This is useful when one API request fans out into several data source
queries — every one of them carries the same `trace_id`.

## Configuration

Set [`CUBEJS_SQL_INCLUDE_TRACE_ID`](https://docs.cube.dev/reference/configuration/environment-variables#cubejs_sql_include_trace_id)
to `true`:

```dotenv theme={"dark"}
CUBEJS_SQL_INCLUDE_TRACE_ID=true
```

Queries then reach your data source with the comment appended:

```sql theme={"dark"}
SELECT ...
/* trace_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 */
```

`trace_id` identifies the API request and matches the field of the same name in
the [Query History export][ref-query-history-export].

> [!WARNING]
>
> A unique comment per request makes each query textually distinct, which
> prevents your data source from reusing cached results — Snowflake's persisted
> query results and BigQuery's result cache both require identical query text.
> Expect more queries to actually execute, and on Snowflake a warehouse that
> would have stayed suspended may resume.

## Finding the comment in your data source

Some query history views truncate long SQL, and a few omit comments entirely.
If you can't find the `trace_id`, check where you're reading it from:

* **Snowflake**: `QUERY_HISTORY`. Note that Snowflake strips *leading* comments,
  which is why Cube appends.
* **Redshift**: `SYS_QUERY_TEXT`, reassembled with `LISTAGG`.
  `SYS_QUERY_HISTORY` and `STL_QUERY` truncate at 4000 characters.
* **BigQuery**: `INFORMATION_SCHEMA.JOBS`. Cloud Audit Logs truncate at 50K
  characters.
* **Databricks**: `system.query.history`. Empty when customer-managed keys are
  enabled.
* **Postgres**: server logs (`log_statement`). `pg_stat_activity.query`
  truncates at `track_activity_query_size` (1024 bytes by default).
* **MySQL**: the general or slow query log.

## Supplying your own identifier

Clients calling the [REST (JSON) API](https://docs.cube.dev/reference/core-data-apis/rest-api) can
supply their own identifier through the `x-request-id` or `traceparent` request
header, letting you trace a query back to a request in your own application.
Otherwise Cube generates one.

## Scope

Queries issued to serve an API request are tagged. Pre-aggregation builds,
export bucket operations, refresh keys, background refreshes, and Cube's own
internal queries are left untagged, since there is no API request to trace them
back to.

A single request usually produces one tagged query, but not always — a query
reading a lambda pre-aggregation's source table, for instance, is tagged too.
Match on `trace_id` rather than assuming one row per request.

Not every request produces a tagged query to find: one served from the cache or
from a pre-aggregation never reaches your data source, and when identical
queries arrive together Cube runs them once, under whichever request got there
first. The other requests still appear in the Query History export, but their
`trace_id` matches nothing in your data source's query history.

[ref-query-history-export]: https://docs.cube.dev/admin/monitoring/monitoring-integrations#query-history-export


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.