docs: document request ID propagation for /v1/cubesql endpoint

[paveltiunov]

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

Issue Reference this PR resolves

Documents the feature added in #10633 (feat(api-gateway): propagate request ID for REST /cubesql endpoint).

Description of Changes Made

The recent commit 1bce74b added request ID propagation from the HTTP request context (via x-request-id header, traceparent header, or auto-generated UUID) through to the native SQL execution for the /v1/cubesql endpoint. This PR adds documentation for this feature.

Changes

REST API overview (docs/content/product/apis-integrations/core-data-apis/rest-api/index.mdx):

• Updated the "Request span annotation" section to explicitly list both /v1/load and /v1/cubesql as endpoints that support request span annotation
• Documented traceparent header as an alternative to x-request-id
• Added documentation for the auto-generated request ID format (${uuid}-span-1) when no header is provided

REST API reference (docs/content/product/apis-integrations/core-data-apis/rest-api/reference.mdx):

• Added a paragraph to the /v1/cubesql endpoint section explaining request span annotation support with x-request-id and traceparent headers
• Added a curl example demonstrating usage of the x-request-id header with the /v1/cubesql endpoint
• Added a cross-reference link to the request span annotation section in the overview page

  

[claude]

Claude finished @paveltiunov's task in 1m 32s —— View job

---

Review of PR #10666

• Gather context and read changed files
• Review REST API overview changes (index.mdx)
• Review REST API reference changes (reference.mdx)
• Verify cross-references and technical accuracy
• Post final review

---

Overall Assessment

This is a clean, well-structured documentation PR. The changes accurately reflect the implementation in packages/cubejs-api-gateway/src/request-parser.ts and the cubesql endpoint in gateway.ts. I verified the source code and confirmed:

• x-request-id is checked first, then traceparent, then auto-generated ${uuid}-span-1 — matches the docs ✅
• The cubesql endpoint passes req.context?.requestId to execSql — the propagation chain is correct ✅
• Reference links ([ref-request-span], [ref-ref-load], [ref-ref-cubesql]) all resolve correctly ✅
• URL patterns are consistent with existing references in the same files ✅

Minor Issues

1. Typo in index.mdx — "as whole" should be "as a whole" (line 272)

The original text had this same issue, but since this paragraph was rewritten in this PR, it's a good opportunity to fix it:

which define `x-request-id` as whole:

should be:

which define `x-request-id` as a whole:

Fix this →

2. Missing traceparent format guidance in index.mdx

The docs mention traceparent as an alternative to x-request-id but don't describe the expected format for traceparent. Looking at the code (request-parser.ts:15), the raw header value is used directly — which means a standard W3C traceparent value (e.g., 00-trace-id-span-id-01) would be used as-is as the request ID. This might be worth a brief note, since traceparent values don't follow the ${spanId}-span-${requestSequenceId} format described in the same paragraph. Users might wonder which format to use.

3. Curl example (reference.mdx) — no expected response shown

The other curl examples in this file show the corresponding response. The new tracing example at lines 393-399 doesn't include a response block. While the response would be the same as the basic example, including it (or a brief note like "Response format is the same as above") would be consistent with the existing documentation pattern.

Positive Notes

• Good addition of traceparent as a documented alternative — it aligns with W3C Trace Context standards
• The auto-generated request ID format documentation (${uuid}-span-1) is helpful for users debugging traces
• Cross-reference from the /v1/cubesql section back to the request span annotation overview is well-placed
• The writing style correctly addresses the reader as "you" per the docs style guide

Summary

Looks good overall — this is a straightforward docs addition that accurately documents the feature from #10633. The only actionable item is the "as whole" → "as a whole" typo fix. The other two points are optional improvements.