LangSmith 관측성

LangSmith 관측성 (Observability)

에이전트가 입력을 받아 출력을 내는 사이 어떤 과정을 거쳤는지, 그 실행 단계 하나하나가 바로 trace예요. LangGraph 앱을 만들고 나면 이 trace를 LangSmith에서 시각화해서 디버깅, 평가, 모니터링까지 할 수 있는데요, 이번 글에서 tracing을 켜고 프로젝트·메타데이터를 다루는 방법을 살펴볼게요.

출처: 공식문서

사전 준비 (Prerequisites)

Tracing 활성화

아래 환경변수를 설정하면 앱 전체의 tracing이 켜져요. 기본적으로 default라는 이름의 프로젝트에 trace가 기록되구요.

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

선택적으로 trace하기

원하는 부분만 trace하고 싶다면, LangSmith의 tracing_context 컨텍스트 매니저를 쓰면 돼요. LANGSMITH_TRACING이 켜져 있지 않은 상태에서 이 컨텍스트 안의 호출만 trace되고 밖은 안 되는 식이죠.

import langsmith as ls

# 이 호출은 trace됩니다
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "Send a test email to [email protected]"}]})

# (LANGSMITH_TRACING이 설정돼 있지 않으면) 이 호출은 trace되지 않습니다
agent.invoke({"messages": [{"role": "user", "content": "Send another email"}]})

프로젝트로 기록하기

  • 정적으로: 앱 전체에 커스텀 프로젝트 이름을 쓰려면 LANGSMITH_PROJECT 환경변수를 지정해요. 
    export LANGSMITH_PROJECT=my-agent-project
  • 동적으로: 특정 작업만 프로젝트 이름을 바꿔 기록할 수도 있어요. 
    import langsmith as ls

with ls.tracing_context(project_name="email-agent-test", enabled=True):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "Send a welcome email"}]
    })

Trace에 메타데이터·태그 추가

invoke 호출에 config를 넘기면 태그와 메타데이터를 함께 붙일 수 있어요.

response = agent.invoke(
    {"messages": [{"role": "user", "content": "Send a welcome email"}]},
    config={
        "tags": ["production", "email-assistant", "v1.0"],
        "metadata": {
            "user_id": "user_123",
            "session_id": "session_456",
            "environment": "production"
        }
    }
)

tracing_context에도 같은 방식으로 태그·메타데이터를 줄 수 있어요.

with ls.tracing_context(
    project_name="email-agent-test",
    enabled=True,
    tags=["production", "email-assistant", "v1.0"],
    metadata={"user_id": "user_123", "session_id": "session_456", "environment": "production"}):
    response = agent.invoke(
        {"messages": [{"role": "user", "content": "Send a welcome email"}]}
    )

이 메타데이터·태그는 LangSmith의 해당 trace에 함께 기록돼요.

민감 데이터 마스킹 (Anonymizer)

주민등록번호 같은 민감 정보가 LangSmith에 로그로 남지 않도록 가리고 싶을 때가 있어요. anonymizer를 만들어 그래프의 callbacks로 연결하면 됩니다. 아래 예시는 XXX-XX-XXXX 형태의 SSN을 trace에서 <ssn>으로 가립니다.

from langchain_core.tracers.langchain import LangChainTracer
from langgraph.graph import StateGraph, MessagesState
from langsmith import Client
from langsmith.anonymizer import create_anonymizer

anonymizer = create_anonymizer([
    # Matches SSNs
    { "pattern": r"\b\d{3}-?\d{2}-?\d{4}\b", "replace": "<ssn>" }
])

tracer_client = Client(anonymizer=anonymizer)
tracer = LangChainTracer(client=tracer_client)
# Define the graph
graph = (
    StateGraph(MessagesState)
    ...
    .compile()
    .with_config({'callbacks': [tracer]})
)

Tracing으로 디버깅·평가·모니터링을 어떻게 하는지 더 알고 싶다면 LangSmith 문서를 봐 주세요.

더 알아보기 (Learn more)