Agent skill

Span File Export

by forcedotcom in forcedotcom/salesforcedx-vscode

Use file-based span/log export for AI consumption. An agent skill from forcedotcom/salesforcedx-vscode.

BSD-3-ClauseAuto-check passedDevOps & Cloud

Install Span File Export

skills CLI
$ npx skills add forcedotcom/salesforcedx-vscode --skill span-file-export -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install forcedotcom/salesforcedx-vscode span-file-export --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/forcedotcom/salesforcedx-vscode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/span-file-export .claude/skills/span-file-export && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
span-file-export
GitHub stars
1k
Token cost
~2.2k tokens
SKILL.md length
632 words
Files
1
Skills in repo
37
Repo updated
First seen
Licence
BSD-3-Clause

At a glance

Use file-based span/log export for AI consumption. An agent skill from forcedotcom/salesforcedx-vscode.

  • Works in 3 steps: npm run spans:server -w… → Add to .esbuild-web-extra-settings.json… → npm run run:web -w packages/
  • Enabling span file dump
  • SKILL.md covers Settings, Location, Record Format and Enable (Desktop), plus 3 more sections
  • Calls npm and jq

What it does

Span File Export is an agent skill from forcedotcom/salesforcedx-vscode. Use file-based span/log export for AI consumption. Where it lives, how to enable/clear, record format for Node and Web. Use when enabling span file dump, debugging traces for AI, or configuring local observability.

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in DevOps & Cloud, covering Observability. It works with Visual Studio Code and OpenTelemetry. The repository describes itself as: Salesforce Extensions for VS Code. The licence is BSD-3-Clause.

When your agent uses it

  • Enabling span file dump
  • Debugging traces for AI
  • Configuring local observability

Example prompts

  • “/span-file-export”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. npm run spans:server -w salesforcedx-vscode-services
  2. Add to .esbuild-web-extra-settings.json at repo root (gitignored)
  3. npm run run:web -w packages/

What it can do on your machine

Read from SKILL.md and the folder at commit 27807f6. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm
    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Span File Export loads about 2.2k tokens when it runs. Until then it costs about 58 tokens; SKILL.md has 632 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~58
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from forcedotcom/salesforcedx-vscode at commit 27807f6, republished under its BSD-3-Clause licence (© forcedotcom). 632 words, ~2,203 tokens.

