foglamp-labs/foglamp

何を解決するか

Foglamp は Vercel AI SDK 専用の観測性レイヤーを提供します。複雑なマルチステップのエージェントワークフロー中に、モデルに送信された正確なプロンプトと応答、実際のコスト、レイテンシ、トークン使用量を可視化することで、「ブラックボックス」エージェントの問題を解決します。

動作方法

Foglamp はテレメトリコレクターを通じて TypeScript アプリケーションに統合されます。registerTelemetry(foglamp()) を呼び出すことで、generateText および streamText のすべての呼び出しを自動的にトレースします。

このシステムは3つの主要なコンポーネントで構成されています：

• SDK：クライアント側ライブラリで、スパン（LLMステップやツール呼び出しのような作業単位）とトレース（トップレベルの呼び出し）をキャプチャします。
• インジェスト API：認証を処理し、OpenRouter の価格情報を使ってインジェスト時にコストを計算し、ClickHouse にバッチ挿入を行う書き込み重視のサービスです。
• ダッシュボード：ClickHouse と Postgres からデータを読み取り、パフォーマンスメトリクス、ウォーターフォールトレースビュー、コスト内訳を表示する Next.js Web アプリケーションです。

対象ユーザー

TypeScript と Vercel AI SDK（バージョン 4 から 7）を使用し、AI エージェントの本番環境でのパフォーマンスと財務コストを監視したい開発者。

主な特徴

• 詳細なコスト追跡：トークンの各次元（プロンプト、完了、キャッシュなど）ごとのコストを計算し、カスタム価格オーバーライドをサポートします。
• 分散トレーシング：エージェントステップとツール呼び出しのウォーターフォールビューを提供し、各スパンの正確な入力と出力を含みます。
• パフォーマンス監視：p50/p95/p99 レイテンシと最初のトークン到着時間（TTFT）を追跡します。
• 自己ホスティング可能：Postgres、ClickHouse、Redis を使用して Docker Compose で完全にデプロイ可能です。
• 統合アラート：コスト、レイテンシ、エラー率、トークン使用量に対するしきい値ベースのメール通知を提供します。