Trace Claude Code - Docs by LangChain

요약

이 문서는 Claude Code CLI에서 생성된 대화 기록을 LangSmith로 자동 전송하여 AI 상호작용을 추적(tracing)하는 방법을 안내합니다.

️이를 위해 전역 "Stop" hook을 stop_hook.sh 스크립트와 함께 설정하여 Claude Code의 응답 후 대화 내용을 LangSmith 실행(run)으로 변환하고 전송합니다.

사용자는 LangSmith API 키를 준비하고, 각 Claude Code 프로젝트 설정 파일에 환경 변수를 추가하여 tracing을 활성화하면 LangSmith에서 사용자 메시지, 도구 호출, 어시스턴트 응답을 포함한 trace를 볼 수 있습니다.

상세 내용

이 문서는 Claude Code CLI에서 이루어지는 대화 내역을 LangSmith로 자동 전송하여 추적(tracing)하는 방법에 대한 가이드이다. 이 설정을 통해 사용자 메시지, 도구 호출, 어시스턴트 응답을 포함한 대화 트레이스를 LangSmith에서 확인할 수 있다. 다만, Claude Code의 대화 기록에는 시스템 프롬프트가 포함되지 않으므로 LangSmith Trace에도 시스템 프롬프트는 나타나지 않는다.

핵심 방법론 (Core Methodology)

이 Tracing 메커니즘은 Claude Code의 전역 "Stop" hook을 활용한다. "Stop" hook은 Claude Code가 응답을 생성할 때마다 실행되도록 구성된다. 이 hook은 stop_hook.sh라는 셸 스크립트를 실행하며, 이 스크립트가 Tracing의 핵심 역할을 수행한다.

대화 기록 읽기: stop_hook.sh 스크립트는 Claude Code가 생성한 대화 기록(conversation transcripts)을 읽는다. 이 기록은 일반적으로 .json 또는 텍스트 형식으로 저장된다.

LangSmith Run으로 변환: 스크립트는 대화 기록 내의 각 메시지(사용자 메시지, 도구 호출, 어시스턴트 응답)를 LangSmith의 "Run"(또는 "span") 형식으로 변환한다. LangSmith는 애플리케이션의 실행 흐름을 Run이라는 단위로 기록하며, 이는 LangChain의 Span 개념과 유사하다. 이 변환 과정에서 jq와 같은 JSON 처리 도구가 활용될 것으로 예상된다.

LangSmith로 전송: 변환된 Run 데이터는 HTTP 요청(예: curl 명령어 사용)을 통해 지정된 LangSmith project로 전송된다. 이때 LangSmith API key가 인증에 사용된다.

Tracing 활성화 및 그룹화: Tracing은 프로젝트별로 선택적으로(opt-in) 활성화되며, 이는 환경 변수를 통해 제어된다. LangSmith에서는 동일한 Claude Code 세션에서 발생한 모든 대화 턴(turn)이 thread_id를 공유하여 하나의 스레드(Thread)로 그룹화되어 표시되므로, 전체 대화 흐름을 쉽게 파악할 수 있다.

전제 조건 (Prerequisites)

Tracing 설정을 위해서는 다음 사항이 충족되어야 한다.

* Claude Code CLI가 설치되어 있어야 한다.
* 유효한 LangSmith API key가 필요하다.
* 명령줄 JSON 프로세서인 jq가 설치되어 있어야 한다.
* 이 가이드는 현재 macOS 환경만을 지원한다.

설정 단계 (Detailed Setup Steps)

Hook 스크립트 생성: ~/.claude/hooks/stop_hook.sh 경로에 stop_hook.sh 스크립트 파일을 생성하고, 이 스크립트가 실행 가능하도록 chmod +x ~/.claude/hooks/stop_hook.sh 명령어를 사용하여 권한을 부여한다. 이 스크립트는 대화 기록을 처리하고 LangSmith로 데이터를 전송하는 로직을 포함한다.

전역 Hook 구성: ~/.claude/settings.json 파일에 전역 "Stop" hook을 구성한다. 이는 Claude Code가 응답을 생성할 때마다 stop_hook.sh 스크립트가 실행되도록 설정하는 것으로, 모든 Claude Code CLI project에 대해 Tracing을 쉽게 활성화할 수 있는 기반을 마련한다. 설정 예시는 다음과 같다:

json{
      "hooks": {
        "Stop": [
          {
            "hooks": [
              {
                "type": "command",
                "command": "bash ~/.claude/hooks/stop_hook.sh"
              }
            ]
          }
        ]
      }
    }

Tracing 활성화: Tracing을 원하는 각 Claude Code project 디렉토리 내에 .claude/settings.local.json 파일을 생성하거나 편집하여 다음 환경 변수들을 포함시킨다. 이 설정은 project별로 Tracing을 활성화하거나 비활성화하며, LangSmith API key와 project 이름을 지정한다. CC_LANGSMITH_DEBUG 변수를 true로 설정하여 상세 디버그 로깅을 활성화할 수 있다.

json{
      "env": {
        "TRACE_TO_LANGSMITH": "true",
        "CC_LANGSMITH_API_KEY": "lsv2_pt_...",
        "CC_LANGSMITH_PROJECT": "project-name",
        "CC_LANGSMITH_DEBUG": "true"
      }
    }

위 설정은 모든 Claude Code 세션에 대해 Tracing을 활성화하기 위해 전역 settings.json 파일에 추가할 수도 있다.

설정 확인 및 문제 해결 (Verification and Troubleshooting)

* 설정 후 Claude Code 세션을 시작하고, Claude Code가 응답한 후 LangSmith에서 Trace가 나타나는지 확인한다.
* Trace가 나타나지 않을 경우: ~/.claude/state/hook.log 파일을 확인하여 hook이 실행되는지, 환경 변수가 올바른지, API key가 유효한지, LangSmith project가 존재하는지, 그리고 디버그 모드를 활성화하여 API 호출 상태를 확인한다.
* 권한 오류: stop_hook.sh 스크립트가 실행 가능한지 (chmod +x) 확인한다.
* 필수 명령어 누락: jq, curl, uuidgen과 같은 필수 명령어가 설치되어 있는지 확인한다.
* 로그 파일 크기 관리: hook 활동 로그는 ~/.claude/state/hook.log에 기록되며, 디버그 모드 활성화 시 파일 크기가 커질 수 있으므로 주기적으로 관리하거나 지울 수 있다.

#LangSmith #Claude Code #Tracing #CLI #Observability