# Foglamp

> Open-source observability layer for AI agents built on the Vercel AI SDK — tracks cost, latency, token usage, distributed traces, and evals with two lines of code.

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.

## Features
- Cost tracking per model, agent, and customer
- Distributed trace waterfall with prompt and response per span
- p50/p95/p99 latency and time-to-first-token metrics
- Production evals with code checks and LLM judges
- Threshold alerts on cost, latency, error rate, TTFT, tokens, and request count
- Email and Slack alert notifications
- Named agents, workflows, and sessions as first-class indexed fields
- Free-form metadata support
- Self-hostable via Docker Compose with ClickHouse and Postgres
- Two-line SDK instrumentation for Vercel AI SDK v4–v7
- Cost computed at ingest from OpenRouter pricing per token dimension
- Per-project custom price overrides
- Silent no-op SDK when API key is unset
- Serverless runtime support (Vercel, AWS Lambda, Cloudflare Workers)

## Integrations
Vercel AI SDK, OpenAI (GPT models), Anthropic (Claude models), Google (Gemini models), OpenRouter, ClickHouse, PostgreSQL, Redis, Resend (email), Google OAuth, Slack (alerts)

## Platforms
WEB, API, CLI, DEVELOPER_SDK

## Pricing
Open Source, Free tier available

## Links
- Website: https://foglamp.dev
- Documentation: https://docs.foglamp.dev/
- Repository: https://github.com/foglamp-labs/foglamp
- EveryDev.ai: https://www.everydev.ai/tools/foglamp