Spanlens

Spanlens

只需一行即可启用的开源大模型可观测性工具。 将 OpenAI、Anthropic 或 Gemini 客户端指向 Spanlens，即可记录每次调用的成本、令牌数、延迟和完整 Agent 跟踪信息。无需重写 SDK，也无需迁移平台。支持 11 个提供商，还原生集成 Vercel AI SDK、LangChain 和 LlamaIndex；你还可以通过随附的 MCP 服务，在 Cursor 或 Claude Desktop 中查询所有数据。只需一条 Docker 命令即可自托管。MIT 许可证。

它为何存在。 我曾基于 OpenAI 和 Gemini 开发一款大模型应用，却遇到了瓶颈。提供商的仪表板只显示总支出，除此之外什么也没有。我无法判断哪个功能消耗的令牌最多、哪个模型处理每项任务的成本最低，也不知道每个端点的实际成本。Spanlens 就是我想要的那一层。只需一行即可启用，不会影响关键路径，而且它是开源的，因此你可以自托管我们运行的确切代码。

⭐ 如果 Spanlens 对你有帮助，请为仓库点星。只需一秒，这也是帮助其他开发者发现此项目的最大助力。

托管版：spanlens.io · npm：@spanlens/sdk · PyPI：spanlens · CLI：@spanlens/cli · MCP：@spanlens/mcp-server · 状态：status.spanlens.io · 更新日志：spanlens.io/changelog

---

在线演示（无需注册）：spanlens.io/demo/requests

---

为什么选择 Spanlens？

• Helicone 已被收购，未来路线图尚不确定。
• Langfuse 功能强大，但设置复杂，扩展成本高。
• Spanlens 提供覆盖 80% 实际生产需求的 20% 功能。你可以获得请求日志、成本跟踪、Agent 追踪、异常检测、PII 扫描和提示词版本管理，同时享有简洁的 UI、两分钟即可完成的设置，以及不会因增长而惩罚你的定价。

	Spanlens	Langfuse Pro	Helicone
开源	✅ MIT	✅ MIT	✅ MIT
可自托管	✅ 一条 Docker 命令	✅	✅
免费套餐	50K req/mo	50K events/mo	10K req/mo
团队套餐（1M req/mo）	$149/mo	$271/mo	~$200/mo
Agent 追踪	✅	✅	⚠️ 有限
LLM-as-judge 评估	✅	✅	❌
PII + 注入扫描	✅	❌	❌
模型推荐	✅	❌	❌
提示词 A/B 实验	✅	✅	❌

账单可预测，不会突然触及配额上限。 免费套餐在 50K 次请求时会触发硬性 429，因此开发环境中的失控循环不会让你产生费用。付费套餐采用软性限额，并允许超额使用（Pro：每 100K 次 +$8，Team：每 100K 次 +$5），直至你自行控制的硬性上限。这样，流量激增时会按合理费用计费，而不是直接丢弃请求。

席位：Free 1 个 · Pro 3 个 · Team 10 个 · Enterprise 不限。席位指成员或待处理的邀请，不收取按席位计费的费用。自托管实例不限制席位数。所有付费套餐均可创建不限数量的项目。

⭐ 喜欢这个方向吗？点一个 star，能让更多开发者在满是臃肿、已被收购的工具的领域中找到轻量级开源替代方案。

---

⚡ 30 秒快速开始

TypeScript / JavaScript（Next.js）

npx @spanlens/cli init

向导会：

1. 使用你的包管理器（npm / pnpm / yarn / bun）安装 @spanlens/sdk
2. 将 SPANLENS_API_KEY 写入 .env.local
3. 将所有 new OpenAI({ apiKey, baseURL }) 改写为 createOpenAI()

只需粘贴一次 Spanlens API 密钥，确认两个提示，即可完成。现在，你的 LLM 调用会经由 Spanlens 代理，并显示在 www.spanlens.io/requests 中。

手动设置 TypeScript

