foglamp-labs/foglamp

해결하는 문제

Foglamp은 Vercel AI SDK 전용의 관측성 레이어를 제공하여, 개발자가 AI 에이전트의 실제 비용, 지연 시간, 내부 실행 단계에 대한 가시성을 갖지 못하는 문제를 해결합니다. 모델로 전송된 내용과 각 호출의 비용을 정확히 추적함으로써 '블랙박스' 문제를 방지합니다.

작동 방식

Foglamp은 타입스크립트 애플리케이션에 텔레메트리 컬렉터를 통해 통합됩니다. generateText 및 streamText 호출에서 데이터를 캡처하여 인제스트 API로 전송합니다. 이 데이터는 고용량의 스팬과 트레이스를 위해 ClickHouse에, 설정 및 알림을 위해 Postgres에 저장됩니다.

주요 메커니즘은 다음과 같습니다:

• 비용 계산: OpenRouter 가격 데이터를 사용하여 인제스트 시 비용을 계산합니다.
• 분산 추적: 호출을 트레이스(상위 수준 호출)와 스팬(LLM 단계, 도구 호출, 임베딩 등)로 조직하여 실행의 워터폴 뷰를 생성합니다.
• 문맥 기반 그룹화: agentName, sessionId, workflowName과 같은 인덱싱된 필드를 사용하여 로그를 그룹화하고 필터링합니다.
• 알림: 비용, 지연 시간, 오류율에 대한 임계값 규칙을 분당 평가합니다.

대상 사용자

TypeScript와 Vercel AI SDK(v4–v7)를 사용하여 본격적인 AI 에이전트의 성능, 비용, 신뢰성을 모니터링이 필요한 개발자들.

주요 특징

• 통합 관측성: 하나의 대시보드에서 비용, 지연 시간(첫 번째 토큰 도착 시간 포함), 토큰 사용량, 분산 트레이스를 모두 추적합니다.
• 자체 호스팅 가능: ClickHouse, Postgres, Redis를 사용해 Docker Compose로 완전히 배포할 수 있습니다.
• 무작위 비활성화: API 키가 제공되지 않으면 SDK는 비활성화되어 메인 애플리케이션에 지연 시간을 추가하거나 오류를 발생시키지 않습니다.
• 세부 추적: 고객별 비용 추적 및 사용자 정의 가격 오버라이드를 지원합니다.
• 유연한 통합: 모든 호출에 대한 글로벌 인스트루멘테이션과 특정 컨텍스트에 대한 개별 오버라이드를 모두 제공합니다.