foglamp-labs/foglamp

What it solves

Foglamp provides an observability layer specifically for the Vercel AI SDK. It solves the problem of "black box" AI agents by providing visibility into the actual costs, latency, token usage, and the exact prompts and responses sent to models during complex, multi-step agent workflows.

How it works

Foglamp integrates into a TypeScript application via a telemetry collector. By calling registerTelemetry(foglamp()), it automatically traces every generateText and streamText call.

The system consists of three main components:

• SDK: A client-side library that captures spans (units of work like LLM steps or tool calls) and traces (top-level calls).
• Ingest API: A write-heavy service that authenticates requests, calculates costs at the point of ingestion using OpenRouter pricing, and bulk-inserts data into ClickHouse.
• Dashboard: A Next.js web application that reads from ClickHouse and Postgres to display performance metrics, waterfall trace views, and cost breakdowns.

Who it’s for

Developers using TypeScript and the Vercel AI SDK (versions 4 through 7) who need to monitor the production performance and financial cost of their AI agents.

Highlights

• Detailed Cost Tracking: Computes costs per token dimension (prompt, completion, cached, etc.) and supports custom price overrides.
• Distributed Tracing: Provides a waterfall view of agent steps and tool calls, including the exact input and output for every span.
• Performance Monitoring: Tracks p50/p95/p99 latency and Time to First Token (TTFT).
• Self-Hostable: Can be deployed entirely via Docker Compose using Postgres, ClickHouse, and Redis.
• Integrated Alerting: Threshold-based email notifications for cost, latency, error rates, and token usage.