import { createOpenAI } from '@spanlens/sdk/openai'
const openai = createOpenAI()  // reads SPANLENS_API_KEY, uses Spanlens proxy baseURL

Python

pip install "spanlens[openai]"

from spanlens.integrations.openai import create_openai

client = create_openai()  # reads SPANLENS_API_KEY from env
res = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

如需了解 Python 中的 Agent 追踪（多步骤、异步、工具调用），请参阅 Python SDK README。

框架集成

已经在使用编排框架？将 Spanlens 接入为回调即可，无需改写代码。

Vercel AI SDK（适用于 Next.js / edge）

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

const client = new SpanlensClient({ apiKey: process.env.SPANLENS_API_KEY! })

// generateText / generateObject have no onFinish, so pass the awaited result to end()
const tracker = createSpanlensTracker({ client, modelName: 'gpt-4o' })
const result = await generateText({
  model: openai('gpt-4o'),
  messages,
  onStepFinish: tracker.onStepFinish,
}).catch(async (err) => {
  await tracker.onError(err)   // ends the span as an error
  throw err
})
await tracker.end(result)      // records the run's total usage

// streamText / streamObject close the span from their callbacks
const streamTracker = createSpanlensTracker({ client, modelName: 'gpt-4o' })
const stream = streamText({
  model: openai('gpt-4o'),
  messages,
  onStepFinish: streamTracker.onStepFinish,
  onFinish: streamTracker.onFinish,
  onError: streamTracker.onError,
})

跟踪器不会等待 Spanlens，因为每次更新都会在后台发送。在无服务器处理程序中，返回前请执行 await client.flush()，以免函数冻结时丢失数据。

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。使用相同的 BaseCallbackHandler 契约，可与 chains、LCEL 和 LangGraph 配合使用。

更多集成：AWS Bedrock、CrewAI、Flowise、Instructor、LlamaIndex、OpenAI Assistants、MCP 服务。完整设置指南见 spanlens.io/docs/integrations。

Ollama（本地 LLM）：Ollama 在你的机器上运行，因此不会经由托管代理。使用 createOllama() 获取一个开箱即用的客户端，并用 observeOllama() 包装每次调用，即可记录 span 并标记为 Ollama。

import { SpanlensClient } from '@spanlens/sdk'
import { createOllama, observeOllama } from '@spanlens/sdk/ollama'

const spanlens = new SpanlensClient({ apiKey: process.env.SPANLENS_API_KEY! })
const ollama = createOllama() // points at http://localhost:11434/v1

const trace = spanlens.startTrace({ name: 'chat' })
const res = await observeOllama(trace, 'chat', (headers) =>
  ollama.chat.completions.create(
    { model: 'llama3.1', messages: [{ role: 'user', content: 'Hello' }] },
    { headers },
  ),
)
await trace.end({ status: 'completed' })

---

你会看到什么

记录每个请求的模型、提供商、延迟、令牌数、成本，以及完整的提示词和响应正文。支持筛选、搜索和导出。流式响应会自动重建。

---

你会获得什么

