用途：在 VS Code 扩展客户端（packages/apex-lsp-vscode-extension，扩展宿主内代码）中启用基于文件的 span/日志导出，把追踪记录写入本地磁盘，供 AI 代理消费。语言服务器与解析器包不在默认范围内。
主要能力：本地 OTLP 导出到 ~/.sf/vscode-spans/，span 与日志记录交错写入同一个 JSONL 文件。导出器与记录格式来自共享的 @salesforce/vscode-services SDK 层（SdkLayerFor(context)），由 salesforce.salesforcedx-vscode-services 扩展提供。
OTLP 与文件二选一：enableLocalTraces 面向 Grafana/Jaeger 等人类界面；enableFileTraces 生成磁盘 .jsonl，面向 AI 代理。同一时间只用一种。
必要设置（位于共享的 salesforcedx-vscode-salesforcedx 段，非 apex 段）：salesforcedx-vscode-salesforcedx.enableFileTraces 默认 false，开启文件捕获；salesforcedx-vscode-salesforcedx.logLevel 默认 error，设为 info 或 debug 可看到更多日志；SF_LOG_LEVEL 环境变量在 VS Code 设置未设时作为回退（fatal 映射为 error）。扩展注册 onDidChangeConfiguration 监听器，切换 enableFileTraces、enableConsoleTraces 或 enableLocalTraces 时重建追踪运行时，无需重载窗口；其他 SDK 层行为可能仍依赖激活，未生效时重载。
文件位置：全部记录在同一目录 ~/.sf/vscode-spans/，文件名模式 {ISO-timestamp}.jsonl。查找最新：ls -lt ~/.sf/vscode-spans/ | head -1。
记录格式：每行独立 JSON，用 kind 字段区分。span 记录含 traceId、spanId、parentSpanId（空为根 span）、name、spanKind（OTEL SpanKind 枚举 +1）、startTimeUnixNano、endTimeUnixNano、attributes、events、links、status（code 1=OK，2=ERROR）、resource.attributes["extension.name"]、instrumentationScope；时长毫秒为 (endTimeUnixNano - startTimeUnixNano) / 1_000_000。log 记录含 timestamp（纳秒）、severityText、severityNumber、body（字符串或数组）、traceId、spanId、attributes；仅输出达到或高于 logLevel 的日志。
启用（桌面）：设置中搜索 enableFileTraces 勾选，或在共享段设置 enableFileTraces 为 true、logLevel 为 info。
启用（Web / run:web）：工作区配置好后，Web 会 POST 到本地 span 文件服务器（常通过 salesforcedx-vscode-services 与 .esbuild-web-extra-settings.json）。本仓库根目录未定义 spans:server 脚本，不要假定存在；请查看工作区 package.json 并遵循 salesforcedx-vscode-services 团队文档。仅当 wireit 图包含时才启动 span 服务器（monorepo 在端口 3003 运行）。在仓库根 .esbuild-web-extra-settings.json 添加 {"salesforcedx-vscode-salesforcedx.enableFileTraces": true}，再运行所测扩展包的 web 目标。
清除：rm ~/.sf/vscode-spans/* 或 rm -rf ~/.sf/vscode-spans/。
追踪关联：日志通过 traceId + spanId 引用发出时活动的 span。重建操作：找出同一 traceId 的所有 span；用 parentSpanId → 子节点构建树；找出同一 traceId 的日志，它们属于 spanId 匹配的 span。
限制：仅覆盖扩展客户端；服务器端 LSP 工作仍聚焦协议与语义，除非产品明确加入追踪。