Loupe: LLM 앱 개발자를 위한 경량 로컬 트레이싱 대시보드

섹션별 상세

Loupe는 로컬 개발 단계에서 발생하는 구체적인 질문들인 페이로드 내용, 도구 인자, 실행 속도 저하 원인 등에 즉각적인 답변을 제공하도록 설계되었다.

UI는 세션 중심의 뷰를 제공하며, 대화 타임라인에서 사용자 메시지, 어시스턴트 응답, 도구 호출 및 결과를 한눈에 파악할 수 있도록 시각화한다.

Loupe의 대화 타임라인 뷰 스크린샷 — Screenshot사용자 메시지, 어시스턴트 응답, 그리고 도구 호출(Tool Call)과 그 결과가 하나의 타임라인에 통합되어 표시되는 모습을 보여준다. 각 단계별 실행 시간과 상태(OK)를 직관적으로 확인할 수 있다.

Loupe의 상세 요청 페이로드 JSON 뷰 — Screenshot모델에 전달된 실제 JSON 요청 데이터를 구조화하여 보여준다. 시스템 프롬프트, 사용자 입력, 도구 정의 등이 정확히 어떻게 전송되었는지 검증하는 용도로 사용됨을 알 수 있다.

OpenAI 공식 클라이언트를 사용하는 경우 wrapOpenAIClient 함수를 통해 기존 코드를 거의 수정하지 않고도 트레이싱 기능을 통합할 수 있다.

javascript

import { wrapOpenAIClient } from '@mtharrison/loupe';
import OpenAI from 'openai';

const client = wrapOpenAIClient(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  () => ({
    sessionId: 'session-123',
    rootSessionId: 'session-123',
    rootActorId: 'support-assistant',
    actorId: 'support-assistant',
    provider: 'openai',
    model: 'gpt-4.1',
    stage: 'answer',
    tags: {
      feature: 'support',
      environment: 'local',
    },
  }),
);

const response = await client.chat.completions.create({
  model: 'gpt-4.1',
  messages: [
    { role: 'user', content: 'Summarise the latest customer notes.' },
  ],
});

OpenAI 클라이언트를 래핑하여 트레이싱 기능을 활성화하는 코드 예시

보안을 위해 인증 헤더인 Authorization과 x-api-key는 자동으로 마스킹 처리되며, 모델이 사용량 정보를 제공할 경우 비용 합산 기능도 지원한다.

데이터 영속성이 없는 인메모리 방식을 사용하여 재시작 시 모든 트레이스가 초기화되는데, 이는 로컬 반복 개발 시 데이터 관리에 대한 부담을 줄여주는 의도된 특징이다.

용어 해설

트레이싱(Tracing): — 애플리케이션의 실행 흐름과 각 단계에서 발생하는 데이터를 기록하고 추적하는 과정이다. LLM 개발에서는 프롬프트 입력부터 모델 응답, 도구 호출까지의 전체 과정을 시각화하여 디버깅을 용이하게 한다.
페이로드(Payload): — API 요청이나 응답 시 전송되는 실제 데이터 본문을 의미한다. LLM 컨텍스트에서는 모델에 전달되는 메시지 배열, 온도 설정, 도구 정의 등 구체적인 JSON 데이터를 포함한다.
도구 호출(Tool Calling): — LLM이 외부 함수나 API를 실행해야 한다고 판단하고 필요한 인자를 생성하는 기능이다. 에이전트가 실시간 정보를 검색하거나 계산을 수행하는 등 외부 세계와 상호작용하는 핵심 메커니즘이다.
인메모리(In-memory): — 데이터를 디스크가 아닌 RAM에 저장하여 처리하는 방식이다. 속도가 매우 빠르지만 프로세스가 종료되면 데이터가 사라지는 휘발성을 가지며, Loupe는 이를 활용해 로컬 개발 시 데이터 관리 부담을 줄였다.

기술

OpenAI API
npm
JavaScript
SSE (Server-Sent Events)

활용 사례

로컬 LLM 에이전트 디버깅
도구 호출 인자 및 결과 검증
스트리밍 응답 지연 시간 분석
프롬프트 변경 사항에 따른 페이로드 비교

언급된 리소스

GitHubLoupe GitHub Repository

문서@mtharrison/loupe npm package

import { wrapOpenAIClient } from '@mtharrison/loupe'; import OpenAI from 'openai'; const client = wrapOpenAIClient( new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), () => ({ sessionId: 'session-123', rootSessionId: 'session-123', rootActorId: 'support-assistant', actorId: 'support-assistant', provider: 'openai', model: 'gpt-4.1', stage: 'answer', tags: { feature: 'support', environment: 'local', }, }), ); const response = await client.chat.completions.create({ model: 'gpt-4.1', messages: [ { role: 'user', content: 'Summarise the latest customer notes.' }, ], });

Loupe: LLM 앱 개발자를 위한 경량 로컬 트레이싱 대시보드

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

Loupe: LLM 앱 개발자를 위한 경량 로컬 트레이싱 대시보드

섹션별 상세

용어 해설

기술

활용 사례

언급된 리소스

관련 토론

댓글

관련 기사

Spring AI Playground 공개와 에이전트 관찰성용 인앱 대시보드

관련 토론

댓글

관련 기사

Spring AI Playground 공개와 에이전트 관찰성용 인앱 대시보드