feat(telemetry): client-side HTTP span + opt-in W3C traceparent propagation (#4384)

docs/developers/development/telemetry.md

@@ -262,6 +262,99 @@ and logs still carry `session.id`, and trace / log backends (Jaeger, Tempo,
 Loki, Aliyun SLS / ARMS Tracing) handle per-session slicing natively without
 cardinality pressure.
 
+### Client-side HTTP span on outbound fetch
+
+When telemetry is enabled, Qwen Code registers `UndiciInstrumentation`
+which creates a client-side HTTP span for every outbound `fetch()`
+request originated by the process — including the LLM SDKs (`openai`,
+`@google/genai`, `@anthropic-ai/sdk`), the MCP StreamableHTTP client, the
+`WebFetch` tool, and any IDE-extension out-of-process calls. The span
+lets you see network latency (TTFB / response body transfer) separately
+from upstream model processing time, which the existing
+`api.generateContent` span alone can't distinguish.
+
+These spans go to your **own** OTLP collector (or file outfile) just like
+the rest of the telemetry — they do not affect what is written onto the
+outbound HTTP request itself. Whether the W3C `traceparent` header is
+also written into the outgoing request stream is controlled by a
+**separate, security-relevant setting** documented in
+[outbound correlation](#outbound-correlation-security-relevant) below.
+
+**Feedback-loop avoidance.** OTel SDK uses `fetch` internally to upload OTLP
+data. Without protection, instrumenting `fetch` would trace those uploads,
+which would themselves be uploaded, causing an infinite loop. Qwen Code's
+undici instrumentation is configured with an `ignoreRequestHook` that skips
+URLs matching the configured `telemetry.otlpEndpoint` /
+`telemetry.otlpTracesEndpoint` / `telemetry.otlpLogsEndpoint` /
+`telemetry.otlpMetricsEndpoint` prefixes. In file-outfile mode there are no
+outbound HTTP uploads, so the hook is a no-op.
+
+## Outbound correlation (SECURITY-RELEVANT)
+
+These settings live in a **separate top-level namespace** from `telemetry.*`
+on purpose: telemetry controls data flow into the operator's own
+observability backend, while `outboundCorrelation.*` controls what
+client-side correlation data qwen-code writes **into outbound LLM API
+request streams** that reach third-party LLM provider endpoints
+(DashScope, OpenAI, Anthropic, etc.). Different recipients, different
+consent decision. **All values default to off.** See PR #4390 review
+discussion for the framing rationale.
+
+### `outboundCorrelation.propagateTraceContext`
+
+```jsonc
+"outboundCorrelation": {
+  "propagateTraceContext": false // default
+}
+```
+
+When `false` (default), Qwen Code installs a no-op `TextMapPropagator` on
+the OTel SDK. UndiciInstrumentation still creates client HTTP spans for
+your OTLP collector, but `propagation.inject()` is a no-op so **no
+`traceparent` is written onto outbound requests**. Trace IDs stay
+internal to the operator's collector.
+
+When `true`, the SDK's default W3C composite propagator
+(`tracecontext` + `baggage`) is installed and the standard `traceparent`
+header is written on every outbound `fetch`:
+
+```
+traceparent: 00-<32-hex traceId>-<16-hex parentSpanId>-<01-sampled | 00-not-sampled>
+```
+
+Opt in only when the LLM provider also reports into your OTel collector
+for cross-process trace stitching — e.g. ARMS Tracing serving DashScope.
+For most operators the value is `false`; cross-vendor trace continuation
+is niche.
+
+**Depends on `telemetry.enabled: true`.** The OTel SDK only initializes
+when telemetry is enabled, so `propagateTraceContext` only takes effect
+in that state. Setting it to `true` while telemetry is disabled is a
+silent no-op — no SDK, no propagator, no `traceparent` on the wire.
+Verify both flags when wiring an ARMS+DashScope correlation setup:
+
+```jsonc
+{
+  "telemetry": {
+    "enabled": true,
+    "otlpTracesEndpoint": "http://tracing-analysis-...",
+  },
+  "outboundCorrelation": {
+    "propagateTraceContext": true,
+  },
+}
+```
+
+### Other outbound correlation headers
+
+`X-Qwen-Code-Session-Id` and `X-Qwen-Code-Request-Id` are **not part of
+this PR**. They will be designed and proposed in their own follow-up
+PR(s) under the same `outboundCorrelation.*` namespace, each with its
+own threat model and operator-consent flow. PR #4390 review (LaZzyMan)
+established the principle: "telemetry's scope of work doesn't include
+sending identifiers to LLM providers"; correlation-header work moves to
+its own design discussion rather than landing under telemetry.
+
 ## Aliyun Telemetry
 
 ### Manual OTLP Export

packages/cli/src/config/config.ts

@@ -1710,6 +1710,7 @@ export async function loadCliConfig(
       screenReader,
     },
     telemetry: telemetrySettings,
+    outboundCorrelation: settings.outboundCorrelation,
     usageStatisticsEnabled: settings.privacy?.usageStatisticsEnabled ?? true,
     clearContextOnIdle: settings.context?.clearContextOnIdle,
     fileFiltering: settings.context?.fileFiltering,

packages/cli/src/config/settingsSchema.ts

@@ -8,6 +8,7 @@ import type {
   MCPServerConfig,
   BugCommandSettings,
   TelemetrySettings,
+  OutboundCorrelationSettings,
   AuthType,
   ChatCompressionSettings,
   ModelProvidersConfig,
@@ -1037,6 +1038,29 @@ const SETTINGS_SCHEMA = {
     },
   },
 
+  outboundCorrelation: {
+    type: 'object',
+    label: 'Outbound Correlation',
+    category: 'Advanced',
+    requiresRestart: true,
+    default: undefined as OutboundCorrelationSettings | undefined,
+    description:
+      "SECURITY-RELEVANT. Controls what client-side correlation data qwen-code writes into outbound LLM API requests (DashScope, OpenAI, Anthropic, etc.) — separate from `telemetry.*` which governs data flow into the operator's OWN OTLP collector. All values default to off. Opt in only when the LLM provider also reports into your OTel collector for cross-process trace stitching (e.g. ARMS Tracing + DashScope).",
+    showInDialog: false,
+    jsonSchemaOverride: {
+      type: 'object',
+      properties: {
+        propagateTraceContext: {
+          description:
+            "Requires `telemetry.enabled: true`. Inject W3C `traceparent` header on outbound `fetch` requests (LLM SDK calls, MCP StreamableHTTP, WebFetch, ...). Default: false — trace context stays internal to the operator's OTLP collector and is NOT written onto third-party request streams. Set true only when you want cross-process trace stitching with an OTel-aware LLM provider (e.g. ARMS+DashScope). Client HTTP spans are still emitted in either case; this flag only governs the wire `traceparent` header.",
+          type: 'boolean',
+          default: false,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+
   fastModel: {
     type: 'string',
     label: 'Fast Model',

packages/core/package.json

@@ -35,6 +35,7 @@
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
     "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/instrumentation-undici": "^0.14.0",
     "@opentelemetry/sdk-node": "^0.203.0",
     "@types/html-to-text": "^9.0.4",
     "@xterm/headless": "5.5.0",

packages/core/src/config/config.test.ts

@@ -1655,6 +1655,37 @@ describe('Server Config (config.ts)', () => {
     });
   });
 
+  describe('OutboundCorrelation Configuration', () => {
+    // Default-to-false is security-relevant — controls whether
+    // `traceparent` is written onto outbound LLM/fetch request streams.
+    it.each<{
+      label: string;
+      outboundCorrelation: ConfigParameters['outboundCorrelation'];
+      expected: boolean;
+    }>([
+      { label: 'omitted', outboundCorrelation: undefined, expected: false },
+      { label: 'empty object', outboundCorrelation: {}, expected: false },
+      {
+        label: 'explicit true',
+        outboundCorrelation: { propagateTraceContext: true },
+        expected: true,
+      },
+      {
+        label: 'explicit false',
+        outboundCorrelation: { propagateTraceContext: false },
+        expected: false,
+      },
+    ])(
+      'propagateTraceContext resolves to $expected when $label',
+      ({ outboundCorrelation, expected }) => {
+        const config = new Config({ ...baseParams, outboundCorrelation });
+        expect(config.getOutboundCorrelationPropagateTraceContext()).toBe(
+          expected,
+        );
+      },
+    );
+  });
+
   describe('UseRipgrep Configuration', () => {
     it('should default useRipgrep to true when not provided', () => {
       const config = new Config(baseParams);

packages/core/src/config/config.ts

@@ -337,6 +337,42 @@ export interface TelemetryMetricsSettings {
   includeSessionId?: boolean;
 }
 
+/**
+ * Security-relevant settings controlling what client-side correlation
+ * data qwen-code writes into outbound LLM API requests.
+ *
+ * **Why this is a separate namespace from `telemetry.*`:** telemetry
+ * controls data flow into the user's OWN observability backend (OTLP
+ * collector / file outfile). The settings here control data flow OUT of
+ * the qwen-code process and INTO third-party LLM provider request
+ * streams (DashScope, OpenAI, Anthropic, etc.). Different recipients =
+ * different consent decision, so a different settings tree. See PR
+ * #4390 review (LaZzyMan) for the framing rationale.
+ *
+ * All values default to off / no propagation. Operators who want to
+ * propagate trace context for server-side trace stitching (e.g. ARMS
+ * Tracing + DashScope) opt in explicitly.
+ */
+export interface OutboundCorrelationSettings {
+  /**
+   * Inject W3C `traceparent` header on outbound HTTP requests
+   * originated by undici / global `fetch` (LLM SDK calls, MCP
+   * StreamableHTTP clients, WebFetch tool, etc.). Default: `false`.
+   *
+   * When `false`, the SDK is configured with a no-op
+   * `TextMapPropagator` so trace context stays internal to the user's
+   * OTLP collector (operator still gets client HTTP spans, but the
+   * trace id is not written onto third-party request streams).
+   *
+   * When `true`, the OTel default W3C composite propagator
+   * (`tracecontext` + `baggage`) is installed and `traceparent` is
+   * written on every outbound `fetch`. Useful when the LLM provider
+   * also reports into the operator's OTel collector — e.g. ARMS
+   * Tracing + DashScope — for cross-process trace stitching.
+   */
+  propagateTraceContext?: boolean;
+}
+
 export interface OutputSettings {
   format?: OutputFormat;
 }
@@ -565,6 +601,7 @@ export interface ConfigParameters {
   contextFileName?: string | string[];
   accessibility?: AccessibilitySettings;
   telemetry?: TelemetrySettings;
+  outboundCorrelation?: OutboundCorrelationSettings;
   gitCoAuthor?: GitCoAuthorParam;
   usageStatisticsEnabled?: boolean;
   /**
@@ -854,6 +891,7 @@ export class Config {
   private autoModeDenialState: AutoModeDenialState = createDenialState();
   private readonly accessibility: AccessibilitySettings;
   private readonly telemetrySettings: TelemetrySettings;
+  private readonly outboundCorrelationSettings: OutboundCorrelationSettings;
   private readonly gitCoAuthor: GitCoAuthorSettings;
   private readonly usageStatisticsEnabled: boolean;
   private readonly fileReadCacheDisabled: boolean;
@@ -1022,6 +1060,10 @@ export class Config {
       metrics: params.telemetry?.metrics,
       resourceAttributeWarnings: params.telemetry?.resourceAttributeWarnings,
     };
+    this.outboundCorrelationSettings = {
+      propagateTraceContext:
+        params.outboundCorrelation?.propagateTraceContext ?? false,
+    };
     this.gitCoAuthor = {
       ...normalizeGitCoAuthor(params.gitCoAuthor),
       name: 'Qwen-Coder',
@@ -2853,6 +2895,15 @@ export class Config {
     return this.telemetrySettings.resourceAttributeWarnings ?? [];
   }
 
+  /**
+   * Whether to inject W3C `traceparent` on outbound `fetch` requests
+   * (LLM SDKs, MCP, WebFetch, etc.). Default false — see
+   * `OutboundCorrelationSettings` for rationale.
+   */
+  getOutboundCorrelationPropagateTraceContext(): boolean {
+    return this.outboundCorrelationSettings.propagateTraceContext ?? false;
+  }
+
   getTelemetryOutfile(): string | undefined {
     return this.telemetrySettings.outfile;
   }

packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.test.ts

@@ -97,6 +97,8 @@ describe('AnthropicContentGenerator', () => {
     mockConfig = {
       getCliVersion: vi.fn().mockReturnValue('1.2.3'),
       getProxy: vi.fn().mockReturnValue(undefined),
+      getTelemetryEnabled: vi.fn().mockReturnValue(false),
+      getSessionId: vi.fn().mockReturnValue('test-session'),
     } as unknown as Config;
   });
 

packages/core/src/core/contentGenerator.test.ts

@@ -22,6 +22,8 @@ describe('createContentGenerator', () => {
       getUsageStatisticsEnabled: () => true,
       getContentGeneratorConfig: () => ({}),
       getCliVersion: () => '1.0.0',
+      getTelemetryEnabled: () => false,
+      getSessionId: () => 'test-session',
     } as unknown as Config;
 
     const mockGenerator = {
@@ -57,6 +59,8 @@ describe('createContentGenerator', () => {
       getUsageStatisticsEnabled: () => false,
       getContentGeneratorConfig: () => ({}),
       getCliVersion: () => '1.0.0',
+      getTelemetryEnabled: () => false,
+      getSessionId: () => 'test-session',
     } as unknown as Config;
     const mockGenerator = {
       models: {},

packages/core/src/core/geminiContentGenerator/index.test.ts

@@ -23,6 +23,8 @@ describe('createGeminiContentGenerator', () => {
       getUsageStatisticsEnabled: vi.fn().mockReturnValue(false),
       getContentGeneratorConfig: vi.fn().mockReturnValue({}),
       getCliVersion: vi.fn().mockReturnValue('1.0.0'),
+      getTelemetryEnabled: vi.fn().mockReturnValue(false),
+      getSessionId: vi.fn().mockReturnValue('test-session'),
     } as unknown as Config;
   });