관찰 데이터 구조: run·trace·thread·trajectory
관찰 데이터 구조: run·trace·thread·trajectory
LangSmith가 관찰 데이터를 어떤 단위로 구조화하고 시각화하는지 이해하면, 트레이스를 보내는 방법까지 자연스럽게 따라와요. 에이전트가 수행하는 모든 작업 단위는 run으로 기록되고, 한 번의 작업에 속한 run들은 trace로 묶이며, 여러 턴으로 이뤄진 대화에서는 trace들을 thread로 연결해요. 여기에 trajectory라는 평평한 시각화까지 더해지면 데이터가 꽤 입체적으로 보이기 시작해요.
데이터는 어떻게 구조화되고 시각화될까
LangSmith에서 에이전트가 수행하는 작업 단위(모델 호출, 도구 실행, 정보 검색 등)는 전부 run으로 기록돼요. 한 번의 작업에 속한 run들을 모은 것이 trace이고, 다중 턴 세션에서 trace들을 연결한 것이 thread예요. 반면 trajectory는 세션 전체를 시작부터 끝까지 순서대로 나열한 메시지 목록으로 펼쳐 보여주는 방식이에요. thread가 세션의 trace를 묶고 중첩 구조를 유지한다면, trajectory는 중첩을 걷어내고 에이전트가 지나온 길을 순서대로 읽을 수 있게 해줘요.
run
run은 에이전트가 수행한 하나의 작업 단위예요. LLM 호출, 프롬프트 구성, 문서 검색 같은 것이 각각의 run이 돼요. OpenTelemetry에 익숙하다면 run을 span이라고 생각하면 돼요.
trace
trace는 한 번의 작업에 속한 run들의 모음이에요. 예를 들어 사용자 요청이 에이전트를 트리거해서 모델을 호출하고, 도구를 실행하고, 다시 모델을 호출한다면 그 모든 run은 같은 trace에 속해요. run들은 고유한 trace ID로 trace에 묶이죠. 참고로 trace 하나는 최대 25,000개의 run으로 제한돼요. 이 한도에 도달하면 LangSmith는 그 trace에 추가로 보내는 run을 거부해요.
thread
thread는 하나의 다중 턴 세션을 나타내는 trace들의 연속이에요. 한 턴은 세션에서 한 번의 교환, 즉 사용자 메시지와 그에 대해 에이전트가 수행하는 모든 작업을 의미하고, 각 턴은 자신만의 trace로 기록돼요. trace들을 thread로 묶으려면 고유한 값을 가진 thread_id 메타데이터 키를 넘겨주면 돼요. 자세한 구성 방법은 threads 문서를 참고해요.
trajectory
trajectory는 에이전트가 시작부터 끝까지 지나온 길을 보여주는 평평하고 순서가 있는 메시지 목록이에요. thread 내 trace들의 투영(projection)으로 볼 수 있는데, 세션 중에 교환된 human·AI·tool 메시지를 각각 처음 등장한 순서대로 한 번씩 담고 run의 중첩 구조는 걷어낸 형태예요. UI에서 trajectory를 렌더링하는 Messages view는 현재 beta 단계예요.
trace·thread·trajectory 비교
| Trace | Thread | Trajectory | |
|---|---|---|---|
| 형태 | run의 트리 | trace의 연속 | 평평한 순서 목록 |
| 포함 내용 | 모든 run과 전체 입출력 | 연결된 모든 trace의 모든 run | 연결된 모든 trace의 모든 메시지(중복 제거) |
| 쓰기 좋은 때 | 한 작업이 왜 실패했는지·왜 느렸는지 디버깅 | 턴을 넘나드는 동작을 타이밍·중첩 유지한 채 조사 | 실행 디테일 없이 세션에서 오간 내용을 읽기 |
데이터를 직접 뒤지지 않고도 trace·run·thread를 분석하고 싶다면 Chat 기능을 쓰는 것도 좋아요. 에이전트 성능 이해, 이슈 디버깅, 대화 스레드 인사이트를 손쉽게 얻을 수 있어요.
project
project는 하나의 애플리케이션 또는 서비스와 관련된 모든 trace를 담는 컨테이너예요. trace를 project에 기록하는 방법은 Log traces to a project에서 확인해요.
trace 보강하기
- Feedback — 특정 기준에 따라 개별 run을 점수화해요. 각 피드백 항목은 태그와 점수로 이뤄지고 고유한 run ID로 run에 묶여요. 연속형이거나 범주형(discrete)일 수 있고, 태그는 조직 내 run들 사이에서 재사용할 수 있어요. 저장 방식은 Feedback data format guide를 참고해요.
- Tags — run에 붙여 분류·필터·그룹핑에 쓰는 문자열이에요. 태그 달기를 참고해요.
- Metadata — run에 붙이는 키-값 쌍의 모음이에요. 애플리케이션 버전, 환경 같은 문맥 정보를 담고 tags처럼 필터·그룹핑에 쓸 수 있어요. 메타데이터 추가를 참고해요.
trace 보내기
trace 데이터를 LangSmith로 보내는 방법은 두 가지예요.
통합(Integrations) — LangChain, LangGraph, OpenAI, Anthropic, CrewAI 같은 지원 프레임워크를 쓰면 통합이 입력·출력·메타데이터를 자동으로 캡처해요. 일반적인 관찰 도구의 자동 계측(auto-instrumentation)에 해당하는 방식이라 코드 수정 없이 동작해요. 전체 통합 목록을 확인해 보세요.
수동 계측(Manual instrumentation) — 지원되는 통합이 없거나 무엇을 추적할지 세밀하게 제어하고 싶을 때 써요. LangSmith는 세 가지 메커니즘을 제공해요.
@traceable/traceable: 어떤 함수든 추적해 주는 데코레이터trace컨텍스트 매니저 (Python): 특정 코드 블록을 감싸 추적RunTreeAPI: 저수준에서 명시적으로 trace를 구성
수동 계측 추가 방법은 annotate-code 문서를 참고해요.
데이터 보존
LangSmith(SaaS)는 trace 데이터를 수집 시점부터 180일간 보존해요. 이후엔 trace가 영구 삭제되고, 사용량 통계를 위한 제한된 메타데이터만 남아요. 보존 등급과 가격 상세는 Usage and billing: Data retention을 확인해요. 보존 기간을 넘어 데이터를 유지하고 싶다면 dataset에 추가하면 되는데, 데이터셋은 원본 trace가 삭제된 뒤에도 무기한 유지돼요. 만료 전에 trace를 지우고 싶다면 Manage a trace를 참고해요.