diff --git a/docs/telemetry.md b/docs/telemetry.md
index e1f56f22e5d..9c6c786e8aa 100644
--- a/docs/telemetry.md
+++ b/docs/telemetry.md
@@ -260,3 +260,36 @@ outerB()
         return telemetry.my_Metric.run(() => b(), { functionId: { name: 'aButMoreUnique' } })
     }
     ```
+
+## Tracing Telemetry Events
+
+All telemetry events include a traceId in addition to other attributes. Traceids allow for improved tracking and correlation of related events across a single operation or user flow.
+
+### What is a traceId?
+
+A traceId is a unique identifier that is generated for the top-level telemetry event in a flow and then propagated to all subsequent related events. This allows us to group and analyze all events associated with a particular operation.
+
+### How it works
+
+1. When a top-level telemetry event is created (e.g., `vscode_executeCommand`), a new traceId is generated.
+2. This traceId is then attached to all subsequent related telemetry events that occur as part of the same operation or flow.
+3. The traceId remains consistent for all events within the same flow
+
+### Example
+
+Consider a flow where `vscode_executeCommand` triggers `amazonq_enterFocusChat` and `amazonq_openChat`. The resulting telemetry events would look like this:
+
+```
+vscode_executeCommand:
+traceId: 'aaaaa-aaaaa-aaaaa-aaaaa-aaaaa'
+
+amazonq_enterFocusChat
+traceId: 'aaaaa-aaaaa-aaaaa-aaaaa-aaaaa'
+
+amazonq_openChat
+traceId: 'aaaaa-aaaaa-aaaaa-aaaaa-aaaaa'
+```
+
+allowing us to look up `traceId=aaaaa-aaaaa-aaaaa-aaaaa-aaaaa` in our telemetry instance and find all the related events.
+
+For more information visit the OpenTelemetry documentation on traces: https://opentelemetry.io/docs/concepts/signals/traces/
diff --git a/packages/core/src/shared/telemetry/spans.ts b/packages/core/src/shared/telemetry/spans.ts
index ea9816402d5..f5b6cb11667 100644
--- a/packages/core/src/shared/telemetry/spans.ts
+++ b/packages/core/src/shared/telemetry/spans.ts
@@ -343,6 +343,14 @@ export class TelemetryTracer extends TelemetryBase {
      *
      * All changes made to {@link attributes} (via {@link record}) during the execution are
      * reverted after the execution completes.
+     *
+     * This method automatically handles traceId generation and propagation:
+     * - If no traceId exists in the current context, a new one is generated.
+     * - The traceId is attached to all telemetry events created within this span.
+     * - Child spans created within this execution will inherit the same traceId.
+     * - Related concepts: https://opentelemetry.io/docs/concepts/signals/traces/
+     *
+     * See docs/telemetry.md
      */
     public run<T, U extends MetricName>(name: U, fn: (span: Metric<MetricShapes[U]>) => T, options?: SpanOptions): T {
         const initTraceId = (callback: () => T): T => {