LLM Wiki

Trace Every Claude Code Session in LangSmith in Minutes

Properties2
descriptionLangSmith 공식 플러그인으로 Claude Code 세션을 몇 분 만에 트레이싱하는 셋업 가이드
tagsai-coding, dev-tools, anthropic, debugging, youtube

10 min read

출처 https://youtu.be/jLOM_ahG78c · 채널 LangChain · 길이 00:02:44 포맷 LangChain 프로덕트팀 Amy가 얼굴을 비추며 진행하는 짧은 튜토리얼. 터미널·VS Code·LangSmith 웹 화면을 화면 공유로 보여주며 셋업 전 과정을 실연한다. 원본 자막: raw/transcripts/2026-07-11-trace-claude-code-langsmith.en.srt

한눈에 보는 요약

  • Claude Code로 에이전트를 만들다 보면 “왜 이런 툴 콜이 일어났는지, 서브 에이전트가 뭘 리턴했는지” 알 수 없어 막막할 때가 있는데, LangSmith 공식 플러그인을 설치하면 몇 분 만에 모든 Claude Code 세션이 LangSmith에서 트레이싱된다.
  • 준비물은 Claude Code CLI, Node.js, LangSmith API 키 세 가지뿐이다.
  • 설치는 명령 3개면 끝난다: 마켓플레이스 추가 → 플러그인 설치 → 플러그인 리로드.
  • 트레이스 전송 여부·API 키·프로젝트명은 프로젝트 루트의 .claude/settings.local.json 한 블록으로 설정한다. 모든 프로젝트에 기본 적용하고 싶으면 같은 블록을 전역 ~/.claude/settings.json에 넣으면 된다.
  • LangSmith에서는 메시지 하나하나가 트레이스로 남아 유저 메시지·툴 콜·서브 에이전트 실행·토큰 사용량·최종 응답까지 전부 보이고, Threads 탭으로 가면 같은 세션의 여러 턴이 하나의 대화로 묶여서 보인다.
  • 발표자는 이어서 Codex·Cursor용 동일 셋업 영상도 예고한다.

장면별 상세 설명

[00:01] 1. 인트로 — 왜 트레이싱이 필요한가

장면 1 — 발표자 Amy 소개

LangChain 프로덕트팀의 Amy가 이 영상에서 Claude Code 애플리케이션을 LangSmith로 트레이싱하는 법을 보여주겠다고 소개한다. Claude Code로 에이전트를 만들다 보면 에이전트가 예상 밖의 행동을 했는데 왜 그랬는지 알 방법이 없었던 경험이 있을 것이다 — 어떤 툴 콜이 그걸 유발했는지, 서브 에이전트가 실제로 뭘 리턴했는지 알 수가 없다. 이 영상에서는 몇 분의 셋업만으로 모든 Claude Code 세션을 LangSmith로 바로 트레이싱해서, 모든 메시지·툴 콜·서브 에이전트 실행까지 전체 트레이스를 받는 법을 다룬다.

[00:29] 2. 준비물 3가지

장면 2 — 준비물을 설명하는 Amy

시작 전에 필요한 건 세 가지다: Claude Code CLI, Node.js, 그리고 LangSmith API 키. API 키가 없다면 LangSmith 설정에서 발급받으면 된다. 이 세 가지만 갖추면 바로 시작할 수 있다.

[00:45] 3. 설치 1단계 — 마켓플레이스 플러그인 추가

장면 3 — Claude Code 터미널에서 marketplace add 명령

Claude Code를 열고 명령 3개를 실행하면서 마켓플레이스 플러그인을 추가한다. 화면에 실제로 입력되는 명령은 다음과 같다.

/plugin marketplace add langchain-ai/langsmith-claude-code-plugins

실행하면 Successfully added marketplace: langchain-ai가 뜬다.

[00:52] 4. 설치 2단계 — 트레이싱 플러그인 설치 및 리로드

장면 4 — plugin install 명령 입력 화면

이어서 트레이싱 플러그인 자체를 설치한다.

/plugin install langsmith-tracing@langsmith-claude-code-plugins

설치 후 플러그인을 다시 불러오도록 리로드하면 설치는 끝이다. 나중에 업그레이드할 때는 /plugin marketplace update langsmith-claude-code 다음에 /plugin reload plugins만 다시 실행하면 된다.

[01:12–01:25] 5. 프로젝트 설정 파일 — .claude/settings.local.json

장면 5 — VS Code에 열린 settings.local.json과 트레이싱 설정 팁

이제 플러그인에게 트레이스를 어디로 보낼지 알려줘야 한다. 가장 깔끔한 방법은 프로젝트 설정 파일이다 — 프로젝트 디렉터리에 .claude/settings.local.json을 만들고 다음 블록을 넣는다.

