Span File Export

Span & Log File Export

Scope (this repo)

• In scope: VS Code extension client — packages/apex-lsp-vscode-extension and code that runs in the extension host and uses the services extension / enableFileTraces (see src/observability/extensionTracing.ts).
• Out of scope for default guidance: Language server and parser packages (packages/apex-parser-ast, packages/apex-ls, etc.) — do not treat file-span export as a requirement there unless product explicitly adds tracing. Server-side LSP work stays focused on protocol and semantics.

Local OTLP export to ~/.sf/vscode-spans/ for AI consumers. Spans and log records interleaved in one JSONL file. The actual exporter and record format come from the shared @salesforce/vscode-services SDK layer (SdkLayerFor(context)), which the extension obtains from the salesforce.salesforcedx-vscode-services extension.

Choose One: OTLP vs File

• OTLP (enableLocalTraces): Grafana/Jaeger UI — for humans
• File (enableFileTraces): .jsonl on disk — for AI agents, Cursor

Use only one at a time.

Settings Required

These settings live in the shared salesforcedx-vscode-salesforcedx section provided by the services extension (not the apex section).

The extension registers an onDidChangeConfiguration listener (extensionTracing.ts) that tears down and rebuilds the tracing runtime when enableFileTraces, enableConsoleTraces, or enableLocalTraces change — so toggling these settings takes effect without a window reload. (Other SDK-layer behavior may still depend on activation; reload if a change does not take effect.)

Where It Lives

All records in one directory: ~/.sf/vscode-spans/

Filename pattern: {ISO-timestamp}.jsonl (e.g., 2026-05-22T15-33-01-398Z.jsonl)

Find latest: ls -lt ~/.sf/vscode-spans/ | head -1

Record Format

Each line is independent JSON. Discriminate on the "kind" field.

Spans (kind: "span")

{"kind":"span","traceId":"abc123","spanId":"def456","parentSpanId":"","name":"apex-language-server-extension.activate","spanKind":1,"startTimeUnixNano":"1779461510277547833","endTimeUnixNano":"1779461510278117291","attributes":{"componentCount":"5"},"events":[],"links":[],"status":{"code":1,"message":""},"resource":{"attributes":{"extension.name":"apex-language-server-extension","service.name":"apex-language-server-extension"}},"instrumentationScope":{"name":"apex-language-server-extension","version":"2026-03-02T01:00.304Z"}}

Logs (kind: "log")

{"kind":"log","timestamp":"1779463981397000000","severityText":"WARN","severityNumber":30000,"body":"UserIdNotFoundError: Could not determine user ID","traceId":"b4d710...","spanId":"706dfc...","attributes":{"fiberId":"#295"}}

Only log records at or above the configured logLevel are emitted.

Enable (Desktop)

Settings → search enableFileTraces → check, or set both in the shared salesforcedx-vscode-salesforcedx section:

{
  "salesforcedx-vscode-salesforcedx.enableFileTraces": true,
  "salesforcedx-vscode-salesforcedx.logLevel": "info"
}

Enable (Web / run:web)

Web POSTs to a local span file server when the workspace is set up for it (often via consumed salesforcedx-vscode-services and .esbuild-web-extra-settings.json). This repo does not define a spans:server script at the root, so do not assume one exists — check the workspace package.json and follow the salesforcedx-vscode-services team docs when wiring run:web + span server.

1. Start the span server only if your wireit graph includes it (see team salesforcedx-vscode-services docs when applicable; the monorepo runs it on port 3003).
2. Add to .esbuild-web-extra-settings.json at repo root (gitignored when local):

   { "salesforcedx-vscode-salesforcedx.enableFileTraces": true }
   

3. Run the web target for the extension package you are testing.

Clear

rm ~/.sf/vscode-spans/* or rm -rf ~/.sf/vscode-spans/

Trace Correlation

Logs reference the span that was active when they were emitted via traceId + spanId. To reconstruct an operation:

1. Find all spans with a given traceId
2. Build the tree using parentSpanId → children
3. Find logs with the same traceId — they belong to the span matching their spanId