LangSmith 트레이싱 셀프 셋업 (수정중)

1. 트레이싱이 뭔가: 왜 켜나

LLM 호출은 기본적으로 블랙박스다. .invoke(prompt) 를 부르면 답만 돌아오고, 그 안에서 무슨 프롬프트가 실제로 나갔는지·토큰을 얼마나 썼는지·몇 초 걸렸는지는 코드만 봐선 안 보인다.

트레이싱은 그 호출 하나하나를 기록으로 남겨 웹에서 들여다보게 해주는 것이다. LangSmith 프로젝트를 열면 호출마다:

• 실제로 나간 입력(시스템 프롬프트 + 메시지 전체)과 돌아온 출력
• 토큰 사용량(입력/출력, 캐시 읽기·쓰기 분리. L14 의 캐싱이 실제로 적중했는지 여기서 확인한다)
• 지연(latency)과, tool-loop 이면 단계별 트리

가 보인다. 프롬프트를 튜닝하거나, 왜 답이 이상한지 디버깅하거나, 비용이 어디서 새는지 볼 때 추측 대신 실제 호출을 보는 도구다. (우리 팀 디버깅 원칙 "추측 말고 실제 증거 먼저" 와 같은 결. L24.)

---

2. LangSmith 의 3층 계층: Org → Workspace → Project

셋업에서 헷갈리는 건 대부분 이 3층을 뭉뚱그리기 때문이다. 각 층이 무엇을 담는지부터 나눈다.

Organization  (조직, 결제·멤버가 붙는 최상위 계정 단위)
└── Workspace  (워크스페이스, API 키가 붙는 단위. 무료 플랜은 딱 1개)
    ├── Project: jjom_agent   (프로젝트 = 트레이스를 묶는 "라벨/버킷")
    ├── Project: popax
    └── Project: dongtan

• Organization: 계정 최상위. 결제 플랜(무료 Developer / 유료 Plus)과 멤버가 여기 붙는다.
• Workspace: 트레이스가 실제로 쌓이는 공간. API 키가 발급되는 단위가 바로 여기다. 무료 Developer 플랜은 워크스페이스가 1개로 제한된다.
• Project: 워크스페이스 안에서 트레이스를 이름으로 묶는 버킷. jjom_agent, popax 처럼 프로젝트 slug 별로 나뉜다. 자동 생성된다. 첫 트레이스가 도착하면 그 이름의 Project 가 목록에 생긴다.

핵심은 다음 섹션의 한 문장이다: 키는 워크스페이스에, 프로젝트 구분은 라벨에.

---

3. 가장 흔한 오해: "프로젝트마다 키를 새로 받아야 하나?"

아니다. 키(PAT)와 Project 는 역할이 완전히 다르다.

	정체	결정하는 것
API 키 (PAT)	인증 토큰 (lsv2_pt_...)	트레이스가 어느 워크스페이스로 갈지
LANGCHAIN_PROJECT	그냥 문자열 라벨	워크스페이스 안에서 어떤 이름으로 묶일지

무료 플랜은 워크스페이스가 1개뿐이므로:

• 키는 PAT 1개면 끝. 내 프로젝트(jjom_agent, popax, …) 트레이스가 전부 이 워크스페이스 하나로 모인다.
• 프로젝트 구분은 .env 의 LANGCHAIN_PROJECT 값을 프로젝트마다 다르게 두는 것으로 한다. 키는 그대로, 라벨만 바꾼다.

⚠️ Setup 패널의 UI 착시: LangSmith 에서 새 Project 를 만들려고 들어가면 Setup 안내 패널에 "Generate API Key" 버튼이 있다. 이걸 보고 "프로젝트용 키가 따로 있구나" 하고 프로젝트마다 새 키를 받는 사람이 많은데, 그 버튼이 주는 키도 워크스페이스 전체용이다(프로젝트 전용 키라는 건 없다). Project 는 코드에서 LANGCHAIN_PROJECT 라벨로 만들어지는 것이지, 키로 만들어지는 게 아니다.

즉 "프로젝트 하나 = 키 하나" 라는 직관은 틀렸다. 워크스페이스 하나 = 키 하나, 프로젝트는 라벨로 무한히 나눈다.

---

4. 셀프 셋업: 계정 → 키 → .env 4줄

절차 자체는 짧다(전체 원문은 팀 wiki onboarding/langsmith-setup.md).

① 계정 + 키 발급 1. https://smith.langchain.com 에서 회사 이메일로 회원가입(개인 무료 Developer 플랜). 2. Settings → API Keys → Create API Key → Personal Access Token 선택. 3. 발급된 lsv2_pt_... 를 즉시 복사한다(한 번만 보여준다).

② 내 프로젝트 src/.env 에 4줄 추가

LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=lsv2_pt_...        # 1단계에서 발급한 본인 키
LANGCHAIN_PROJECT=<project_slug>     # 예: jjom_agent (프로젝트 slug 그대로)

