Spanlens - LLM 호출과 에이전트 trace를 한 곳에서 보는 오픈소스 관측 플랫폼

Spanlens — LLM 호출과 에이전트 trace를 한 곳에서 보는 오픈소스 관측 플랫폼

Spanlens - LLM 호출과 에이전트 trace를 한 곳에서 보는 오픈소스 관측 플랫폼

LLM 기반 서비스를 운영하다 보면 두 가지 질문이 항상 따라붙습니다. "이번 달 OpenAI 청구서가 왜 이렇게 나왔지?" 그리고 "방금 끝난 에이전트 trace는 왜 이렇게 오래 걸렸지?" Spanlens는 이 두 가지 고질적 문제를 한 화면에서 해결하기 위해 태어난 오픈소스 관측 플랫폼입니다. 본문에서는 Spanlens가 어떤 동기로 만들어졌고, 어떤 기능을 제공하는지, 그리고 직접 셀프호스팅하는 방법까지 정리합니다.

왜 Spanlens가 필요한가

LLM 서비스의 운영 비용과 디버깅은 전통적인 웹 서비스와 결이 다릅니다. 일반적인 REST API는 호출당 비용이 거의 고정적이고 응답 시간이 ms 단위로 일정하지만, LLM API는 모델별 단가가 다르고 토큰 사용량에 따라 비용이 비선형적으로 늘어납니다. 또한 에이전트 워크플로우처럼 여러 LLM 호출이 그래프 형태로 얽혀 있으면, 어떤 경로가 병목인지 손으로 로그를 따라가야 하는 경우가 많습니다.

Spanlens는 이 두 문제를 동시에 짚습니다. 첫째는 비용 가시성, 둘째는 에이전트 trace 시각화입니다. 단순한 로그 수집을 넘어, "이 trace가 느린 이유"를 자동으로 분석해주는 도구를 지향합니다.

핵심 기능 4가지

1. baseURL 한 줄 통합

OpenAI, Anthropic, Gemini SDK의 baseURL을 Spanlens 프록시 주소로 바꾸는 것만으로 모든 요청과 응답이 자동 기록됩니다. 응답은 그대로 passthrough 되기 때문에 스트리밍, tool calling, JSON mode 등 원본 동작이 그대로 유지됩니다. 코드 수정 없이 한 줄만 바꾸면 로깅이 시작된다는 점이 매력적입니다.

에이전트처럼 wrap 방식이 더 자연스러운 경우에는 SDK로 trace_id와 span_id를 주입해 부모 자식 관계까지 기록할 수 있습니다. 단순한 시퀀스 로그가 아니라, 호출 간 위계가 보존된 trace 데이터가 만들어집니다.

2. 에이전트 trace와 LangGraph 토폴로지 뷰

시간순 타임라인뿐 아니라 실제 그래프 노드 위에 trace를 얹어서 보여줍니다. LangGraph로 작성한 에이전트라면 어느 노드에서 시간이 많이 소요되었는지, 어느 엣지가 가장 자주 호출되는지를 한 화면에서 확인할 수 있습니다. 그래프 형태의 시각화는 평행 호출이나 분기 구조가 있는 에이전트에서 특히 유용합니다.

3. Critical Path 자동 분석

trace 안에서 latency를 가장 많이 잡아먹은 호출 체인을 자동으로 표시해줍니다. "이 trace는 왜 느렸지?"라는 질문에 답하기 위해 클릭을 여러 번 해야 했던 기존 도구들과 달리, Spanlens는 가장 의심스러운 경로를 즉시 제시합니다. 성능 최적화 포인트를 찾는 데 들어가는 시간을 크게 줄여줍니다.

4. Prompts A/B 통계 비교

같은 프롬프트의 두 버전을 latency, 비용, 토큰 사용량 기준으로 비교할 수 있습니다. 단순한 평균 차이가 아니라 Welch t-test를 적용해 표본 분산까지 고려한 차이를 보여주기 때문에, "그냥 평균이 좀 낮네" 수준이 아니라 "통계적으로 유의미한 차이다"라는 결론을 내릴 수 있습니다. n이 작을 때 경고를 띄우는 방식 등 UX 디테일도 고민 중이라고 합니다.

셀프호스팅과 스택

전체 코드가 MIT 라이선스로 공개되어 있어, Docker 이미지로 직접 서버에 띄울 수 있습니다. SaaS 버전과 동일한 코드가 public 레포에 그대로 들어 있어, 운영 환경에 맞게 커스터마이징도 가능합니다.

기술 스택은 Next.js 14, Hono, Supabase Postgres, ClickHouse, 그리고 전부 TypeScript로 구성된 pnpm monorepo입니다. 프록시 요청은 Hono로 받아서 Authorization 헤더와 메타데이터를 분리하고, provider key는 AES-256-GCM으로 메모리에서만 복호화해 사용합니다. 스트리밍 응답은 body.tee()로 원본을 클라이언트에 즉시 반환하면서, 복사본은 백그라운드에서 파싱해 토큰과 비용을 계산합니다.

로그는 ClickHouse에 비동기로 적재되고, INSERT 실패 시 Supabase 폴백 큐로 보관된 뒤 cron이 재시도하는 구조입니다. 모델 가격 정보는 DB 테이블에 두고 5분 TTL의 stale-while-revalidate로 캐싱해 콜드스타트 안전망까지 마련되어 있습니다.

직접 써보기

먼저 spanlens.io에서 데모 버전을 확인해 볼 수 있습니다. 실제 트래픽을 흘려보기 전이라도 UI 감각을 익히기에 충분합니다. 이후 자신의 프로젝트에 적용할 때는 OpenAI SDK의 baseURL을 api.spanlens.io/proxy/openai/v1 형태로 바꾸기만 하면 됩니다. 기존 코드는 그대로 두고 호출 패턴과 비용, latency가 기록되는 것을 확인할 수 있습니다.

운영 환경의 데이터를 다루어야 한다면 self-host 가이드가 공개되어 있으므로, docker compose로 web, server, ClickHouse 3개 컨테이너를 띄우면 됩니다. 현재는 managed Supabase 전제이지만, 한 줄 docker run으로 완성하려면 Supabase 자체 호스팅 옵션까지 함께 제공할지 제작자가 고민 중이라고 합니다.

전망과 한 줄 정리

LLM 서비스를 본격적으로 운영하기 시작하면, 비용 최적화와 trace 디버깅은 곧바로 핵심 과제가 됩니다. 콘솔 로그와 스프레드시트를 들고 다니는 일은 비효율적이며, 멀티 에이전트 워크플로우에서는 사실상 불가능에 가깝습니다. Spanlens는 이 자리에 들어갈 수 있도록 설계된 경량 오픈소스 도구입니다. 한 줄 baseURL 변경으로 시작하고, 필요해지면 통계 기반 A/B 비교와 Critical Path 분석까지 활용할 수 있다는 점에서, LLM 서비스를 운영하거나 실험하는 개발자라면 한 번 시도해볼 만합니다.

핵심 정리

• LLM 호출 로깅을 baseURL 교체 한 줄로 시작

• LangGraph 에이전트 토폴로지 뷰와 Critical Path 자동 분석

• Prompts A/B 비교에 Welch t-test 적용

• MIT 라이선스, Docker로 셀프호스팅 가능

• TypeScript 모노레포, ClickHouse + Supabase 기반

---

📚 출처

• https://news.hada.io/topic?id=30076