LangSmith 관측성

트레이스(trace)는 애플리케이션이 입력에서 출력으로 가는 동안 거치는 일련의 단계예요. 각 개별 단계는 run으로 표현되죠. LangSmith로 이러한 실행 단계를 시각화할 수 있어요. 쓰려면 애플리케이션에 대한 트레이싱을 활성화해야 해요. 그러면 다음을 할 수 있어요:

사전 요구사항

시작 전에 다음이 있어야 해요:

LangSmith 계정: smith.langchain.com에서 (무료로) 가입하거나 로그인해요.
LangSmith API 키: API 키 만들기 가이드를 따라요.

출처: LangSmith 관측성 - 공식 문서

트레이싱 활성화

애플리케이션의 트레이싱을 활성화하려면 다음 환경 변수를 설정해요:

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

기본적으로 트레이스는 default라는 이름의 프로젝트에 기록돼요. 커스텀 프로젝트 이름을 설정하려면 프로젝트에 기록을 보세요.

자세한 내용은 LangGraph로 트레이스하기를 보세요.

선택적으로 트레이스하기

LangSmith의 tracing_context 컨텍스트 매니저로 특정 invocation이나 애플리케이션의 일부만 트레이스하도록 선택할 수 있어요:

import langsmith as ls

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

# 이 호출은 트레이스되지 않음 (LANGSMITH_TRACING이 설정되지 않았다면)
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"}]
    })

트레이스에 메타데이터 추가

커스텀 메타데이터와 태그로 트레이스에 주석을 달 수 있어요:

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의 트레이스에 첨부돼요.

트레이스로 에이전트를 디버그·평가·모니터링하는 방법에 대한 자세한 내용은 [LangSmith 문서](/langsmith/observability)를 보세요.

익명화 도구로 트레이스의 민감 데이터 기록 방지

민감 데이터를 마스킹해서 LangSmith에 기록되지 않게 하고 싶을 수 있어요. 익명화 도구를 만들고 설정으로 그래프에 적용할 수 있어요. 이 예제는 사회보장번호 형식(XXX-XX-XXXX)과 일치하는 모든 것을 LangSmith로 보내는 트레이스에서 지웁니다.

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([
    # SSN과 일치
    { "pattern": r"\b\d{3}-?\d{2}-?\d{4}\b", "replace": "<ssn>" }
])

tracer_client = Client(anonymizer=anonymizer)
tracer = LangChainTracer(client=tracer_client)
# 그래프 정의
graph = (
    StateGraph(MessagesState)
    ...
    .compile()
    .with_config({'callbacks': [tracer]})
)

LangSmith 관측성