LangSmith 관찰 가능성

LangSmith 관찰 가능성 (Observability)

에이전트가 입력을 받아 출력을 내기까지 거치는 여러 단계를 쭉 이어서 보면, 각각의 실행 단계가 하나의 실행 기록(run)으로 남아요. 이런 실행 흐름을 합쳐 부르는 이름이 트레이스(trace)예요. LangSmith를 쓰면 이 실행 단계를 시각적으로 확인할 수 있어요. 애플리케이션에 트레이싱을 활성화하면 아래 같은 일들이 가능해져요.

출처: 문서

본문

사전 준비 (Prerequisites)

시작 전에 준비할 게 두 가지 있어요.

트레이싱 활성화 (Enable tracing)

애플리케이션에서 트레이싱을 켜려면 다음 환경 변수를 설정해요.

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

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

더 자세한 내용은 LangGraph로 트레이스하기를 확인해요.

선택적으로 트레이스하기 (Trace selectively)

특정 호출이나 애플리케이션 일부만 트레이스하고 싶다면 LangSmith의 tracing_context 컨텍스트 매니저를 쓸 수 있어요.

import langsmith as ls

# This WILL be traced
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "Send a test email to [email protected]"}]})

# This will NOT be traced (if LANGSMITH_TRACING is not set)
agent.invoke({"messages": [{"role": "user", "content": "Send another email"}]})

프로젝트에 기록하기 (Log to a project)

정적으로 (Statically)

LANGSMITH_PROJECT 환경 변수를 설정하면 애플리케이션 전체에 커스텀 프로젝트 이름을 지정할 수 있어요.

export LANGSMITH_PROJECT=my-agent-project

동적으로 (Dynamically)

특정 작업에 대해 프로그래밍 방식으로 프로젝트 이름을 설정할 수도 있어요.

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"}]
    })

트레이스에 메타데이터 추가하기 (Add metadata to traces)

트레이스에 커스텀 메타데이터와 태그를 붙여서 주석을 달 수 있어요.

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 문서에서 더 자세히 볼 수 있어요.

익명화 도구로 민감 데이터 로깅 막기 (Use anonymizers)

민감 데이터가 LangSmith에 기록되지 않도록 가려주고 싶을 때가 있을 거예요. 익명화 도구(anonymizers)를 만들어 설정으로 그래프에 적용할 수 있어요. 아래 예시는 사회보장번호 형식(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([
    # 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]})
)

더 알아보기 (Learn more)

  • Trace with LangGraph: LangGraph 애플리케이션에서 트레이싱을 활성화하는 방법을 다뤄요.
  • LangSmith documentation: 트레이스를 활용한 디버깅·평가·모니터링 방법을 설명해요.
  • Anonymizers: 민감 데이터 마스킹 규칙을 만드는 방법을 다뤄요.