功能	描述
请求日志	记录每次大模型调用，包括模型、令牌数、成本、延迟以及完整的请求／响应正文（也会重建流式内容）
Agent 跟踪	将多步骤工作流显示为甘特图瀑布式跨度树，并突出显示关键路径（跨越分支的最长依赖链，而不仅仅是最慢的单个跨度）；还提供节点与边组成的图拓扑视图，用于查看 LangChain / LangGraph 回调跟踪
成本跟踪	按请求细分成本，并提供每日汇总和预算提醒。提示词缓存令牌（Anthropic 中的 cache_read / cache_creation，OpenAI 中的 prompt_tokens_details.cached_tokens）会单独解析，并按折扣价计费，因此你可以看到实际节省的缓存成本，而不只是标价
按终端用户分析	使用 x-spanlens-user 标记调用（SDK：withUser() / with_user()）；/users 页面会显示每位用户的成本、令牌数、错误、模型和最后活跃时间
异常检测	检测延迟、成本或错误率相对于 7 天基线的 3σ 偏差，并提供根因提示（令牌数变化、HTTP 状态码分布）
提醒	针对预算、错误率和 p95 延迟设置阈值规则。通过 Email（Resend）、Slack 或 Discord Webhook 发送。每 15 分钟通过 cron 评估一次，并采用至少一次投递机制
PII + 提示词注入扫描	基于正则表达式检测请求和响应正文；可按项目启用注入拦截（422）；向工作区所有者即时发送提醒邮件
节省成本（模型推荐）	/savings 信息面板会显示符合更便宜模型特征的调用（“你的 gpt-4o 调用看起来像是分类任务。试试 gpt-4o-mini”），并估算每月节省金额。月初至今的提示词缓存节省卡片会显示因缓存读取令牌享受折扣而少支付的美元金额
响应缓存	可按请求选择启用 x-spanlens-cache: true（或设置 TTL 秒数，上限为 24 小时；SDK：withCache()）。当相同请求正文完全匹配时，会直接返回已存储的响应，不调用服务提供方；日志记录的成本为零，且按 API 密钥隔离，不会在不同密钥间泄露数据。仅支持非流式、状态码为 200 的响应
邮件摘要与运行状况提醒	每周一发送工作区周报（请求数、成本及周环比变化、热门模型、异常）；如果曾发送流量的工作区突然连续 24 小时没有流量，则会向管理员发送数据静默提醒邮件，以便在密钥失效或环境变量被删除演变成无声流失之前及时发现
提示词版本管理 + A/B 测试	注册提示词模板，开展流量拆分实验，并排比较不同版本的延迟／成本／错误率；延迟和成本使用 Welch's t-test，错误率使用 z-test 进行报告，让你获得统计显著性，而不只是平均值
提示词 Playground	直接在信息面板中注入变量并执行任意提示词版本，在发布前查看实际成本和响应
数据集	可重复使用的（input, expected_output）测试集，可针对任意提示词版本或模型重新运行。可直接从信息面板上传 CSV / JSONL 文件，也可通过 POST 以编程方式上传。用于离线评估和回归检查
评估与实验	构建 LLM-as-judge 评估器（使用 OpenAI、Anthropic 或 Gemini 进行评判，可根据评估标准选择成本最低或效果最好的模型），并通过评分标准锚点和通过率置信区间进行评估。支持成对 A 与 B 模式，用于正面对比提示词；支持 Agent 轨迹模式，用于为完整跟踪评分（而非只评估最终文本）；还支持以 (evaluator, response) 为键缓存评判结果，避免重新运行时重复调用大模型。人工标注会进入抽样队列，并使用 Pearson r（数值型）或 Cohen's κ（类别型）衡量评判结果与人工标注的一致性
OpenAPI 3.0 规范 + Swagger UI	可通过 GET /api/v1/openapi.json 获取机器可读规范，并通过 GET /api/v1/docs 使用交互式浏览器。漂移测试会确保每个路由都有文档记录
已保存的筛选条件	固定常用的请求日志查询条件（模型、状态、成本范围、标签），并在整个工作区共享
出站 Webhook	订阅 request.created / trace.completed / alert.triggered 事件。负载使用 HMAC 签名，签名头为 X-Spanlens-Signature: sha256=…，接收方可据此验证来源
OpenTelemetry / OTLP 数据接入	POST /v1/traces 接受采用 gen_ai.* 语义约定的 OTLP/HTTP JSON 导出数据，因此无需编写 Spanlens 专用代码，即可接入任意 OTel SDK
服务提供方密钥安全	每周通过邮件汇总长期未使用（90 天以上未使用）的服务提供方密钥；每天使用 GitGuardian 扫描活跃密钥是否泄露，并提供每个密钥的扫描历史
隐私控制	每个请求都可通过 x-spanlens-log-body: full | meta | none 请求头，让客户减少 Spanlens 存储的数据（删除正文、删除终端用户 ID），而不丢弃请求本身
数据导出	可将请求、跟踪、异常和标记的安全事件下载为 CSV 或 JSON（GET /api/v1/exports/{requests,traces,anomalies,security}?format=csv）。服务器端采用流式处理，支持导出 10 万行以上的数据，避免大型导出导致 OOM

