foglamp-labs/foglamp

何を解決するか

Foglamp は Vercel AI SDK 専用の観測性レイヤーを提供し、開発者が AI エージェントの実際のコスト、レイテンシ、内部実行ステップを把握できないという課題を埋めます。モデルに送信された内容と各呼び出しのコストを正確に追跡することで、「ブラックボックス」問題を回避します。

動作方法

Foglamp はテレメトリコレクターを通じて TypeScript アプリケーションに統合されます。generateText および streamText 呼び出しのデータを収集し、インジェスト API に送信します。このデータは、高頻度のスパンおよびトレース用に ClickHouse に、設定およびアラート用に Postgres に格納されます。

主なメカニズムは以下の通りです：

• コスト計算：OpenRouter の価格データを使用してインジェスト時にコストを計算します。
• 分散トレーシング：トップレベルの呼び出しを「トレース」とし、LLM ステップ、ツール呼び出し、埋め込みを「スパン」として組織し、実行のウォーターフォールビューを構築します。
• 文脈に基づくグループ化：agentName、sessionId、workflowName などのインデックス付きフィールドを使用してログをグループ化・フィルタリングします。
• アラート機能：1分ごとにコスト、レイテンシ、エラー率のしきい値ルールを評価します。

対象ユーザー

TypeScript および Vercel AI SDK（v4–v7）を使用し、本番環境での AI エージェントのパフォーマンス、コスト、信頼性を監視したい開発者。

主な特徴

• 統合された観測性：1つのダッシュボードでコスト、レイテンシ（最初のトークン到着時間も含む）、トークン使用量、分散トレースを追跡。
• 自己ホスティング可能：ClickHouse、Postgres、Redis を使用して Docker Compose で完全にデプロイ可能。
• 静的ノーオプ：API キーが提供されていない場合、SDK は無効化され、メインアプリケーションにレイテンシを追加したり、エラーを発生させたりすることはありません。
• 細粒度の追跡：顧客ごとのコスト追跡とカスタム価格オーバーライドをサポート。
• 柔軟な統合：すべての呼び出しにグローバルにインストルメントを適用するか、特定のコンテキストに対して個別にオーバーライドする選択が可能。