foglamp-labs/foglamp

解决的问题

Foglamp 为 Vercel AI SDK 提供了一个专门的可观测性层，填补了开发者无法了解其 AI 代理实际成本、延迟和内部执行步骤的空白。它通过精确追踪发送给模型的内容以及每次调用的成本，避免了“黑箱”问题。

工作原理

Foglamp 通过一个遥测收集器集成到 TypeScript 应用中。它捕获 generateText 和 streamText 调用的数据，并将其发送到一个摄入 API。这些数据存储在 ClickHouse（用于高吞吐量的跨度和追踪）和 Postgres（用于配置和告警）中。

关键机制包括：

• 成本计算：在摄入时使用 OpenRouter 定价数据计算成本。
• 分布式追踪：将调用组织为追踪（顶层调用）和跨度（LLM 步骤、工具调用或嵌入），以创建执行的瀑布视图。
• 上下文分组：使用 agentName、sessionId 和 workflowName 等索引字段对日志进行分组和过滤。
• 告警：每分钟评估成本、延迟和错误率的阈值规则。

适用人群

使用 TypeScript 和 Vercel AI SDK（v4–v7）并需要在生产环境中监控其 AI 代理性能、成本和可靠性的开发者。

主要亮点

• 统一可观测性：在一个仪表板中追踪成本、延迟（包括首次令牌到达时间）、令牌使用量和分布式追踪。
• 可自托管：可通过 Docker Compose 使用 ClickHouse、Postgres 和 Redis 完全部署。
• 静默无操作：如果没有提供 API 密钥，SDK 将保持非活动状态，确保不会向主应用添加延迟或抛出错误。
• 细粒度追踪：支持按客户追踪成本和自定义价格覆盖。
• 灵活集成：提供对所有调用的全局 Instrumentation，也支持对特定上下文的逐调用覆盖。