---

团队和工作区

Spanlens 开箱即支持多用户。邀请队友、分配角色，并为每位客户创建独立工作区。

• 角色包括 admin（成员和账单管理）、editor（数据和设置管理）以及 viewer（只读）。系统会保护最后一位管理员，防止其被降级或移除。
• 席位数量取决于套餐，成员和待处理邀请都会计入。工作区席位已满时，新邀请会收到 402 和升级指引；有人接受邀请时，系统会再次检查。即使席位上限降低，也不会移除现有成员。
• 电子邮件邀请有效期为 7 天，令牌使用 sha256 哈希。设置 RESEND_API_KEY 后通过 Resend 发送；本地开发时则会回退为在控制台记录接受邀请的 URL。
• 待处理邀请横幅会在仪表板顶部显示尚未接受的邀请，即使收件人从未打开邮件也会显示。接受邀请后，用户会加入并自动切换到相应工作区；拒绝邀请则会移除该记录。
• 多工作区支持通过侧边栏在工作区之间切换（sb-ws cookie + 硬刷新，以便中间件重新解析作用域）。适用于需要管理多个客户的顾问，也适用于将生产环境和暂存环境分别设为独立工作区的团队。
• 两步引导会将新注册用户带到 /onboarding：为工作区命名、回答两个可选的调查问题，即可完成。受邀用户会进入精简流程，接受邀请后将跳过创建工作区。
• 审计日志（设置 → 审计日志）会记录每次成员、角色和邀请事件，以及操作人和时间戳。

---

Monorepo 结构

Spanlens/
├── apps/
│   ├── web/             Next.js 16 dashboard (www.spanlens.io)
│   └── server/          Hono LLM proxy + REST API (api.spanlens.io)
├── packages/
│   ├── sdk/             @spanlens/sdk:  TypeScript / JavaScript SDK
│   ├── sdk-python/      spanlens (PyPI): Python SDK
│   ├── cli/             @spanlens/cli:  npx wizard for 1-command setup
│   └── mcp-server/      @spanlens/mcp-server: MCP server for Cursor / Claude Desktop / Continue
└── supabase/
    ├── migrations/      Postgres schema (orgs, projects, keys, prompts, requests; RLS-gated)
    └── seeds/           model_prices.sql etc.

数据存储位置

所有数据都存储在 Supabase Postgres 中。组织、项目、成员、API 和提供商密钥、提示词、数据集、警报、账单和审计日志，都是受 RLS 保护的普通表。

requests 表（每次大模型调用对应一行）按 created_at 按月分区，因此清理过期日志时只需删除分区，无需执行批量 DELETE。读取操作通过 apps/server/src/lib/requests-query.ts 执行，该文件会注入 organization_id 筛选条件和按套餐设定的数据保留期限（免费版 = 14 天 / 专业版 = 90 天 / 团队版 = 365 天）。如果日志写入失败，该行会以 JSON 格式暂存到 requests_fallback 队列中，并由 cron 每 5 分钟重放一次。重放操作具有幂等性（ON CONFLICT (created_at, id) DO NOTHING），因此重试不会对配额重复计算请求。

项目、统一密钥和标头