• .env 는 .gitignore 에 있어 커밋되지 않는다. 키를 소스코드에 절대 넣지 말 것.
• LANGCHAIN_TRACING_V2=true 가 트레이싱 on/off 스위치다. 끄고 싶으면 false 로 두거나 4줄을 지운다.
• 이미 실행 중인 dev 서버가 있으면 재시작해야 새 .env 를 읽는다(서버는 켜질 때 환경변수를 한 번 읽는다).

---

5. 왜 코드는 한 줄도 안 고치나: get_*_llm() 이 이미 LangChain

.env 4줄만 넣으면 되는 이유는, 우리가 LLM 을 직접 부르지 않고 항상 standarda-core 의 헬퍼로 부르기 때문이다.

# standarda_core/llm.py:16, get_anthropic_llm()
from langchain_anthropic import ChatAnthropic
...
def get_anthropic_llm(...):
    """LLM 인스턴스 초기화 및 반환 (Claude)
    LangChain 기반이므로 LangSmith tracing이 자동 적용됨.
    """

get_anthropic_llm() / get_openai_llm() / get_google_llm() 은 전부 LangChain 객체(ChatAnthropic 등)를 돌려준다. LangChain 은 LANGCHAIN_TRACING_V2=true 와 LANGCHAIN_API_KEY 가 환경에 있으면 모든 .invoke() 호출을 자동으로 LangSmith 에 보낸다. 우리 코드에 트레이싱 코드를 넣을 필요가 없다.

이게 CLAUDE.md 가 "절대 ChatAnthropic() 를 직접 만들지 말고 get_*_llm() 을 쓰라" 고 못박은 이유 중 하나다. 직접 OpenAI() 를 만들면 LangChain 밖이라 트레이싱이 통째로 누락된다. (같은 규칙: 캐싱·비용 계측도 standarda_core 경유라야 걸린다. L14.)

③ 확인: Claude 를 부르는 코드를 한 번 실행 → LangSmith 웹 좌측 nav Tracing → 프로젝트 목록에 <project_slug> 가 자동으로 뜨는지 본다. 클릭하면 방금 호출의 입력/출력/토큰/지연이 보인다.

---

6. 무료 Developer 플랜의 제약: 언제 벽에 부딪히나

개인 무료 계정은 공짜인 대신 한도가 있다. 넘으면 어떻게 되는지 미리 알아둔다.

항목	무료 Developer 플랜
seat	1개 (개인)
워크스페이스	1개 (여러 개는 유료)
트레이스	월 5,000건 무료, 초과분 pay-as-you-go($2.50/1k)
보관 기간	14일 (무료 base trace)

• 트레이스가 갑자기 안 쌓이면 월 5k 한도 초과를 먼저 의심한다(LangSmith 웹 Usage 확인). 초과분 과금을 켜야 하면 경영지원팀에 결제 설정을 요청한다. 개인 카드로 걸지 않는다.
• 옛 트레이스가 사라진 건 정상이다. 무료는 14일만 보관한다. 오래 남겨야 할 케이스는 스크린샷·별도 저장.

그 외 자주 겪는 문제(목록에 아무것도 안 뜸 / 401 Unauthorized 등)와 해결은 팀 wiki onboarding/langsmith-setup.md 의 "자주 겪는 문제" 표에 정리돼 있다.

---

오늘 정리 + 다음

• 정리: LangSmith 는 Org→Workspace→Project 3층이다. 키(PAT)는 워크스페이스 단위라 무료 플랜에선 1개면 충분하고, 프로젝트 구분은 .env 의 LANGCHAIN_PROJECT 라벨로 한다. 셋업은 계정 만들고 키 받아 .env 에 4줄 넣는 게 전부. 우리 코드는 get_*_llm()(LangChain) 을 쓰므로 트레이싱이 자동으로 붙는다.
• 흔한 함정: Setup 패널의 "Generate API Key" 를 보고 프로젝트마다 새 키를 받는 것. 그 키도 워크스페이스 전체용이다. 프로젝트는 키가 아니라 라벨(LANGCHAIN_PROJECT)로 나뉜다. 또 하나: .env 저장 전에 켜둔 dev 서버는 옛 환경변수를 물고 있어 트레이스가 안 뜬다 → 재시작.
• 이어지는 주제: 트레이스를 실제로 열어 프롬프트 튜닝·비용 분석에 쓰는 법(토큰·캐시 적중 읽기, L14 의 캐싱이 트레이스에서 어떻게 보이는지).
• 자습 권장: 각자 자기 프로젝트에 오늘 절차대로 트레이싱을 붙여보고, LLM 을 한 번 호출해 Tracing 목록에 뜨는지 확인해 온다. 절차 원문·문제해결은 팀 wiki onboarding/langsmith-setup.md, 모델 키 정책은 infrastructure/llm-api-key-management.md.