저는 작은 LLM 에이전트들을 만듭니다. 데모에서 보는 인상적인 종류가 아니라, 고객 지원 질문에 답하거나 문서를 뒤져서 답변을 가져오는 것과 같은 실용적이고 작은 것들 말이죠. 그리고 몇 달 동안 가장 짜증 났던 부분은 모델이나 프롬프트 (Prompt)가 아니었습니다. 그것이 실제로 무엇을 하고 있는지 전혀 알 수 없다는 점이었습니다.

그 느낌을 아실 겁니다. 실행에 9초가 걸리는데 왜 그런지는 모릅니다. 도구 (Tool)를 한 번 호출하고, 다시 호출하고, 세 번째로 호출하고, 그 과정 어딘가에서 40센트를 써버립니다. 로그 (Logs)는 JSON의 벽입니다. 프롬프트를 수정하고 배포하지만, 사용자가 불평하기 전까지는 그것을 더 좋게 만들었는지 아니면 더 나쁘게 만들었는지 진심으로 알 수 없습니다. 저는 마치 2015년인 것처럼 print() 출력물을 뚫어지게 쳐다보고 있었습니다.

그래서 제 에이전트 실행 과정을 그냥 보여줄 수 있는 무언가를 찾아 나섰습니다. 도구들이 존재하긴 합니다. 괜찮은 것들도 있고, 정말 좋은 것들도 있지만, 그것들은 모두 제가 주고 싶지 않은 것을 요구했습니다.

저를 계속 괴롭혔던 두 가지

호스팅형 (Hosted) 도구들은 당신의 트레이스 (Traces)를 자신들의 서버에 저장하기를 원합니다. 이는 제게 있어 프롬프트, 즉 실제 고객 메시지가 제가 대시보드를 볼 수 있도록 다른 사람의 데이터베이스에 앉아 있게 된다는 것을 의미합니다. 사양하겠습니다.

셀프 호스팅 (Self-hostable)이 가능한 도구들은 기업을 위해 만들어졌으며, 그 특징이 고스란히 드러납니다. 모두가 추천하는 도구는 실행을 위해 Postgres와 ClickHouse, Redis, 그리고 S3 버킷이 모두 필요합니다. 네 개의 상태 저장 서비스 (Stateful services)가 필요한 것이죠. 저는 사이드 프로젝트에서 하루에 아마 몇 천 번 정도의 모델 호출을 기록하고 있을 뿐입니다. 그것을 확인하기 위해 ClickHouse 클러스터를 구축하는 것은 식료품 봉지를 옮기기 위해 지게차를 빌리는 것과 같습니다.

저는 잠시 고민하다가 이 불일치 자체가 문제라는 것을 깨달았습니다. 이것은 기업 규모의 데이터가 아닙니다. 제 노트북 규모의 데이터입니다. 그리고 그 사실을 받아들이는 순간, 설계는 아주 좋은 의미로 정말 지루해집니다. 그냥 SQLite 파일이 있는 웹 앱일 뿐입니다. 그게 전부입니다. 하나의 프로세스 말이죠.

그래서 저는 그것을 만들었습니다. 이름은 Otterscope입니다.

이것의 실체

이것은 하나의 Go 바이너리입니다. 실행하면 SQLite 파일을 열고, 표준 포트에서 OpenTelemetry 트레이스 (traces)를 수신합니다. 모든 OpenTelemetry 설정에서 이미 사용 중인 것과 동일한 환경 변수 하나로 에이전트를 이 도구에 연결하기만 하면, 실행 기록 (runs)이 나타나기 시작합니다. 계정도, 설정 파일도, 관리해야 할 다른 서비스도 필요 없습니다.

제가 가장 신경 써서 제대로 만들고 싶었던 부분은 데이터의 '형태 (shape)'였습니다. 다른 모든 도구들은 OpenTelemetry의 기본 단위인 스팬 (spans)을 보여주는데, 이는 마치 스택 트레이스 (stack trace)처럼 읽힙니다. 저는 실행 기록 (runs)을 원했습니다. 하나의 에이전트 실행은 하나의 실행 기록이며, 그 내부에서 단계들을 볼 수 있습니다. 즉, 이 LLM 호출, 저 도구 호출, 그리고 동일한 도구를 세 번 호출한 루프 같은 것들 말이죠. 호출을 클릭하면 입력되고 출력된 실제 메시지를 읽을 수 있으며, 토큰 수와 비용이 바로 그 자리에 표시됩니다. 무언가 잘못되었을 때, 실제로 어디서 문제가 생겼는지 확인할 수 있습니다.

주요 제공업체들의 현재 가격을 알고 있는 비용 테이블이 있어, 실행 기록은 단순히 얼마나 많은 토큰을 소모했는지가 아니라 비용이 얼마 들었는지를 알려줍니다. 만약 제가 가격 정보를 가지고 있지 않은 모델을 사용한다면, 토큰 수는 보여주되 달러 금액을 모른다는 사실을 정직하게 표시합니다. 이는 들리는 것보다 훨씬 중요한 문제인데, 저는 지어낸 숫자보다는 차라리 빈칸을 보는 편을 택하겠습니다.