Download SKILL.mdSave it as .claude/skills/span-file-export/SKILL.md (or your agent's skills folder).
name
span-file-export
description
Use file-based span/log export for AI consumption. Where it lives, how to enable/clear, record format for Node and Web. Use when enabling span file dump, debugging traces for AI, or configuring local observability.
review
never

Span & Log File Export

Local OTLP export to ~/.sf/vscode-spans/ for AI consumers. Spans + log records interleaved in one JSONL file.

Settings

SettingDefaultPurpose
salesforcedx-vscode-salesforcedx.enableFileTracesfalseEnable file capture (spans + logs)
salesforcedx-vscode-salesforcedx.logLevelerrorMin log level exported. info/debug for most logs.
SF_LOG_LEVEL env var—Fallback when setting unset (fatal→error)

Reload window after changing — SDK layer builds at activation.

Location

Dir: ~/.sf/vscode-spans/. Filename: {ISO-timestamp}.jsonl (e.g. 2026-05-22T15-33-01-398Z.jsonl).

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

Record Format

Each line independent JSON. Discriminate on kind.

Spans (kind: "span")
jsonl
{"kind":"span","traceId":"abc123","spanId":"def456","parentSpanId":"","name":"ConnectionService.getConnection","spanKind":1,"startTimeUnixNano":"1779461510277547833","endTimeUnixNano":"1779461510278117291","attributes":{"orgId":"00D..."},"events":[],"links":[],"status":{"code":1,"message":""},"resource":{"attributes":{"extension.name":"salesforcedx-vscode-core","service.name":"salesforcedx-vscode-core"}},"instrumentationScope":{"name":"salesforcedx-vscode-core","version":"2026-03-02T01:00.304Z"}}
FieldNotes
parentSpanId: ""Root span
status.code1=OK, 2=ERROR
spanKindOTEL SpanKind +1 (1=INTERNAL, 2=SERVER, 3=CLIENT)
resource.attributes["extension.name"]Emitting extension
Duration (ms)(endTimeUnixNano - startTimeUnixNano) / 1_000_000

Identity attrs (userId, cliId, webUserId, orgId, common.*) stamped only on root spans — child spans have them null; not a gap. Mirrors the App Insights properties exactly. userId absent for expired/unauthenticated orgs. Note: an internal diagnostic child span (maybeUpdateDefaultOrgRef) annotates the literal string "undefined" when SOQL userId is unresolved — that string never reaches exported root spans (filtered out).

sh
f=$(ls -t ~/.sf/vscode-spans/*.jsonl | head -1)
jq -rc 'select(.kind=="span" and .parentSpanId=="") | {name, userId:.attributes.userId, cliId:.attributes.cliId, webUserId:.attributes.webUserId, orgId:.attributes.orgId}' "$f" | sort -u
Logs (kind: "log")
jsonl
{"kind":"log","timestamp":"1779463981397000000","severityText":"WARN","severityNumber":30000,"body":"UserIdNotFoundError: Could not determine user ID","traceId":"b4d710...","spanId":"706dfc...","attributes":{"fiberId":"#295"}}
FieldNotes
traceId + spanIdSpan active when log emitted
severityTextINFO, WARN, ERROR (filtered by logLevel)
bodyString or array (multiple args)
timestampNanos since epoch

Enable (Desktop)

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

Hosted Web Console cannot write this dir. Local OTLP (enableLocalTraces → :4318) → web-console-local-traces.

Enable (Web / run:web)

Web POSTs to local span file server (port 3003). Server must run.

  1. npm run spans:server -w salesforcedx-vscode-services
  2. Add to .esbuild-web-extra-settings.json at repo root (gitignored):
    json
    { "salesforcedx-vscode-salesforcedx.enableFileTraces": true }
  3. npm run run:web -w packages/<extension>

App Insights Telemetry Capture

Inspect App Insights telemetry each platform would send to Azure — captured locally, never sent. Output: ~/.sf/vscode-appinsights/ (separate from spans), via same server (port 3003).

PlatformTriggerExporterEndpointFile prefix
Desktop (Node)Dev/Test mode (auto); custom port via SF_OTEL_INGESTION_ENDPOINTAzure Monitor/v2.1/trackappinsights-
WebESBUILD_WEB_LOCAL=1 (auto under run:web)@vscode/extension-telemetry/v2.1/trackappinsights-web-

Start server first: npm run spans:server -w salesforcedx-vscode-services

Show full SKILL.md (328 more words)Show less
Desktop (Node)

Extension via --extensionDevelopmentPath (F5, vscode-test, Playwright desktop e2e) = ExtensionMode.Development/Test, which auto-diverts App Insights to http://localhost:3003/v2.1/track — no env var or setting. Telemetry force-enabled (provably can't reach Azure).

Custom port: SF_OTEL_INGESTION_ENDPOINT=http://localhost:NNNN.

Divert Mechanism: Connection string stays pristine. Both FilteredAzureMonitorTraceExporter (dependencies path) and ApplicationInsightsNodeExporter (customEvents path) swap their private HTTP transport to POST Breeze envelopes over plain HTTP to {localIngestionEndpoint}/v2.1/track. Why swap transport? The Azure SDK's ConnectionStringParser.sanitizeUrl force-upgrades http:// → https://, blocking plain-HTTP localhost servers.

Server gzip-decompresses, writes raw Breeze envelopes (exact wire format Azure receives). Top-level keys: name, time, instrumentationKey, sampleRate, tags, version, data. No iKey, no target. Custom dimensions (IDs, common.*) live in data.baseData.properties, NOT directly under baseData:

jsonl
{"name":"Microsoft.ApplicationInsights.RemoteDependency","time":"2026-06-15T15:44:24.223Z","instrumentationKey":"f5cbbeba-...","sampleRate":100,"version":1,"tags":{"ai.cloud.role":"salesforcedx-vscode-core","ai.operation.id":"f2da4484..."},"data":{"baseType":"RemoteDependencyData","baseData":{"name":"ConnectionService.getConnection","id":"1250a85f...","success":true,"resultCode":"0","duration":"00:00:00.001","properties":{"common.extname":"salesforcedx-vscode-core","cliId":"00d6...","webUserId":"701b...","userId":"005..."},"measurements":{}}}}

Filename: appinsights-{ISO-timestamp}.jsonl. data.baseType: RemoteDependencyData (span path), MetricData, ExceptionData, or EventData (customEvents path).

FieldNotes
instrumentationKeyconnection key (NOT iKey)
tags["ai.cloud.role"]emitting extension
data.baseData.propertiescustom dimensions: cliId, webUserId, userId, common.*, telemetryTag

Identity lands only on root spans (spanTransformProcessor gates on !span.parentSpanContext) → most envelopes/spans lack IDs; that's expected, not a gap. userId (SOQL-derived) is absent until an org is authenticated and the query resolves; absent for expired orgs. cliId/webUserId are install-stable, present once seedTelemetryIdentities runs at activation — activation spans firing before that seeding are bare.

customEvents path (EventData, via ApplicationInsightsNodeExporter) only emits when an extension's packageJSON sets enableCustomEventsFromSpans. None do today — so only the dependencies path (RemoteDependencyData) appears.

Useful queries:

sh
g=$(ls -t ~/.sf/vscode-appinsights/*.jsonl | head -1)
jq -rc '.data.baseType' "$g" | sort | uniq -c                                  # envelope mix
jq -rc 'select(.data.baseType=="RemoteDependencyData") | {name:.data.baseData.name, role:.tags["ai.cloud.role"], userId:.data.baseData.properties.userId, cliId:.data.baseData.properties.cliId, webUserId:.data.baseData.properties.webUserId}' "$g"
Web

npm run run:web builds via vscode:bundle:local, setting ESBUILD_WEB_LOCAL=1 — web exporter POSTs to http://localhost:3003/v2.1/track (shared Node endpoint). (SF_OTEL_INGESTION_ENDPOINT has no effect on web: connection string hard-coded.)

Payload is not Breeze — it's the @vscode/extension-telemetry shape:

jsonl
{"name":"ConnectionService.getConnection","eventType":"event","properties":{"orgId":"00D...","common.extname":"salesforcedx-vscode-core"},"measurements":{"duration":42}}

Filename: appinsights-web-{ISO-timestamp}.jsonl. eventType: event (success) or errorEvent (failed span).

Workflow
  1. npm run spans:server -w salesforcedx-vscode-services
  2. Desktop: launch extension in dev/test mode (auto). Web: npm run run:web -w packages/<extension> (auto).
  3. Trigger commands/spans
  4. View: cat ~/.sf/vscode-appinsights/*.jsonl | jq '.' | less
Clear

rm ~/.sf/vscode-appinsights/*

Trace Correlation

Logs reference active span via traceId + spanId. Reconstruct:

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

© forcedotcom, BSD-3-Clause. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/span-file-export of forcedotcom/salesforcedx-vscode.

Open the folder on GitHubat commit 27807f6

Compare with similar skills

Span File Export next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Span File Export compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Span File Export this skillforcedotcom/salesforcedx-vscode1k—~2.2kAutomated safety check: PassBSD-3-Clause
Motel Debugkitlangton/motel298—~2.2kAutomated safety check: PassMIT
Aspire Service DefaultsAaronontheweb/dotnet-skills1.2k1 repos~2.6kAutomated safety check: PassMIT
Sentry Advanced Troubleshootingjeremylongshore/tons-of-skills-marketplace2.8k—~3.7kAutomated safety check: PassMIT
Tempsgotempsh/temps826—~1.9kAutomated safety check: PassApache-2.0
UModel Root Cause Analysisalibaba/UnifiedModel412—~1.9kAutomated safety check: PassCustom licence

Similar skills

  • Motel Debug

    kitlangton/motel

    Debug applications with motel, a local OpenTelemetry ingest and query server.

    298 GitHub stars~2.2k tokensUpdated 1 mo ago
    DevOps & CloudAuto-check passed
  • Aspire Service Defaults

    Aaronontheweb/dotnet-skills

    Sets up a shared ServiceDefaults project for .NET Aspire apps that centralizes OpenTelemetry, health checks, HTTP resilience and service discovery for every service.

    1.2k GitHub starsUsed in 1 repo~2.6k tokens
    DevOps & CloudAuto-check passed
  • Sentry Advanced Troubleshooting

    jeremylongshore/tons-of-skills-marketplace

    Advanced Sentry troubleshooting for complex SDK issues, silent event drops, source map failures, distributed tracing gaps, and SDK conflicts.

    2.8k GitHub stars~3.7k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Temps

    gotempsh/temps

    Manage, deploy, operate, and instrument applications with Temps.

    826 GitHub stars~1.9k tokensUpdated today
    DevOps & CloudAuto-check passed
  • UModel Root Cause Analysis

    alibaba/UnifiedModel

    Investigates a service incident to its root cause by querying a UModel object graph alongside metrics, logs, topology and recent deployments.

    412 GitHub stars~1.9k tokensUpdated 14 days ago
    DevOps & CloudAuto-check passed
  • Agent Kill Switch

    vivekchand/clawmetry

    Give the human an off switch and a cost meter for the coding agents on this machine, using ClawMetry.

    425 GitHub stars~1.1k tokensUpdated today
    DevOps & CloudAuto-check passed

More from forcedotcom/salesforcedx-vscode

All 37 skills in this repo
  • Command UI

    forcedotcom/salesforcedx-vscode

    Command palette, CodeLens, context menus, package.nls titles, and NotificationModeService.

    1k GitHub stars~1.4k tokensUpdated today
    Auto-check passed
  • Services Extension Consumption

    forcedotcom/salesforcedx-vscode

    Consume the salesforcedx-vscode-services extension API. An agent skill from forcedotcom/salesforcedx-vscode.

    1k GitHub stars~5k tokensUpdated today
    Auto-check passed
  • Changelog

    forcedotcom/salesforcedx-vscode

    Polish the automated CHANGELOG on develop before the next stable build.

    1k GitHub stars~3.3k tokensUpdated today
    Auto-check passed
  • Core Extension API

    forcedotcom/salesforcedx-vscode

    Public API exported by salesforcedx-vscode-core activate(). An agent skill from forcedotcom/salesforcedx-vscode.

    1k GitHub stars~842 tokensUpdated today
    Auto-check passed
  • Drivable Vscode

    forcedotcom/salesforcedx-vscode

    Operate a real VS Code instance through drivable-vscode. An agent skill from forcedotcom/salesforcedx-vscode.

    1k GitHub stars~1k tokensUpdated today
    Auto-check passed
  • Effect Best Practices

    forcedotcom/salesforcedx-vscode

    Enforces Effect-TS patterns for services, errors, layers, atoms, and Effect.pipe composition.

    1k GitHub stars~6.2k tokensUpdated today
    Auto-check passed

Questions about Span File Export

What does Span File Export do?

Use file-based span/log export for AI consumption. An agent skill from forcedotcom/salesforcedx-vscode. Span File Export is an agent skill from forcedotcom/salesforcedx-vscode. Use file-based span/log export for AI consumption.

When should I use Span File Export?

Span File Export fits situations like: enabling span file dump; debugging traces for AI; configuring local observability.

How do I install Span File Export in Claude Code?

Run `npx skills add forcedotcom/salesforcedx-vscode --skill span-file-export -a claude-code`. Or copy the skill folder (.claude/skills/span-file-export in forcedotcom/salesforcedx-vscode) into .claude/skills/span-file-export in your project. Claude Code loads it when a task matches its description.

How do I install Span File Export in Codex?

Run `npx skills add forcedotcom/salesforcedx-vscode --skill span-file-export -a codex`. Or copy the skill folder (.claude/skills/span-file-export in forcedotcom/salesforcedx-vscode) into .agents/skills/span-file-export in your project. Codex loads it when a task matches its description.

Can I use Span File Export in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add forcedotcom/salesforcedx-vscode --skill span-file-export -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/span-file-export, .gemini/skills/span-file-export, .github/skills/span-file-export and .opencode/skills/span-file-export in your project.

What does Span File Export need to run?

Going by SKILL.md and its folder, Span File Export needs the command-line tools its instructions call (npm and jq).

Does Span File Export access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Span File Export safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Span File Export use?

Span File Export is published under the BSD-3-Clause licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Span File Export use?

About 2.2k tokens (SKILL.md is roughly 8.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Span File Export?

Skills that share tags, products or a category with Span File Export: Motel Debug (kitlangton/motel, 298 stars), Aspire Service Defaults (Aaronontheweb/dotnet-skills, 1.2k stars), Sentry Advanced Troubleshooting (jeremylongshore/tons-of-skills-marketplace, 2.8k stars) and Temps (gotempsh/temps, 826 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Span File Export?

forcedotcom (a GitHub organization) maintains it in forcedotcom/salesforcedx-vscode, which has 1,035 GitHub stars. The repository holds 37 skills in this directory. The repository was last updated on October 8, 2026.

Source: forcedotcom/salesforcedx-vscode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.