Frequently asked questions
Each answer is short and links the page that holds the details.
Getting started
Section titled “Getting started”Is there a hosted version of Spanlight?
Section titled “Is there a hosted version of Spanlight?”No. Spanlight is open source and you run it yourself with Docker Compose or on Railway; see Self-hosting. The live demo at https://spanlight.dev shows the product with sample data, and you need nothing installed to try it. Your own server can also show the live demo, a shared read-only workspace, once you turn the demo on.
Which languages work?
Section titled “Which languages work?”The Python SDK covers Python and the TypeScript SDK covers Node.js. From any other language you can send traces over OTLP, or point an OpenAI-style or Anthropic client at the gateway, as the JavaScript and cURL examples in OpenAI and Anthropic show. Ways to send data compares them.
Should I use port 8000 or 8080?
Section titled “Should I use port 8000 or 8080?”Docker Compose serves Spanlight on http://localhost:8080, and the API you start with uvicorn for development listens on http://localhost:8000. The SDK defaults to port 8000, so with Compose set SPANLIGHT_HOST to the 8080 address; see The SDK points at the wrong host.
Does the SDK slow my app down?
Section titled “Does the SDK slow my app down?”Recording a span only adds it to an in-memory queue, and a background thread sends the queue in batches, so tracing never waits on the network. The flush at exit can wait up to the shutdown timeout (5 seconds by default), and fetching a prompt is a network call; see The Python SDK for the batch size, the queue bound and what happens when delivery fails. The gateway is different because it sits in the request path; see The gateway.
Data and privacy
Section titled “Data and privacy”Where is my data stored, and for how long?
Section titled “Where is my data stored, and for how long?”Traces, spans and the job queue are in your own Postgres database, the only database Spanlight needs; see Self-hosting. Exports and backups go to an S3-compatible object store that you configure; see Exports and Backups. A project keeps its traces for 30 days by default, and you can set 1 to 90 days; see Set the retention period and Limits.
Can I stop prompts and completions from being stored?
Section titled “Can I stop prompts and completions from being stored?”Yes. Turn off Capture prompts & completions in the project settings and spans are stored without their input and output. Known secret patterns are redacted before a span is stored, but that is a safety net, not a guarantee, so turning capture off is the sure way to keep a payload out; see Privacy.
Why does a cost show a dash?
Section titled “Why does a cost show a dash?”The cost is unknown, which is not the same as zero. A span is priced only when it has a model, both token counts and a matching price; see When a cost is unknown.
Is the cost the same as my provider invoice?
Section titled “Is the cost the same as my provider invoice?”No. It is an estimate from your own token counts and a dated price table that leaves out batch discounts, regional modifiers, server-tool fees and taxes; see The price table is versioned. You can add your own rate for a model with a price override.
Integrations
Section titled “Integrations”Does it work with OpenInference?
Section titled “Does it work with OpenInference?”Yes, since 2026-10. Send the OpenInference spans over OTLP. Spanlight reads the llm.* attributes for the model, the token counts and the messages, and input.value and output.value when there are no messages, so an OpenInference span gets its cost like any other. OpenInference shows the tested setup for the OpenAI and LangChain instrumentations, and OTLP compatibility what each exporter captures and loses.
Does it work with the Vercel AI SDK?
Section titled “Does it work with the Vercel AI SDK?”Yes, over OTLP with the AI SDK’s OpenTelemetry telemetry turned on. Spanlight reads both the AI SDK’s own ai.* attributes (ai 5 and 6, and 7 through its legacy telemetry) and the gen_ai.* attributes of the GenAI mode of ai 7. The AI SDK reports a call’s usage on the step and again on the provider call inside it; Spanlight counts it once. Vercel AI SDK has the tested setup, and OTLP compatibility what each AI SDK version captures and loses.
Does it work with LiteLLM, OpenLLMetry or Traceloop?
Section titled “Does it work with LiteLLM, OpenLLMetry or Traceloop?”Yes, over OTLP. LiteLLM’s OpenTelemetry callback writes the OpenTelemetry gen_ai.* attributes, in its default mode and in its newer one. OpenLLMetry (Traceloop) provider spans carry gen_ai.* attributes, and its workflow, task, agent and tool spans are read from the traceloop.* attributes. See LiteLLM and OpenLLMetry for the tested setups, and OTLP compatibility for what each captures and loses.
Can I import data from Langfuse, LangSmith or Helicone?
Section titled “Can I import data from Langfuse, LangSmith or Helicone?”No. Spanlight has no importer for traces from those tools. To switch, send new traffic with the Python SDK, OTLP or the gateway; Ways to send data helps you choose.
Does it work with OpenAI and Anthropic?
Section titled “Does it work with OpenAI and Anthropic?”Yes. The Python SDK wraps both clients, and the gateway proxies both APIs; see Integrations.
Self-hosting
Section titled “Self-hosting”What does it need to run?
Section titled “What does it need to run?”Docker with the Compose plugin and three secrets in deploy/.env. There is no Redis or message broker, because Postgres also holds the job queue; see Self-hosting.
Why does no trace arrive?
Section titled “Why does no trace arrive?”Check first that the SDK has the right host and an API key. Troubleshooting lists the causes in the order to check them.
Evaluations
Section titled “Evaluations”Can I fail a pull request when a prompt gets worse?
Section titled “Can I fail a pull request when a prompt gets worse?”Yes. The eval-gate GitHub Action runs a prompt over a dataset and fails the job when a mean score is below your threshold; see Eval gate for CI, the GitHub Action and the eval gate tutorial.
Do evaluations cost money?
Section titled “Do evaluations cost money?”Rule-based evaluators cost nothing. An LLM judge spends provider money, capped by the judge’s monthly budget, and every experiment run makes real provider calls under a cost cap; see Evaluators and Experiments.
Related pages
Section titled “Related pages”- Self-hosting: run Spanlight with Docker Compose or on Railway.
- Tutorial: trace your first app: send a trace and find it in the dashboard.
- Troubleshooting: fixes for traces that do not arrive and spans that are rejected.
- Glossary: short definitions of the terms Spanlight uses.