Quickstart

Install the Spanloom Python SDK, create a project, and see your first trace in under five minutes.

1. Install the SDK

Install the spanloom package from PyPI:

$ pip install spanloom

The SDK requires Python 3.9 or later.

2. Get your API key

Sign up at spanloom.com, create a project, and copy the API key from Settings. You will use it in the next step.

Note: API keys are project-scoped. Each project you create in Spanloom gets its own key. Rotate keys from the workspace settings at any time.

3. Instrument your first LLM call

Add three lines to your existing OpenAI code:

import openai
import spanloom

spanloom.init(api_key="spl_your_key_here")

client = openai.OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarise the RAG pipeline."}]
)
print(response.choices[0].message.content)

That is it. Spanloom patches the OpenAI client automatically on init(). Every call is traced.

4. View your trace

Run your script. Within a few seconds, the trace appears in the Spanloom dashboard under the project you created. You will see:

  • The span name, model, and prompt hash
  • Input and output token counts
  • Latency (time-to-first-token and total)
  • Estimated cost based on the model's published token rate

Advanced: wrapping a multi-step pipeline

For pipelines with multiple LLM calls, retrieval steps, and tool invocations, use the context manager to group spans into a single named trace:

import spanloom

with spanloom.trace("rag_answer", user_id="u_123") as trace:
    docs = retrieve_documents(query)
    with trace.span("retrieve_docs"):
        docs = retrieve_documents(query)
    with trace.span("llm_answer"):
        answer = call_llm(query, docs)
    return answer

Each trace.span() block creates a child span in the waterfall. Nesting is unlimited.

TypeScript / Node.js

The TypeScript SDK is available in open beta:

npm install @spanloom/sdk
import { init } from "@spanloom/sdk";
init({ apiKey: "spl_your_key_here" });

Usage mirrors the Python SDK. The TypeScript SDK auto-instruments openai, LangChain.js, and the Vercel AI SDK on init.

Next steps