{
  "env": {
    "TRACE_TO_LANGSMITH": "true",
    "CC_LANGSMITH_API_KEY": "<your LangSmith API key>",
    "CC_LANGSMITH_PROJECT": "my-project"
  }
}
  • TRACE_TO_LANGSMITH: 이 프로젝트의 트레이싱을 켜고 끄는 스위치. false로 바꾸면 언제든 끌 수 있다.
  • CC_LANGSMITH_API_KEY: LangSmith API 키.
  • CC_LANGSMITH_PROJECT: 트레이스가 LangSmith에서 보여질 프로젝트명.

화면 하단 팁: 모든 프로젝트에 기본으로 트레이싱을 켜고 싶다면, 같은 블록을 프로젝트별 설정이 아니라 전역 ~/.claude/settings.json에 넣으면 된다.

[01:43] 6. 실제 사용 — Claude Code를 평소처럼 쓴다

장면 6 — "바르셀로나 날씨" 질문에 웹 검색 툴을 호출하는 Claude Code

설정이 끝나면 이제 Claude Code를 평소처럼 쓰면 된다. 화면에서는 “Tell me what the weather is in Barcelona”라고 물어보자 Claude Code가 Web Search("weather in Barcelona today") 툴을 호출해 바르셀로나의 날씨(맑고 더움, 최고 92°F, 폭염주의보)를 출처(AccuWeather, The Weather Channel, Weather Underground)와 함께 답한다. 응답이 끝나면 LangSmith로 넘어가서 확인한다.

[01:52–02:00] 7. LangSmith에서 트레이스 뜯어보기 — 툴 콜 단위까지

장면 7 — 트레이스 상세 화면. Bash 툴 콜과 그 출력이 펼쳐져 있다

LangSmith에서 보내는 메시지 하나하나가 자기만의 트레이스로 남고, 그 안에 전체 그림이 들어있다 — 유저 메시지, Claude가 호출한 모든 툴 콜, 토큰 사용량, 서브 에이전트 실행, 그리고 최종 응답까지. 화면의 예시 트레이스는 “install node” 요청에 대해 Claude가 Bash 툴로 node --version, which brew nvm fnm volta, brew --version 같은 커맨드를 실행해 기존 환경(Node·패키지 매니저 유무)을 먼저 점검하는 과정을 보여준다. 오른쪽 Stats 패널에는 턴 수, 지연시간(P50/P99), 입력·출력·캐시별 토큰과 비용까지 세세하게 집계된다.

[02:07] 8. Threads 탭 — 세션 전체를 하나의 대화로

장면 8 — Threads 탭에서 Turn 1(네팔 수도)·Turn 2(터키 수도)가 한 스레드로 묶인 화면

Threads 탭으로 넘어가면, 같은 Claude Code 세션에서 나온 모든 턴이 하나의 스레드로 묶여 있다. 화면 예시에서는 “네팔의 수도는?” → “카트만두”(Turn 1), “터키의 수도는?” → “앙카라”(Turn 2)가 한 스레드 아래 나란히 표시된다. 이렇게 하면 메시지 하나만 보는 게 아니라 대화 전체의 흐름을 따라갈 수 있다.

[02:20] 9. 마무리 — 세 명령과 JSON 한 블록

장면 9 — 손가락으로 숫자를 세며 마무리하는 Amy

이게 셋업의 전부다 — 명령 3개와 JSON 블록 하나만 있으면 이제 모든 Claude Code 세션이 LangSmith에서 디버깅 가능한 트레이스가 된다. 뭔가 안 될 때는 고정된(pinned) 트러블슈팅 스텝을 확인하고, API 키가 맞는지부터 다시 확인하라고 조언한다. 전체 문서 링크는 영상 설명란에 있으며, 같은 셋업을 Codex와 Cursor용으로도 곧 다룰 예정이라고 예고하며 마친다.

핵심 개념·용어 메모

  • 설치 커맨드 2개: /plugin marketplace add langchain-ai/langsmith-claude-code-plugins → /plugin install langsmith-tracing@langsmith-claude-code-plugins → 리로드.
  • .claude/settings.local.json 환경변수 3개: TRACE_TO_LANGSMITH(on/off 스위치), CC_LANGSMITH_API_KEY, CC_LANGSMITH_PROJECT(LangSmith 프로젝트명). 전역 적용은 ~/.claude/settings.json에 동일 블록.
  • 업그레이드: /plugin marketplace update langsmith-claude-code → /plugin reload plugins.
  • LangSmith Threads 탭: 트레이스는 메시지(턴) 단위, Threads는 같은 세션의 턴들을 하나의 대화로 묶어 보여주는 상위 뷰.

원문 인용 모음

  • [00:07] “If you are building agents with Claude Code, you’ve probably had a moment where your Claude Code agent did something unexpected and you had no way to see why.”
  • [00:14] “Which tool call triggered it? What did the sub agent actually return?”
  • [01:21] “traceToLangSmith turns tracing on for this project. You can flip it to false anytime you want it to stop.”
  • [01:52] “Every message you send shows up as its own trace and inside it you get the full picture.”
  • [02:09] “Every turn from the same Claude Code session is grouped under one thread.”
  • [02:17] “Three commands and one JSON block, and now every Claude Code session is a debuggable trace in LangSmith.”

관련 노트

백링크