그리고 제가 가장 애착을 느끼는 부분이 있습니다. 바로 평가 (evals)가 트레이스 (traces)와 같은 곳에 존재한다는 점입니다. 체크 사항을 작성하거나 (

만약 여러분이 이런 도구를 만든다면, 아무도 경고해주지 않는 사실이 하나 있습니다. 바로 AI 트레이스 (traces)를 위한 단일 형식이 존재하지 않는다는 점입니다. 현재 최소 세 가지 형식이 실전에서 사용되고 있으며, 이들은 서로 일치하지 않습니다.

OpenTelemetry에는 "GenAI" 컨벤션 (convention)이 있지만, 현재 마이그레이션 (migration) 중간 단계에 있어서 오래된 속성 레이아웃 (attribute layout)과 새로운 레이아웃이 모두 존재하며, 오늘날 실제 도구들에서 이 두 가지가 모두 방출되고 있습니다. 그다음으로 Arize의 OpenInference가 있는데, 이는 독자적인 방식이며 OpenAI Agents SDK와 LangChain 생태계의 상당수가 사용하는 방식입니다. 마지막으로 Vercel AI SDK는 자체적인 ai.* 속성을 사용하는데 — 이 부분이 아주 골치 아픈 부분입니다 — 이들의 스팬 (spans)은 동일한 스팬 내에서 기존 방식과 새로운 OpenTelemetry 스타일을 혼합해서 사용합니다. 따라서 하나의 속성을 기준으로 추측하면 틀리게 됩니다.

그래서 Otterscope의 큰 부분은 이 모든 것을 받아들여 하나의 깔끔한 모델로 변환하는 번역 레이어 (translation layer) 역할을 합니다. 프로젝트에서 가장 화려하지 않은 코드일지 모르지만, 아마도 가장 가치 있는 코드일 것입니다. 여러분이 사용하는 프레임워크가 어떤 방언을 사용하는지 신경 쓸 필요가 없다는 것을 의미하기 때문입니다. 또한 들어오는 모든 데이터의 원시 페이로드 (raw payload)를 보관하기 때문에, 나중에 번역 로직을 개선하면 이전 데이터를 새 버전으로 다시 재생 (replay)하여 소급적으로 품질을 높일 수 있습니다. 이 작업은 충분히 할 가치가 있다고 느꼈습니다.

이것이 아닌 것

현재는 단일 사용자용입니다. 로그인, 팀, 역할 (roles) 기능은 없습니다. 이는 의도된 설계입니다. 저는 제가 필요로 하는 것을 만들었고, 저는 혼자이기 때문입니다. 기본적으로 localhost에 바인딩되어 실수로 외부에 노출되는 것을 방지하며, 실제 인증 기능이 포함된 팀 버전을 원하신다면 그것은 "누군가 실제로 요청할 때" 만드는 기능이지, "스프레드시트에 B2B라고 적혀 있어서 미리 만드는" 기능이 아닙니다.

또한 아직 초기 단계입니다. 다듬어지지 않은 부분이 있을 것입니다. 하지만 제가 원했던 것, 즉 눈을 감고 비행하는 것(flying blind)을 멈추는 기능은 수행합니다.

사용해보기

가장 빠른 방법은 Docker를 사용하는 것입니다:

docker run -p 8317:8317 -p 4318:4318 -v otterscope:/data ghcr.io/otterscope/otterscope

그다음 OpenTelemetry가 적용된(instrumented) 어떤 에이전트든 http://localhost:4318로 지정하고, http://localhost:8317을 여세요. 먼저 이것저것 클릭해보고 싶다면 가짜 실행 데이터(fake runs)로 채워주는 sample 명령어가 있습니다. 저장소(Repo)에는 Pydantic AI, OpenAI Agents SDK, LangGraph, 그리고 Vercel AI SDK를 위한 설정 스니펫(setup snippets)이 포함되어 있습니다.

저장소 주소: https://github.com/otterscope

노트북 대신 서버에서 실행하고 싶다면, 소형 VPS에서 전체 과정을 별도로 정리해 두었습니다 — 인스턴스 생성부터 Docker와 systemd 서비스의 비교, 그리고 SSH 터널을 통해 비공개로 유지하거나 방화벽으로 보안을 강화하는 방법까지 다룹니다: Self-hosting observability for your AI agents on a $6 Droplet.

몇몇 분들이 물어보셔서, 왜 DigitalOcean인지 알려드립니다

이 도구의 핵심 정체성이 "작고 예측 가능함(small and predictable)"이기 때문이며, 도구가 실행되는 서버 또한 그러하기를 원하기 때문입니다.

$6짜리 Droplet에서도 이 도구는 여유롭게 돌아갑니다. 데이터베이스가 파일 형태이기 때문에 별도의 관리형 데이터베이스(managed database) 비용이 추가로 발생하지 않습니다 — 저는 파일을 복사하거나 Droplet의 스냅샷(snapshot)을 찍는 방식으로 백업을 완료하며, 그것으로 충분합니다. 가격이 고정되어 있어 머릿속으로 계산이 가능하며, 이는 프로젝트의 핵심 목적이 사이드 프로젝트를 위해 예상치 못한 인프라 비용을 지불하지 않는 것일 때 매우 중요합니다. 월말에 어떤 데이터 전송(egress) 항목 때문에 절약한 비용이 다 깎여나갔다는 사실을 알게 되고 싶지는 않으니까요.

또한, 사용하면서 즐거웠습니다. 문서(docs)는 읽기 편하고, Droplet은 1분 이내에 생성되며, Marketplace의 Docker 이미지를 사용하면 "컨테이너를 실행할 수 있는 서버를 띄우는 것"이 오후 내내 걸리는 작업이 아니라 체크박스 하나를 선택하는 수준이 됩니다. 하나의 바이너리, 하나의 파일, 그리고 에이전트 옆에 놓인 하나의 작은 서버와 같은 이런 도구에는 이 방식이 딱 들어맞습니다. 그것이 정말 전부인 이유입니다.

어쨌든, 만약 여러분이 에이전트 로그를 뚫어지게 쳐다보며 고생하고 있다면, 무언가를 셀프 호스팅 (self-host) 해서 사용하고 그만두세요. 꼭 제가 만든 것이 아니어도 상관없지만, 알고 보니 정말 복잡할 필요가 없더라고요.