Traceloop

Traceloop

Traceloop은 LLM(대규모 언어 모델) 애플리케이션의 품질을 자동으로 모니터링하고 디버깅·테스트할 수 있게 해주는 LLM 옵저버빌리티(관측성) 플랫폼이에요. "Monitor, debug and test the quality of your LLM outputs"라는 슬로건처럼, 모델과 프롬프트를 바꿀 때 기존 기능을 망가뜨리지 않으면서 자신 있게 배포할 수 있게 도와줘요. 오픈소스 SDK인 OpenLLMetry를 오픈텔레메트리(OpenTelemetry) 기반으로 제공해서, 트레이스를 Traceloop뿐 아니라 이미 쓰고 있는 옵저버빌리티 스택으로도 내보낼 수 있답니다.

출처: 문서

본문

Traceloop은 LLM 출력의 품질을 실시간으로 모니터링해요. 주요 기능을 정리하면 이렇게 돼요.

주요 기능

LLM 트레이싱 / 옵저버빌리티

  • 요청 하나하나에 대한 실행 트레이싱(Execution Tracing)을 제공해요.
  • 실시간으로 모델 품질에 대한 알림(Alert)을 받을 수 있어요.
  • 모델과 프롬프트 변경을 점진적으로 롤아웃(rollout)할 수 있어요.
  • 프로덕션에서 발생한 이슈를 IDE에서 디버깅하고 다시 실행해볼 수 있어요.
  • 복잡한 워크플로우나 체인을 @workflow 같은 애노테이션으로 표시하면 전체 트레이스를 볼 수 있어요.
  • 지원되는 LLM 프레임워크를 쓰면 코드에 애노테이션을 추가할 필요 없이 자동으로 트레이싱돼요.

오픈텔레메트리(OpenTelemetry) 기반

OpenLLMetry는 오픈텔레메트리 위에 만들어진 오픈소스 프로젝트예요. 비침투적(non-intrusive) 방식으로 트레이싱이 이뤄지며, 트레이스를 Traceloop으로 보낼 수도 있고 Datadog, Honeycomb, Dynatrace, Sentry, Grafana 등 기존 옵저버빌리티 스택으로도 내보낼 수 있어요. OpenTelemetry Collector를 쓰는 경우, 컬렉터 설정에 OTLP exporter만 추가하면 트레이스를 Traceloop으로 라우팅할 수 있어요.

평가(Evaluation)

평가 라이브러리는 LLM 출력, 데이터 품질, 성능을 다양한 차원에서 측정하는 Traceloop의 핵심 기능이에요.

  • 커스텀 평가기(Custom Evaluators) – 자신의 평가 로직을 만들어 쓸 수 있어요.
  • 빌트인 평가기(Built-in Evaluators / Made by Traceloop) – Traceloop이 공통 평가 작업을 위해 미리 구성해둔 평가기예요.
  • 평가기는 Guardrails(실시간 안전 검사), Playgrounds, Experiments(SDK로 데이터셋에 대한 체계적 평가 실행), Monitors(프로덕션 품질 모니터링) 등 여러 곳에서 사용돼요.
  • 에이전트가 도구를 환각(hallucinate)하거나 루프에 빠지는 등의 실패 모드를 잡아내고, 정확성·관련성·안전성·스타일 등을 검사해서 신뢰할 수 있는 시스템을 만들 수 있어요.

모니터링(Monitoring)

Traceloop은 LLM 출력 품질을 실시간으로 모니터링해서 환각(hallucination)과 품질 회귀(regression)를 감지해요.

  • Monitor는 특정 특성을 가진 span 그룹에 대해 실시간으로 실행되는 평가기예요.
  • LLM-as-a-Judge – 대규모 언어 모델로 의미적 품질을 평가해요.
  • Traceloop built-in evaluators – 구조 검증, 안전 검사, 구문 분석 등을 위한 결정적(deterministic) 평가예요.

SDK 설치

오픈소스 SDK인 OpenLLMetry는 Python, Node.js(Typescript), Go, Ruby를 지원해요.

Python(OpenLLMetry)은 터미널에서 이렇게 설치해요.

pip install traceloop-sdk

poetry를 쓰면 이렇게 해요.

poetry add traceloop-sdk

Node.js(Typescript)는 이렇게 설치해요.

npm install @traceloop/node-server-sdk

pnpm add @traceloop/node-server-sdk

yarn add @traceloop/node-server-sdk

사용 예시

LLM 앱에서 트레이서를 초기화해요.

from traceloop.sdk import Traceloop

Traceloop.init()

로컬에서 실행 중이라 배치 전송을 꺼서 트레이스를 즉시 보고 싶다면 이렇게 해요.

Traceloop.init(disable_batch=True)

Node.js에서는 이렇게 초기화해요.

import * as traceloop from "@traceloop/node-server-sdk";

traceloop.initialize();

⚠️ JavaScript의 동작 방식 때문에 OpenAI 같은 LLM 모듈을 import하기 전에 Traceloop SDK를 먼저 import해야 해요.

복잡한 워크플로우는 @workflow 데코레이터로 애노테이션할 수 있어요.

from traceloop.sdk.decorators import workflow

@workflow(name="suggest_answers")
def suggest_answers(question: str):
  ...

# async 함수에서도 잘 동작해요
@workflow(name="summarize")
async def summarize(long_text: str):
  ...

Node.js에서는 함수형 withWorkflow()나 클래스 메서드 데코레이터를 써요.

async function suggestAnswers(question: string) {
  return await withWorkflow({ name: "suggestAnswers" }, () => {
    ...
  });
}

class MyLLM {
  @traceloop.workflow({ name: "suggest_answers" })
  async suggestAnswers(question: string) {
    ...
  }
}

마지막으로 트레이스를 어디로 내보낼지 설정해요. 트레이스 전송을 제어하는 환경 변수는 TRACELOOP_API_KEY와 TRACELOOP_BASE_URL이에요. Traceloop Cloud를 쓰려면 앱에서 API 키를 발급받아 환경 변수로 설정하면 돼요.

export TRACELOOP_API_KEY=your_api_key_here

OpenTelemetry Collector를 쓰는 경우엔 컬렉터 설정에 OTLP exporter를 추가해서 Traceloop으로 트레이스를 보낼 수 있어요.

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch:
exporters:
  otlphttp/traceloop:
    endpoint: "https://api.traceloop.com" # US instance
    headers:
      "Authorization": "Bearer <YOUR_API_KEY>"
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/traceloop]

이렇게 하면 LLM 호출뿐 아니라 벡터 DB나 외부 서비스·데이터베이스 호출까지도 Traceloop 대시보드에서 확인할 수 있어요.

더 알아보기 (Learn more)