Foglamp

Foglamp is an open-source observability platform built specifically for AI agents running on the Vercel AI SDK. Two lines of code and an API key instrument every generateText and streamText call, surfacing costs, latency, token usage, distributed traces, and eval scores in a unified dashboard. The platform is licensed under Apache 2.0 for the core platform and MIT for the SDK, and is fully self-hostable via Docker Compose.

What It Is

Foglamp fills the gap the Vercel AI SDK leaves open: it gives developers a first-class answer to what an agent cost, how slow it was, and what it actually sent the model. It sits between the AI SDK and the model provider, capturing telemetry at ingest and storing spans in ClickHouse with org/project/key state in Postgres. The hosted cloud version and a self-hosted path using plain Postgres + ClickHouse + Redis are both supported.

Architecture and Data Model

Foglamp's architecture separates three independently scalable deployables:

• Ingest (apps/ingest) — a Hono API that handles API-key auth, rate limiting, cost computation at ingest time, and bulk writes to ClickHouse.
• Server (apps/server) — a Hono + tRPC dashboard API with better-auth and an alert evaluator cron.
• Web (apps/web) — a Next.js dashboard.

Spans are stored in ClickHouse; org, project, key, pricing, and alert state live in Postgres. Costs are computed once at ingest from OpenRouter pricing data (cached with a 24-hour refresh), per token dimension — prompt, completion, cached, reasoning, images, web search. Unknown models show — rather than a misleading $0.

Core Observability Capabilities

• Cost intelligence — per-model, per-agent, per-customer spend with custom price overrides per project.
• Latency and TTFT — p50/p95/p99 per model and agent; time-to-first-token read from the SDK's own step timing.
• Distributed traces — waterfall view of every run with the exact prompt and response on every span; tool calls and embedding steps are first-class spans.
• Evals — score production traffic with code checks and LLM judges.
• Alerts — threshold rules on cost, latency, error rate, TTFT, tokens, or request count, evaluated every minute with email and Slack notifications.
• Named agents, workflows, and sessions — agentName, workflowName, workflowRunId, and sessionId are indexed first-class fields; free-form metadata handles everything else.

Self-Hosting Path

The repository ships a docker-compose.yml that starts Postgres, ClickHouse, Redis, the ingest API, the dashboard API, and the web app. A one-shot migrate service runs Postgres migrations, ClickHouse DDL, span retention TTL, and seeds an admin user, org, project, and API key. Email (magic-link and alert notifications) is optional via Resend; Google OAuth is also optional. The SDK becomes a silent no-op when FOGLAMP_API_KEY is unset, so it never throws or adds latency in environments where telemetry is disabled.

SDK Scope and Compatibility

The published foglamp npm package targets TypeScript with Vercel AI SDK v4 through v7. AI SDK v7 uses the native telemetry-integrations collector; v4/v5/v6 use the foglamp/wrap entry point. The SDK has zero runtime workspace dependencies and treats ai as a peer dependency. OTLP /v1/traces ingest is listed in the repository as a planned follow-up. The monorepo is built on Bun workspaces and Turborepo, with packages for the SDK, wire contracts (Zod), cost computation, ClickHouse client, Drizzle schema, tRPC routers, auth, and a shadcn UI component library.