• 一个工作区可以包含多个项目（例如 dev / staging / prod，或每个应用一个项目）。每个项目都有独立的配额、提供商密钥和提示词命名空间。
• 统一 API 密钥可为每个项目提供一个与提供商无关的 sl_live_* 密钥。Spanlens 会根据请求路径推断提供商（/proxy/openai/*、/proxy/anthropic/*、/proxy/gemini/*、/proxy/mistral/*、/proxy/openrouter/*、/proxy/groq/*、/proxy/deepseek/*、/proxy/xai/*、/proxy/cohere/*、/proxy/azure/*），因此即使调用多个模型供应商，也只需一个 Spanlens 密钥。
• X-Spanlens-* 标头（由 SDK 辅助函数 withUser()、withSession()、withPromptVersion()、withLogBody() 自动设置）：为请求添加最终用户 / 会话 ID 标签，将请求关联到提示词版本实验，或限制 Spanlens 存储的请求正文大小。完整列表见 /docs/proxy。
• 流式传输安全机制会在 290 秒时优雅地关闭代理响应，并在日志中设置 truncated=true 标记，确保长时间运行的流不会悄然消失。

---

本地开发

前置条件：Node 20+、pnpm 10.33.0+、Docker（用于本地 Supabase）；Vercel CLI 可选。

# 1. Clone + install
git clone https://github.com/spanlens/Spanlens.git
cd Spanlens
pnpm install

# 2. Start local Supabase (requires Docker)
supabase start
supabase db push        # apply Postgres migrations
supabase gen types --lang typescript --local > supabase/types.ts

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

# 4. Run everything (web on :3000, server on :3001)
pnpm dev

运行测试和 lint

pnpm typecheck          # TS across all packages
pnpm lint               # ESLint
pnpm test               # Vitest: server + sdk + cli suites
pnpm build              # production build smoke test

架构规则和已知问题（流式传输、RLS、Paddle 账单、Vercel Edge runtime、npm 发布）请参阅 CLAUDE.md。

---

自托管

最简单的自托管方式是使用随附的 docker-compose.yml。其中包含两个容器：仪表板（Web） 和 代理/API 服务，两者都从 GHCR 拉取预构建镜像。你只需要另外准备 Supabase 项目，可以使用 Supabase Cloud，也可以使用自己自托管的 Supabase。

1. 应用 Supabase 架构（仅需一次）

打开你的 Supabase 项目 → SQL 编辑器 → 新建查询，粘贴 supabase/init.sql 的内容，然后点击 运行。就这么简单，无需 CLI。

替代方式（psql）：

psql "postgresql://postgres:<password>@db.<ref>.supabase.co:5432/postgres" \
  -f supabase/init.sql

2. 创建 .env 文件

# Supabase (cloud or self-hosted)
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

# Encryption key (generate with: openssl rand -base64 32)
ENCRYPTION_KEY=<32-byte base64>

# Random secret for cron endpoint
CRON_SECRET=<random string>

# Pooled Postgres connection for the `requests` table (required).
# Supabase Dashboard: Connect > Direct > Transaction pooler, with
# "Use IPv4 connection" switched on. Port 6543, not 5432.
# The dedicated pooler shown by default is IPv6-only, so anything without
# outbound IPv6 (Vercel functions included) fails at DNS. Copy the host from
# that dialog rather than assembling it: the shared pooler hostname carries a
# numbered prefix that the region does not tell you.
# This is a full database credential, so keep it out of logs.
SUPABASE_DB_POOLER_URL=postgresql://postgres.<ref>:<password>@<pooler-host>:6543/postgres

# Optional (for invite emails)
# WEB_URL=https://your-domain.com
# RESEND_API_KEY=re_...
# RESEND_FROM=Spanlens <[email protected]>

# Optional (Paddle billing, only if you sell paid plans on your instance)
# PADDLE_API_KEY=...
# PADDLE_NOTIFICATION_SECRET=...
# PADDLE_ENVIRONMENT=sandbox  # or production

3. 启动

docker compose up -d

• 仪表板：http://localhost:3000
• API / 代理：http://localhost:3001
• 健康状态：GET /health（存活状态）和 GET /health/deep（数据库连接池、备用队列深度、定时任务新鲜度）

从较旧版本升级？ 请求日志现在存储在 Postgres 中。重新应用 supabase/init.sql，确保 requests 表存在；将 SUPABASE_DB_POOLER_URL 添加到 .env，然后移除 ClickHouse 容器及其四个 CLICKHOUSE_* 变量。ClickHouse 中已有的行不会迁移，因此在拆除之前，请导出仍需保留的数据。

Web 容器会将 NEXT_PUBLIC_* 变量作为构建参数传入（Next.js 会将它们打包进客户端包），因此必须在执行 docker compose build 之前设置好这些变量。

仅服务端（无仪表板）

如果你只需要代理/API，并单独运行仪表板：

docker pull ghcr.io/spanlens/spanlens-server:latest
docker run -p 3001:3001 \
  -e SUPABASE_URL=... \
  -e SUPABASE_ANON_KEY=... \
  -e SUPABASE_SERVICE_ROLE_KEY=... \
  -e SUPABASE_DB_POOLER_URL=... \
  -e ENCRYPTION_KEY=... \
  ghcr.io/spanlens/spanlens-server:latest

将 SDK 指向你的自托管 URL

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

你的 Spanlens 实例会连接到你的 Supabase。我们不会看到你的数据。

后台任务（Vercel Cron / 你的调度器）

托管实例包含以下 cron 任务（参见 apps/server/vercel.json）。自托管时，将任意调度器指向相同路径，并使用 CRON_SECRET bearer：

路径	计划	用途
/cron/evaluate-alerts	每 15m	评估阈值和异常警报，触发通知
/cron/snapshot-anomalies	每日 01:00	生成每日异常基线
/cron/replay-fallback	每 5m	将 requests_fallback 队列中的数据重放到 requests 表
/cron/stale-key-reminders	每周一 09:00	发送闲置提供商密钥的邮件摘要
/cron/leak-detect-keys	每日 04:00	使用 GitGuardian 扫描活跃的提供商密钥
/cron/recommend-savings-alerts	每日 09:00	通过邮件发送更换模型以节省费用的机会
/cron/check-past-due-downgrades	每日 10:00	发送 D-3 / D-1 警告，并自动降级逾期订阅
/cron/execute-pending-deletions	每 6h	永久删除超过 30 天软删除宽限期的账户
/cron/run-background-migrations	每 5m	清空后台迁移队列（数据回填）
/cron/detect-missing-model-prices	每小时	查找请求日志中没有对应 model_prices 行的新模型 ID
/cron/self-monitor	每小时 :31	Spanlens 使用自身服务：将心跳评估写入内部工作区
/cron/detect-orphan-spans	每小时 :17	标记父级 trace 从未到达的 span
/cron/prune-judge-cache	每日 03:00	按 TTL 淘汰过期的 (evaluator, response) 判定缓存条目
/cron/purge-proxy-cache	每日 03:15	回收已停止活动的密钥对应的过期 proxy_response_cache 行
/cron/weekly-digest	每周一 09:00	向每个工作区发送每周摘要（请求数、费用趋势、热门模型、异常）
/cron/detect-data-silence	每 6h	当此前活跃的工作区停止发送数据达 24h 时提醒管理员
/cron/keep-warm	每 5m	发送轻量级 ping，使 Vercel 函数保持温热（Fly.io / Railway 等始终运行的平台无需启用）

---

贡献

欢迎提交 PR 和问题。请参阅 CONTRIBUTING.md，了解项目结构、本地开发环境设置、代码规范以及我们对 PR 的要求。提交消息遵循 Conventional Commits 规范，PR 模板会引导你完成安全检查清单。

安全问题：请发送邮件至 [email protected]，不要公开提交问题。请参阅 SECURITY.md。

许可证

MIT。你可以自由使用、派生、可自托管或基于此进行构建。spanlens.io 上的托管服务是运行 Spanlens 的推荐方式，但你也可以随时拉取 Docker 镜像并自行运行（请参阅 docs/self-host）。