Spanlens

2. Start local Supabase + ClickHouse (both require Docker)

supabase start supabase db push # apply Postgres migrations supabase gen types --lang typescript --local > supabase/types.ts

docker compose up -d clickhouse # start ClickHouse only (web/server run from pnpm dev) pnpm ch:migrate # apply ClickHouse migrations

1. Clone + install

git clone https://github.com/spanlens/Spanlens.git cd Spanlens pnpm install

⚡ Quick start in 30 seconds

3. Env vars (see apps/server/.env.example)

cp apps/server/.env.example apps/server/.env

2. Create a `.env` file

```bash

Optional (for invite emails)

Optional (Paddle billing, only if you sell paid plans on your instance)

PADDLE_ENVIRONMENT=sandbox # or production

```

Random secret for cron endpoint

CRON_SECRET=<random string>

RESEND_API_KEY=re_...

PADDLE_API_KEY=...

Point your SDK at your self-hosted URL

const openai = createOpenAI({
  baseURL: 'https://your-spanlens.example.com/proxy/openai/v1',
})

Your Spanlens instance talks to your Supabase + ClickHouse. We never see your data.

Framework integrations

Already using an orchestration framework? Plug Spanlens in as a callback. No code rewrites.

Vercel AI SDK (Next.js / edge friendly)

import { SpanlensClient } from '@spanlens/sdk'
import { createSpanlensTracker } from '@spanlens/sdk/vercel-ai'

const tracker = createSpanlensTracker({
  client: new SpanlensClient({ apiKey: process.env.SPANLENS_API_KEY! }),
  modelName: 'gpt-4o',
})

await generateText({
  model: openai('gpt-4o'),
  messages,
  onStepFinish: tracker.onStepFinish,
  onFinish: tracker.onFinish,
})

LangChain JS / LangGraph

import { createSpanlensCallbackHandler } from '@spanlens/sdk/langchain'

const handler = createSpanlensCallbackHandler({ client })
await chain.invoke({ input }, { callbacks: [handler] })   // LangChain
await graph.invoke({ input }, { callbacks: [handler] })   // LangGraph

LlamaIndex TS

import { Settings } from 'llamaindex'
import { registerSpanlensCallbacks } from '@spanlens/sdk/llamaindex'

const unregister = registerSpanlensCallbacks(Settings, { client })
// ... run queries ... unregister() on shutdown

Python: LangChain — from spanlens.integrations.langchain import SpanlensCallbackHandler. Same BaseCallbackHandler contract, works with chains, LCEL, and LangGraph.

Ollama (local LLMs) — Use the OpenAI-compatible client pointed at your local Ollama, then wrap with observeOllama() so the dashboard tags the call as Ollama instead of OpenAI.

import OpenAI from 'openai'
import { observeOllama } from '@spanlens/sdk'

const ollama = new OpenAI({ baseURL: 'http://localhost:11434/v1', apiKey: 'ollama' })
await observeOllama('chat', () => ollama.chat.completions.create({
  model: 'llama3.1', messages: [...]
}))

---