LangSmith 트레이싱 퀵스타트

기껏 만든 LLM 앱이 '왜' 그렇게 답했는지 눈으로 확인하고 싶다면, 트레이싱부터 시작하는 게 가장 좋아요. LangSmith는 요청 동안 실행된 모든 단계(입력부터 최종 출력까지)의 완전한 기록인 트레이스를 캡처해 앱 전체를 들여다볼 수 있게 해줘요. 이 퀵스타트에서는 AI 어시스턴트에 트레이싱을 추가하고 결과를 LangSmith에서 확인해 볼게요.

출처: 공식문서

팁: LangChain이나 LangGraph로 빌드하고 있다면, 환경 변수 하나만으로 LangSmith 트레이싱을 켤 수 있어요. trace with LangChain 또는 trace with LangGraph를 참고하세요.

사전 준비

시작하기 전에 다음이 필요해요.

LangSmith 계정: smith.langchain.com에서 가입하거나 로그인해요.
LangSmith API 키: Create an API key 가이드를 따르세요.
OpenAI API 키: OpenAI 대시보드에서 생성해요.

이 예시는 LLM 프로바이더로 OpenAI를 사용하지만, 자신의 프로바이더에 맞게 바꿀 수 있어요.

1. 환경 설정

프로젝트 디렉터리를 만들고 의존성을 설치한 뒤, 필요한 환경 변수를 설정해요.

mkdir ls-quickstart && cd ls-quickstart
python -m venv .venv && source .venv/bin/activate
pip install -U langsmith openai

셸에서 환경 변수를 내보내요.

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>"

특정 프로젝트로 트레이스를 보내려면 LANGSMITH_PROJECT 환경 변수를 사용해요. 설정하지 않으면 LangSmith가 트레이스 수집 시 기본 트레이싱 프로젝트를 자동으로 만들어요.

참고: 계정이 기본값인 US가 아닌 다른 리전에 있다면, LANGSMITH_ENDPOINT도 해당 리전의 API URL로 설정해야 해요. 그렇지 않으면 API 키가 인식되지 않아 인증 요청이 실패해요. 예를 들어 EU 계정은 export LANGSMITH_ENDPOINT="https://eu.api.smith.langchain.com"처럼요. URL 끝에 슬래시를 붙이지 마세요 — 붙이면 인증 오류가 날 수 있어요.

Anthropic을 쓴다면 Anthropic 래퍼, Google Gemini를 쓴다면 Gemini 래퍼를 사용해요. 그 외 프로바이더는 @traceable 데코레이터로 호출을 수동 트레이싱해요.

2. 앱 만들기

아래 앱은 두 가지 LangSmith 도구를 사용해 트레이싱을 추가해요.

OpenAI wrapper: OpenAI 클라이언트를 감싸 모든 LLM 호출을 중첩된 span으로 자동 기록해요.
Traceable wrapper: 함수를 감싸 입력, 출력, 그리고 중첩된 span들이 LangSmith에서 하나의 트레이스로 보이게 해요. Python에서는 @traceable, TypeScript와 Kotlin에서는 traceable, Java에서는 Tracing.traceFunction을 사용해요.

assistant 함수는 도구(get_context)를 호출해 관련 컨텍스트를 가져온 뒤, 그 컨텍스트를 모델에 전달해요. 두 함수 모두에 traceable wrapper를 적용하면 도구 호출과 LLM 호출이 중첩 span으로서 하나의 트레이스에 모두 캡처돼요.

app.py 파일을 만들고 아래 코드를 넣어요.

from openai import OpenAI
from langsmith.wrappers import wrap_openai
from langsmith import traceable

client = wrap_openai(OpenAI())  # log every OpenAI call automatically

@traceable(run_type="tool")  # trace this as a tool span
def get_context(question: str) -> str:
    # In a real app, this would query a knowledge base or vector store
    return "LangSmith traces are stored for 14 days on the Developer plan."

@traceable  # capture the full pipeline as a single trace
def assistant(question: str) -> str:
    context = get_context(question)
    response = client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[
            {
                "role": "system",
                "content": f"Answer using the context below.\n\nContext: {context}",
            },
            {"role": "user", "content": question},
        ],
    )
    return response.choices[0].message.content

if __name__ == "__main__":
    print(assistant("How long are LangSmith traces stored?"))

TypeScript, Java, Kotlin 버전도 공식 문서에서 확인할 수 있어요. 각 언어에서 동일한 wrap_openai/traceable 패턴을 사용해요. 예시 트레이스 보기

3. 앱 실행

python app.py

4. 트레이스 확인

LangSmith UI에서 Tracing으로 가서 default 프로젝트를 선택해요. assistant 행을 클릭해 트레이스를 열어요. Messages 탭에는 모델로 보낸 대화가 보이고, Details 탭을 선택하면 assistant 함수 안에 get_context 도구 호출과 OpenAI 호출이 중첩된 전체 실행 트리를 볼 수 있어요.

바깥 span은 assistant 함수의 입력과 출력을, 중첩된 get_context span은 도구 호출을, ChatOpenAI span은 모델로 보낸 정확한 프롬프트와 돌아온 응답을 기록해요.

팁: LangSmith CLI로 터미널에서도 트레이스를 확인할 수 있어요.

다음 단계

트레이싱 통합: LangChain, LangGraph, Anthropic 등의 프로바이더.
LLM 애플리케이션 트레이싱: 프로토타이핑부터 프로덕션까지 전체 라이프사이클 튜토리얼.
트레이스 필터링: 대규모 트레이싱 프로젝트를 검색·탐색.
특정 프로젝트로 기록: default 대신 이름 붙은 프로젝트로 트레이스 전송.

LangSmith 트레이싱 퀵스타트