foglamp-labs/foglamp

해결하는 문제

Foglamp은 Vercel AI SDK 전용의 관측성 레이어를 제공합니다. 복잡한 다단계 에이전트 워크플로우 중 모델에 전송된 정확한 프롬프트와 응답, 실제 비용, 지연 시간, 토큰 사용량을 가시화함으로써 '블랙박스' AI 에이전트 문제를 해결합니다.

작동 방식

Foglamp은 텔레메트리 컬렉터를 통해 TypeScript 애플리케이션에 통합됩니다. registerTelemetry(foglamp())을 호출하면 generateText 및 streamText 호출을 자동으로 트레이스합니다.

시스템은 세 가지 주요 구성 요소로 구성됩니다:

• SDK: 클라이언트 측 라이브러리로, 스팬(예: LLM 단계 또는 도구 호출과 같은 작업 단위)과 트레이스(상위 수준 호출)를 캡처합니다.
• 인제스트 API: 인증을 처리하고 OpenRouter 가격 정보를 사용해 인제스트 시점에 비용을 계산하며, ClickHouse에 대량 삽입하는 쓰기 중심 서비스입니다.
• 대시보드: ClickHouse와 Postgres에서 데이터를 읽어 성능 메트릭, 워터폴 트레이스 뷰, 비용 분석을 표시하는 Next.js 웹 애플리케이션입니다.

대상 사용자

TypeScript와 Vercel AI SDK(버전 4~7)를 사용하여 AI 에이전트의 운영 성능과 재정적 비용을 모니터링이 필요한 개발자들입니다.

주요 기능

• 세부적인 비용 추적: 토큰의 각 차원(프롬프트, 완료, 캐시 등)별 비용을 계산하고 사용자 정의 가격 오버라이드를 지원합니다.
• 분산 트레이싱: 에이전트 단계와 도구 호출의 워터폴 뷰를 제공하며, 각 스팬의 정확한 입력과 출력을 포함합니다.
• 성능 모니터링: p50/p95/p99 지연 시간과 최초 토큰 도착 시간(TTFT)을 추적합니다.
• 자체 호스팅 가능: Postgres, ClickHouse, Redis를 사용해 Docker Compose로 완전히 배포할 수 있습니다.
• 통합 알림: 비용, 지연 시간, 오류율, 토큰 사용량에 대한 임계값 기반 이메일 알림을 제공합니다.