Sending traces

How to point your agent or LLM app at Spancache. The short version: there is no SDK to install. Spancache speaks OpenTelemetry (OTLP/HTTP), so any tool that is already OpenTelemetry-instrumented — which is most of the agent ecosystem — ships its traces to us by setting a few environment variables. Standards-based, no vendor lock-in, nothing to get through a security review.

The endpoint


URL	`https://ingest.spancache.ai/v1/traces`
Protocol	OTLP/HTTP, JSON (`http/json`)
Auth	`Authorization: Bearer <YOUR_INGEST_TOKEN>`
Token	from your workspace → Overview → Ingest token (per-tenant; rotate anytime)

We also accept OTLP logs at /v1/logs (agent events and the provider’s own cost figure ride here).

What to collect — metadata vs. content

Pick deliberately; it is the single most important governance choice.

Metadata only (recommended, the default). Cost, tokens (incl. cache), latency, TTFT, model, tools, outcomes, errors, trace structure. No prompt or response text ever leaves your side. Safe for regulated data, and it powers every chart, detection and cost report in Spancache.
+ Prompts & responses (opt-in). Adds the conversation content so you can read a specific trace. Everything captured is scrubbed for secrets at ingest — API keys (sk-…, sk-ant-…, AWS AKIA…), bearer/HTTP-auth tokens, JWTs, GitHub/Slack tokens and PEM private keys are replaced with [REDACTED] before anything is written. For regulated workloads, prefer metadata-only.

The analytics never need content — it is purely for human debugging of a single run.

Recipes

Claude Code

Add to ~/.claude/settings.json under "env" (applies to every session), or export before launch:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1          # traces (beta)
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.spancache.ai
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"
# + content (optional): export OTEL_LOG_USER_PROMPTS=1 OTEL_LOG_ASSISTANT_RESPONSES=1

Claude Code appends /v1/traces and /v1/logs to the base endpoint itself. Telemetry applies to sessions started after the config is set.

Any OpenTelemetry app

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.spancache.ai/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"
export OTEL_TRACES_EXPORTER=otlp

Python — OpenAI / Anthropic SDK, LangChain, LlamaIndex, CrewAI

Use the GenAI instrumentation (OpenLLMetry); it turns LLM calls, tool calls and chains into spans with gen_ai.* token attributes that Spancache prices automatically.

pip install opentelemetry-distro opentelemetry-exporter-otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.spancache.ai/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"
opentelemetry-instrument python your_agent.py
# + content (optional): export TRACELOOP_TRACE_CONTENT=true

Node / TypeScript — Vercel AI SDK, LangChain.js

npm i @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/auto-instrumentations-node
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.spancache.ai/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"
node --require @opentelemetry/auto-instrumentations-node/register your_agent.js

(The Vercel AI SDK emits OTel spans natively when experimental_telemetry is enabled; point the same exporter at the endpoint.)

cURL — smoke test

curl -s https://ingest.spancache.ai/v1/traces \
  -H "Authorization: Bearer <YOUR_INGEST_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name",
    "value":{"stringValue":"demo-agent"}}]},"scopeSpans":[{"spans":[{"name":"chat",
    "traceId":"5b8efff798038103d269b633813fc60c","spanId":"eee19b7ec3c1b174",
    "attributes":[{"key":"gen_ai.request.model","value":{"stringValue":"claude-opus-4-8"}},
    {"key":"gen_ai.usage.input_tokens","value":{"intValue":1200}},
    {"key":"gen_ai.usage.output_tokens","value":{"intValue":800}}]}]}]}]}'

Expect HTTP 200 and {"partialSuccess":{},"accepted":1}. The span appears in Traces within seconds, priced from its tokens.

Verifying

Open the trace console (Open Search from your workspace).
In Traces you should see your agent runs, one row per trace, with cost and duration.
In Cost you get per-model and per-version rollups; in Detections → Templates you can enable guardrails (runaway spend, tool-error loops, …) in one click.

Notes

Do you need a Spancache SDK? No. If a future source speaks only a non-OTLP format, tell us — we also accept OTLP logs and can map common shapes — but the supported, recommended path is OTLP.
Token → tenant. Your ingest token routes every span to your isolated store. Keep it out of source control (use an env var or secret manager); rotate it from the workspace if exposed.
Pricing is computed from tokens at list price (cache-aware), so even sources that do not report a cost get accurate per-call spend. See cost.md.