Lunary

Lunary

Lunary는 AI 챗봇이나 LLM 기반 애플리케이션을 만드는 개발자를 위한 오픈소스 LLM 옵저버빌리티 플랫폼이에요. LLM 호출을 트레이싱하고, 비용과 지연 시간을 분석하고, 프롬프트를 버전 관리하며 협업할 수 있게 도와줘요. Python, JavaScript, LangChain 등 인기 있는 AI 라이브러리를 쉽게 연동할 수 있어요. 좀 더 자세히 살펴볼까요?

출처: 문서

본문

주요 기능

Lunary는 크게 세 가지 관찰(observability) 기능을 제공해요. 바로 Analytics(분석), Logs(로그), Traces(트레이싱) 인데, SDK를 연동하기만 하면 대부분 자동으로 수집돼요.

  • Analytics (분석) — 아래 지표를 자동으로 수집해요.

    • 💰 Costs: LLM 모델 사용으로 발생한 비용
    • 📊 Usage: LLM 호출 횟수와 사용된 토큰 수
    • ⏱️ Latency: LLM 호출과 에이전트의 평균 지연 시간
    • ❗ Errors: LLM 호출과 에이전트에서 발생한 오류 수
    • 👥 Users: 주요 사용자의 시간별 사용량

  • Logs (로그) — LLM 요청과 응답을 로깅하고 검사할 수 있어요. SDK 연동 시 자동으로 기록돼요.

  • Traces (트레이싱) — 복잡한 AI 에이전트를 디버깅하고 문제를 해결하는 데 유용해요. wrapAgent, wrapChain, wrapTool 같은 유틸리티 래퍼를 사용하면 에이전트와 도구의 입력·출력·오류가 자동으로 추적돼요.

  • Prompts (프롬프트 관리) — 프롬프트 템플릿을 저장·버전 관리·협업할 수 있어요. 소스 코드를 정리하고, 코드 재배포 없이 프롬프트를 수정하거나, 비개발자 팀원과 함께 작업하고, A/B 테스트를 할 수 있어요.

  • Chats & Threads — 챗봇 대화와 사용자 피드백을 추적해요.

  • Product Analytics / Classification — 제품 분석과 대화 주제 분류 기능도 제공해요.

  • Evaluations (평가) — LLM 평가 기능도 준비 중이에요 (문서는 "coming soon" 상태).

SDK 설치

Lunary를 쓸 때는 먼저 앱에 가입해서 고유한 tracking ID(공개 키)를 받아야 해요.

Python (Python 3.10 이상 권장):

pip install lunary

Anthropic 공식 SDK를 모니터링하고 싶다면 두 패키지를 함께 설치해요.

pip install lunary anthropic

환경 변수로 공개 키를 설정해요.

export LUNARY_PUBLIC_KEY="PUBLIC KEY"

JavaScript / Node:

npm install lunary

lunary 모듈은 가벼워서 Node JS, Deno, Cloudflare Workers, Vercel Edge functions, Bun에서도 동작해요. 모듈을 불러와서 .init 메서드로 초기화해요.

import lunary from "lunary";

// 앱 ID로 Lunary 모듈 초기화
lunary.init({
  publicKey: "0x0",
});

사용 예시 — OpenAI 연동

SDK가 OpenAI 모듈과 자동으로 연동돼요. Python에서는 lunary.monitor(client) 한 줄로 모든 OpenAI 호출을 모니터링할 수 있어요.

from openai import OpenAI
import lunary

client = OpenAI()

lunary.monitor(client)  # 이 줄이 'openai' 모듈을 통한 모든 호출 모니터링을 설정해요

chat_completion = client.chat.completions.create(
  model="gpt-4o",
  messages=[{"role": "user", "content": "Hello world"}]
)

JavaScript에서는 monitorOpenAI로 OpenAI 인스턴스를 감싸서 요청을 자동으로 추적해요.

import OpenAI from "openai";
import { monitorOpenAI } from "lunary/openai";

// OpenAIApi 클래스에 monitor()를 호출하면 요청이 자동으로 추적돼요
const openai = monitorOpenAI(new OpenAI());

요청에 태그를 달거나 사용자를 식별할 수도 있어요.

chat_completion = client.chat.completions.create(
  model="gpt-4o",
  user_id="user_123",            # 선택: 사용자 ID
  user_props={"name": "John Doe"},  # 선택: 사용자 속성
  tags=["chat", "support"],      # 선택: 태그
  messages=[{"role": "user", "content": "Hello world"}]
)

사용 예시 — 에이전트·도구 트레이싱

wrapAgent로 에이전트 함수를 감싸면 입력·출력·오류가 자동으로 추적되고, 안에서 실행되는 도구와 로그도 올바른 에이전트에 연결돼요.

const myAgent = lunary.wrapAgent(async function MyAgent(input) {
  // 에이전트 커스텀 로직
  // ...
})

await myAgent("Hello, how are you?")

Python에서는 데코레이터로 같은 작업을 해요.

import lunary

@lunary.agent()
def MyAgent(input): # 에이전트 커스텀 로직
  pass

도구를 추적하고 싶다면 wrapTool(JS) 또는 @lunary.tool()(Python)을 사용해요. 감싼 도구가 감싼 에이전트 안에서 실행되면 자동으로 그 에이전트에 연결돼요.

사용 예시 — 프롬프트 템플릿

프롬프트 템플릿을 OpenAI API와 함께 사용하면 프롬프트 추적이 자동으로 이뤄져요. renderTemplate로 변수를 주입하고 완성된 템플릿을 그대로 요청에 넘겨요.

import OpenAI from "openai";
import lunary from "lunary"
import { monitorOpenAI } from "lunary/openai";

// OpenAI 인스턴스를 monitorOpenAI로 감싸주세요
const openai = monitorOpenAI(new OpenAI())

const template = await lunary.renderTemplate("template-slug", {
  name: "John", // 변수 주입
})

const result = await openai.chat.completions.create(template)

Python에서도 동일하게 사용할 수 있어요.

client = OpenAI()

# OpenAI 클라이언트를 모니터링하세요
lunary.monitor(client)

template = lunary.render_template("template-slug", {
  "name": "John", # 변수 주입
})

result = client.chat.completions.create(**template)

직접 특정 LLM API를 쓸 때도 템플릿에서 messages, model, temperature, max_tokens 같은 필드만 꺼내서 사용할 수 있어요.

더 알아보기 (Learn more)