Docs

Quickstart

Run the server, create a workspace key, ingest a span. This is the free Starter path: self-host from the repo (or the Docker image in the README's Deploy section) — no card, no hosted signup.

pip install -r requirements.txt
uvicorn app.main:app --port 8000

# create a workspace + key (dev convenience; only the key's SHA-256 hash is stored)\npython -c "\nfrom app.db import SessionLocal, init_db\nfrom app.tenancy import create_workspace\ninit_db()\ns = SessionLocal()\nws, key = create_workspace(s, 'demo', 'team')   # starter | team | enterprise\ns.commit()\nprint('workspace key (shown once):', key)""

Ingest spans

curl -X POST localhost:8000/v1/traces \
  -H "x-spanwise-key: $KEY" -H 'Content-Type: application/json' -d '{
    "spans": [{
      "trace_id": "t1", "span_id": "s1", "name": "agent.step",
      "service": "my-agent",
      "start_ns": 1700000000000000000, "end_ns": 1700000001000000000,
      "attributes": {"llm.model": "gpt-4o-mini",
                     "llm.usage.prompt_tokens": 120,
                     "llm.usage.completion_tokens": 40}
    }]}'
# {"accepted_spans":1,"trace_ids":["t1"]}

OTLP/HTTP-JSON works too: post {"resourceSpans": [...]} with key-value attribute lists.

Read traces and costs

# list traces (filters: service, status, model, limit, offset)
curl -H "x-spanwise-key: $KEY" "localhost:8000/v1/traces?service=my-agent&limit=20"

# full trace with spans
curl -H "x-spanwise-key: $KEY" localhost:8000/v1/traces/t1

# per-model token spend (USD estimates)
curl -H "x-spanwise-key: $KEY" localhost:8000/v1/costs/summary

Audit log

# append an entry to YOUR workspace's hash-chained log
curl -X POST localhost:8000/v1/audit -H "x-spanwise-key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"deploy.rollback","payload":{"from":"v1.2","to":"v1.1"}}'

# verify the chain (detects tampering)
curl -H "x-spanwise-key: $KEY" localhost:8000/v1/audit/verify
# {"ok":true,"entries":42,"head_hash":"ab..."}

# export the full chain
curl -H "x-spanwise-key: $KEY" localhost:8000/v1/audit/export

Run evals

python -m evals.run --dataset evals/datasets/sample_eval.jsonl --judge heuristic
# {"judge":"heuristic-v1","n":5,"mean_score":0.733,"pass_rate":0.6}

--judge llm requires SPANWISE_JUDGE_API_KEY and a wired provider (see evals/judge.py).