mirror of
https://github.com/QwenLM/qwen-code.git
synced 2026-07-09 17:19:02 +00:00
docs(design): reflect post-R4 polish commits in §12
R4 (commit9bdd3bd6f) was followed by two polish commits that the design doc §12 didn't track: -0be0df270(docs): telemetry.enabled dependency disclosure on propagateTraceContext — added to telemetry.md + settingsSchema description because a self-review pass identified the silent-no-op footgun (operator sets propagateTraceContext: true but forgets telemetry.enabled: true, sees zero behavior change with no error). -c0352fd5b(test): 4 config.test.ts cases covering the getOutboundCorrelationPropagateTraceContext default-false invariant (omitted / {} / explicit true / explicit false) — wenshao review flagged the test gap. Updates §12.4 with a new "Hidden dependency: telemetry.enabled" sub- section explaining the gating relationship and pointing forward at the follow-up PR (future outboundCorrelation.* settings inherit the same dependency). Updates §12.5 implementation table to add the config.test.ts row and clarify the telemetry.md / vscode-schema rows were touched again in the polish pass. 🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)
This commit is contained in:
doudouOUC
parent
c0352fd5b5
commit
62cf6b4ee7
1 changed files with 31 additions and 19 deletions
|
|
@ -824,27 +824,39 @@ R3 化解了 LaZzyMan 第一轮 review 的「广播稳定指纹给第三方 prov
|
|||
- **defaults 全部 off**：符合 LazzyMan 提出的"open-source 客户端不应未经显式同意向第三方发稳定 id"原则
|
||||
- **与 telemetry.\* 解耦**：用户读 settings.json 看到 `outboundCorrelation.*` 立刻能识别这是出站 wire 行为，不是 observability
|
||||
|
||||
#### 隐性依赖：`telemetry.enabled`（已显式文档化）
|
||||
|
||||
虽然 namespace 与 `telemetry.*` 解耦，但 **`propagateTraceContext: true` 的运行时生效依赖 `telemetry.enabled: true`** —— 因为 OTel SDK 只在 telemetry 启用时初始化，没有 SDK 就没有 propagator 安装、没有 `propagation.inject()` 调用，flag 等于沉默 no-op。这是 self-review 阶段识别出的 footgun（运营商加 `propagateTraceContext: true` 却忘开 telemetry，trap server 上看不到任何 `traceparent`，无 error / 无 warning）。
|
||||
|
||||
修复（post-R4 commit `0be0df270`）：两个面板都加显式说明：
|
||||
|
||||
- `docs/developers/development/telemetry.md` 在 `propagateTraceContext` 段加 "Depends on `telemetry.enabled: true`" 提示 + 完整 JSON 示例
|
||||
- `packages/cli/src/config/settingsSchema.ts` 的 description string 末尾追加同义警示
|
||||
|
||||
未来若添加 session-id header 或其他 `outboundCorrelation.*` setting，**同一依赖关系适用** —— 都得在 telemetry 启用前提下才有意义（因为它们都通过 OTel instrumentation/SDK 注入）。Follow-up PR 应继承此 footgun 提示模式。
|
||||
|
||||
### 12.5 实施
|
||||
|
||||
| 文件 | 改动 |
|
||||
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/trusted-llm-hosts.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/trusted-llm-hosts.test.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/sdk.ts` | + `NoopTextMapPropagator`；按 `getOutboundCorrelationPropagateTraceContext()` 决定 SDK textMapPropagator |
|
||||
| `packages/core/src/core/openaiContentGenerator/provider/default.ts` | 移除 `wrapFetchWithCorrelation` 引用 |
|
||||
| `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` | 同上 |
|
||||
| `packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts` | 同上 |
|
||||
| `packages/core/src/core/geminiContentGenerator/index.ts` | 移除 `staticCorrelationHeaders` 引用 |
|
||||
| 上述 4 个 provider 的 `*.test.ts` | 删 session-id 相关测试 case |
|
||||
| `packages/core/src/config/config.ts` | 删 `TelemetrySettings.sessionIdHeaderHosts`、`getTelemetrySessionIdHeaderHosts`；**新增 `OutboundCorrelationSettings` 接口 + `outboundCorrelationSettings` 字段 + `getOutboundCorrelationPropagateTraceContext()` getter** |
|
||||
| `packages/core/src/telemetry/config.ts` | 删 `resolveTelemetrySettings` 中 sessionIdHeaderHosts 透传 |
|
||||
| `packages/cli/src/config/settingsSchema.ts` | 删 `sessionIdHeaderHosts` schema；**新增 `outboundCorrelation` 顶级 schema 项** |
|
||||
| `packages/cli/src/config/config.ts` | 透传 `outboundCorrelation: settings.outboundCorrelation` 进 `ConfigParameters` |
|
||||
| `packages/vscode-ide-companion/schemas/settings.schema.json` | `npm run generate:settings-schema` 重新生成 |
|
||||
| `docs/developers/development/telemetry.md` | 重写 "Trace context propagation" → "Client-side HTTP span on outbound fetch"；删 "Session correlation header" 整节；新增 "Outbound correlation (SECURITY-RELEVANT)" 顶级 section |
|
||||
| `docs/design/telemetry-outbound-propagation-design.md` | 本节 + R4 表头 + 修订指针 |
|
||||
| 文件 | 改动 |
|
||||
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/trusted-llm-hosts.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/trusted-llm-hosts.test.ts` | **删除** |
|
||||
| `packages/core/src/telemetry/sdk.ts` | + `NoopTextMapPropagator`；按 `getOutboundCorrelationPropagateTraceContext()` 决定 SDK textMapPropagator |
|
||||
| `packages/core/src/core/openaiContentGenerator/provider/default.ts` | 移除 `wrapFetchWithCorrelation` 引用 |
|
||||
| `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` | 同上 |
|
||||
| `packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts` | 同上 |
|
||||
| `packages/core/src/core/geminiContentGenerator/index.ts` | 移除 `staticCorrelationHeaders` 引用 |
|
||||
| 上述 4 个 provider 的 `*.test.ts` | 删 session-id 相关测试 case |
|
||||
| `packages/core/src/config/config.ts` | 删 `TelemetrySettings.sessionIdHeaderHosts`、`getTelemetrySessionIdHeaderHosts`；**新增 `OutboundCorrelationSettings` 接口 + `outboundCorrelationSettings` 字段 + `getOutboundCorrelationPropagateTraceContext()` getter** |
|
||||
| `packages/core/src/telemetry/config.ts` | 删 `resolveTelemetrySettings` 中 sessionIdHeaderHosts 透传 |
|
||||
| `packages/cli/src/config/settingsSchema.ts` | 删 `sessionIdHeaderHosts` schema；**新增 `outboundCorrelation` 顶级 schema 项** |
|
||||
| `packages/cli/src/config/config.ts` | 透传 `outboundCorrelation: settings.outboundCorrelation` 进 `ConfigParameters` |
|
||||
| `packages/vscode-ide-companion/schemas/settings.schema.json` | `npm run generate:settings-schema` 重新生成（post-R4 commit `0be0df270` 内再次重生成，反映 description 更新） |
|
||||
| `docs/developers/development/telemetry.md` | 重写 "Trace context propagation" → "Client-side HTTP span on outbound fetch"；删 "Session correlation header" 整节；新增 "Outbound correlation (SECURITY-RELEVANT)" 顶级 section；post-R4 commit `0be0df270` 追加 telemetry.enabled 依赖说明 + JSON 配置示例 |
|
||||
| `docs/design/telemetry-outbound-propagation-design.md` | 本节 + R4 表头 + 修订指针 |
|
||||
| `packages/core/src/config/config.test.ts` (post-R4, commit `c0352fd5b`) | **新增 `OutboundCorrelation Configuration` describe block**，4 个 case 锁定 `getOutboundCorrelationPropagateTraceContext` 的 default-false 安全不变性（omitted / `{}` / explicit true / explicit false） |
|
||||
|
||||
### 12.6 对 LazzyMan 元论点的回应
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue