foglamp-labs/foglamp

What it solves

Foglamp provides an observability layer specifically for the Vercel AI SDK, filling the gap where developers lack visibility into the actual costs, latency, and internal execution steps of their AI agents. It prevents the "black box" problem by tracking exactly what is sent to models and how much each call costs.

How it works

Foglamp integrates into a TypeScript application via a telemetry collector. It captures data from generateText and streamText calls, sending them to an ingest API. This data is stored in ClickHouse (for high-volume spans and traces) and Postgres (for configuration and alerts).

Key mechanisms include:

• Cost Calculation: Computes costs at ingest using OpenRouter pricing data.
• Distributed Tracing: Organizes calls into traces (top-level calls) and spans (LLM steps, tool calls, or embeddings) to create a waterfall view of execution.
• Contextual Grouping: Uses indexed fields like agentName, sessionId, and workflowName to group and filter logs.
• Alerting: Evaluates threshold rules for cost, latency, and error rates every minute.

Who it’s for

Developers using TypeScript and the Vercel AI SDK (v4–v7) who need to monitor the performance, cost, and reliability of their AI agents in production.

Highlights

• Unified Observability: Tracks costs, latency (including Time to First Token), token usage, and distributed traces in one dashboard.
• Self-Hostable: Can be deployed entirely via Docker Compose using ClickHouse, Postgres, and Redis.
• Silent No-op: The SDK remains inactive if no API key is provided, ensuring it never adds latency or throws errors into the main application.
• Granular Tracking: Supports per-customer cost tracking and custom price overrides.
• Flexible Integration: Offers both global instrumentation for all calls and per-call overrides for specific context.