Tracing과 evals
이 장에서 배울 것
이 장에서는 에이전트가 실행되는 과정을 추적하고, 그 기록을 평가 데이터로 바꾸는 방법을 배운다.
trace와 span의 차이를 이해한다.
프롬프트, 도구 호출, 검색, 상태 변경, 승인, 가드레일 결과를 한 실행 기록으로 묶는다.
최종 답변뿐 아니라 중간 실행 단계도 평가한다.
성공률, 근거성, 도구 사용 정확도, 비용, 지연 시간을 지표로 설계한다.
실제 실패 로그를 평가 데이터셋으로 만들고 회귀 테스트에 사용한다.
Human approval과 guardrails에서 만든 승인 로그와 가드레일 기록은 이 장의 출발점이다. 이제 우리는 에이전트가 안전하게 멈췄는지만 보는 것이 아니라, 왜 멈췄고, 왜 통과했고, 어디서 실패했는지를 측정해야 한다.
왜 이 주제가 중요한가
에이전트의 실패는 보통 한 문장으로 드러난다.
'답변이 틀렸다.'
하지만 실제 원인은 여러 곳에 숨어 있다. 검색기가 엉뚱한 문서를 가져왔을 수 있다. 라우터가 잘못된 하위 에이전트로 넘겼을 수 있다. 도구 호출 인자가 틀렸을 수 있다. 승인 정책은 맞았지만 사용자에게 보여준 확인 문구가 불충분했을 수도 있다.
최종 답변만 저장하면 이런 원인을 알 수 없다. 로그가 없으면 개선은 추측이 된다. trace가 있으면 개선은 진단이 된다.
일반 로그는 '무슨 일이 있었다'를 남긴다. tracing은 '어떤 순서로, 어떤 입력을 받아, 어떤 구성 요소가, 어떤 결정을 했는지'를 연결해서 보여준다. eval은 그 실행이 기대한 기준을 만족했는지 점수화한다. 이 둘이 합쳐져야 에이전트를 반복적으로 개선할 수 있다.
핵심 개념 설명
Trace와 span
trace는 하나의 사용자 요청이 시작되어 최종 결과가 나올 때까지의 전체 실행 기록이다. span은 그 안에서 발생한 하나의 작업 단위다. 예를 들어 한 번의 FAQ 질문이 trace라면, 라우터 판단, 문서 검색, LLM 답변 생성, 가드레일 검사, 최종 응답은 각각 span이 된다. 여러 평가 프레임워크도 trace를 end-to-end 평가 단위로, span을 component-level 평가 단위로 다룬다.1
실제 에이전트 trace에는 다음 항목이 같은 trace ID로 묶여야 한다.
사용자 입력
planner 또는 router의 결정
LLM generation
retrieval 요청과 검색 결과
tool call과 tool result
state update
subagent handoff
guardrail 검사 결과
human approval 요청과 응답
final output
OpenAI Agents SDK 같은 에이전트 런타임도 LLM generation, function tool call, guardrail, handoff 등을 기본 추적 대상으로 삼는다.2 중요한 점은 특정 프레임워크 이름이 아니라 구조다. 어떤 도구를 쓰든 '한 실행을 여러 span의 연결 기록으로 남긴다'는 원칙은 같다.
LLM 관측성은 단순 로그 저장이 아니다
LLM 애플리케이션 관측성은 세 가지를 포함한다.
첫째, 계측이다. 코드 안에서 중요한 작업 단위를 span으로 감싸고, trace ID와 parent span ID를 붙인다. OpenTelemetry 기반 도구들은 이런 구조를 표준 관측성 시스템과 연결할 수 있게 해준다. Phoenix도 OpenTelemetry 기반 tracing, 평가, 데이터셋, 실험 추적을 제공한다.3
둘째, 시각화다. trace tree, latency chart, token cost, 실패 span 목록을 대시보드에서 볼 수 있어야 한다. 개발자가 로그 파일을 grep하는 방식만으로는 multi-agent 실행을 빠르게 진단하기 어렵다.
셋째, 운영 환경과 개발 환경의 일관성이다. 개발 중에는 자세히 기록하고 운영에서는 다른 형식으로 기록하면 회귀 분석이 어렵다. 운영에서는 민감 정보를 줄이되, trace 구조와 필드 이름은 유지하는 편이 좋다.
반드시 저장할 필드는 다음과 같다.
| 구분 | 예시 |
|---|---|
| 식별자 | trace_id, span_id, parent_span_id, session_id |
| 버전 | model, prompt_version, tool_schema_version, router_version |
| 실행 정보 | span_type, started_at, ended_at, latency_ms |
| 입력과 출력 | redacted_input, redacted_output, status, error |
| 도구 | tool_name, arguments_schema, result_status, retry_count |
| 검색 | query, document_ids, scores, chunk_count |
| 상태 | state_keys_changed, state_diff_hash |
| 안전 | guardrail_result, approval_required, approval_decision |
| 비용 | input_tokens, output_tokens, estimated_cost |
반대로 그대로 저장하면 안 되는 것도 있다. 개인정보, 비밀키, 인증 토큰, 결제 정보, 의료 정보, 원문 계약서, 내부 보안 문서는 마스킹하거나 해시 처리해야 한다. 모든 요청을 100% 저장할 필요도 없다. 저위험 트래픽은 샘플링하고, 실패·승인 거절·가드레일 위반·고비용 실행은 우선 저장하는 방식이 현실적이다.
Eval의 종류
eval은 에이전트가 잘했는지 판단하는 테스트다. Anthropic은 agent eval을 task, trial, grader, transcript, outcome, evaluation harness 같은 구성 요소로 설명한다. 여기서 transcript는 trace에 해당하고, outcome은 최종 환경 상태다.4 이 구분은 중요하다. 에이전트가 '예약했습니다'라고 말했더라도 실제 DB에 예약이 없으면 성공이 아니다.
에이전트 평가에는 여러 방식이 필요하다.
정답 기반 평가: 예상 답변, 예상 도구 호출, 예상 상태 변화를 기준으로 비교한다.
코드 기반 평가: JSON 스키마, 필수 필드, 금지 도구 호출, DB 상태를 프로그램으로 검사한다.
LLM-as-judge: 별도 모델이 루브릭에 따라 관련성, 근거성, 친절성 등을 평가한다.
휴먼 평가: 정책 해석, 법무 문서, 고객 응대처럼 애매한 사례를 사람이 검토한다.
시뮬레이션 테스트: 가짜 사용자, 가짜 API 오류, 빈 검색 결과를 넣어 반응을 본다.
회귀 테스트: 고정된 데이터셋으로 변경 전후 성능을 비교한다.
에이전트 eval은 최종 답변만 보면 부족하다. retrieved context, tool call, plan, handoff, guardrail 결과도 평가 대상이다. 예를 들어 답변은 맞았지만 필요 없는 결제 도구를 호출했다면 안전하지 않다. 검색 근거는 맞았지만 라우터가 매번 비싼 모델로 보낸다면 운영 비용 문제가 된다.
운영 지표 설계
운영 지표는 제품 목적과 연결되어야 한다. 이 장에서는 다음 지표를 기본 세트로 둔다.
task success rate: 작업을 실제로 완료한 비율
tool call accuracy: 올바른 도구를 올바른 인자로 호출한 비율
groundedness: 답변이 검색 근거에 의해 뒷받침되는 정도
unsupported claim rate: 근거 없는 주장 비율
latency: 응답 지연 시간, 특히 p95와 p99
token cost: 요청당 토큰과 비용
retry·loop rate: 반복 호출, 무한 루프, 과도한 재시도 비율
escalation rate: 사람에게 넘긴 비율
approval rejection rate: 승인 요청 중 거절된 비율
도구 사용 평가는 특히 중요하다. Ragas의 ToolCallAccuracy처럼 도구 호출 순서와 인자 정확도를 함께 보는 방식은 multi-step workflow 검증에 유용하다.5 단, 모든 작업에서 순서가 중요한 것은 아니다. 날씨를 파리와 런던에 대해 각각 조회하는 작업은 순서가 달라도 된다. 반면 '주문 조회 후 환불 처리'는 순서가 중요하다.
벤치마크 점수만 높이는 것은 목표가 아니다. 실제 업무 로그에서 실패 유형을 분류하고, 빈도와 위험도를 기준으로 개선 우선순위를 정해야 한다. 1년에 한 번 나오는 특이 실패보다 매일 30번 발생하는 잘못된 라우팅이 먼저다. 읽기 전용 FAQ 오류보다 결제·삭제·전송 도구 오류가 더 위험하다.
쉬운 비유 또는 사례
trace는 자동차 블랙박스와 비슷하다. 사고가 난 뒤 운전자가 '갑자기 그랬다'고 말해도 원인을 알 수 없다. 블랙박스가 있으면 속도, 위치, 신호, 충돌 시점을 확인할 수 있다.
eval은 정비소의 점검표와 같다. 브레이크가 작동하는지, 타이어가 마모됐는지, 엔진 경고등이 켜졌는지 기준에 따라 확인한다. 감으로 '괜찮아 보인다'고 판단하지 않는다.
에이전트도 같다. trace는 실행의 블랙박스다. eval은 점검표다. 둘이 없으면 에이전트는 데모에서는 똑똑해 보이지만 운영에서는 고치기 어려운 시스템이 된다.
직접 해보는 실습
이번 실습은 Tool use와 function calling에서 만든 FAQ agent와 Human approval과 guardrails에서 만든 승인형 문서 agent를 사용한다.
1단계: trace ID와 span 기록 추가
각 사용자 요청이 들어올 때 trace_id를 생성한다. 각 작업 단위에는 span_id를 붙인다. 최소 span type은 다음과 같이 둔다.
user_input
router_decision
planner_step
retrieval
llm_generation
tool_call
tool_result
state_update
guardrail_check
approval_event
final_output
처음에는 파일 로그나 SQLite로 충분하다. 중요한 것은 예쁜 대시보드가 아니라 같은 구조로 계속 남기는 것이다.
2단계: 필수 필드 저장
각 span에 다음 필드를 남긴다.
| 필드 | 설명 |
|---|---|
| trace_id | 하나의 실행을 묶는 ID |
| span_id | 작업 단위 ID |
| parent_span_id | 상위 작업 ID |
| span_type | retrieval, tool_call 등 |
| input_summary | 민감 정보 제거 후 입력 요약 |
| output_summary | 민감 정보 제거 후 출력 요약 |
| status | success, error, blocked |
| latency_ms | 소요 시간 |
| token_count | 사용 토큰 |
| cost_estimate | 예상 비용 |
| metadata | 모델, 프롬프트, 도구 스키마 버전 |
도구 호출 span에는 tool_name, arguments, result_status, error_message를 추가한다. 승인 span에는 approval_required, approver_role, decision, reason을 추가한다.
3단계: 실패 사례 10개 수집
다음 시나리오를 실행한다.
정상 FAQ 질문 5개
근거 문서가 없는 FAQ 질문 3개
애매한 질문 2개
문서 초안 생성 요청 5개
외부 발송 또는 삭제가 포함된 위험 요청 5개
실패 사례 10개를 골라 다음 분류표에 넣는다.
| 실패 분류 | 판단 기준 |
|---|---|
| 프롬프트 문제 | 지시를 이해했지만 답변 형식이나 정책을 어김 |
| 도구 호출 오류 | 잘못된 도구, 잘못된 인자, 불필요한 호출 |
| 검색 근거 부족 | 검색 결과가 없거나 엉뚱한 문서 사용 |
| 상태 관리 오류 | 이전 단계 결과를 잊거나 잘못 덮어씀 |
| 라우터·플래너 오류 | 잘못된 경로 선택, 불필요한 단계 생성 |
| 승인·가드레일 정책 문제 | 승인 필요 작업을 자동 실행하거나 과도하게 차단 |
4단계: 간단한 eval 작성
처음부터 복잡한 평가 시스템을 만들 필요는 없다. 다음 네 가지부터 시작한다.
FAQ 답변은 근거 문서 ID를 포함해야 한다.
근거 문서에 없는 주장은 unsupported claim으로 표시한다.
발송·삭제·결제·권한 변경 도구는 approval_event 없이 실행되면 실패다.
예상 도구 목록이 있는 테스트에서는 tool_name과 핵심 인자가 일치해야 한다.
5단계: 수정 계획 리포트 작성
각 실패에 대해 다음 형식으로 정리한다.
| 항목 | 내용 |
|---|---|
| failure_id | F-001 |
| scenario | 사용자의 요청 |
| failing_span | 실패가 발생한 span |
| expected | 기대 동작 |
| actual | 실제 동작 |
| metric | 영향을 받은 지표 |
| root_cause | 원인 분류 |
| fix_plan | 수정 계획 |
| retest_dataset | 다시 돌릴 데이터셋 버전 |
평가 데이터셋은 버전 관리한다. 예를 들어 faq_eval_v1, doc_agent_eval_v1처럼 이름을 붙인다. 프롬프트, 도구 스키마, 라우터 기준, 모델을 바꾸기 전후에 같은 데이터셋을 실행해야 회귀를 발견할 수 있다.
흔한 실수와 오류 분석
첫째, 최종 답변만 저장한다. 그러면 검색 실패인지, 도구 실패인지, 모델 생성 실패인지 구분할 수 없다.
둘째, 에이전트가 스스로 보고한 도구 호출을 믿는다. 도구 호출 로그는 런타임 실행 계층에서 직접 남겨야 한다. 모델이 '호출했다'고 말하는 것과 실제 호출은 다르다.
셋째, 민감 정보를 그대로 저장한다. tracing은 보안을 약화시키기 위한 장치가 아니다. 마스킹, 샘플링, 접근 제어, 보관 기간 설정이 함께 있어야 한다.
넷째, LLM-as-judge 점수를 절대 진실로 여긴다. judge 모델도 틀린다. 중요한 평가는 사람 샘플링으로 보정하고, 가능한 항목은 코드 기반 평가로 검사한다.
다섯째, 데이터셋을 매번 바꾼다. 평가 데이터가 계속 달라지면 프롬프트 개선인지 데이터 난이도 변화인지 알 수 없다.
여섯째, 평균 점수만 본다. 평균 성공률이 높아도 결제 취소, 개인정보 노출, 외부 발송 같은 고위험 코호트에서 실패하면 배포하면 안 된다.
요약
trace는 하나의 실행 전체 기록이고, span은 그 안의 작업 단위다.
에이전트 trace에는 LLM 호출뿐 아니라 도구, 검색, 상태 변경, 라우팅, 승인, 가드레일 이벤트가 포함되어야 한다.
eval은 최종 답변뿐 아니라 중간 실행 단계와 실제 환경 outcome까지 평가해야 한다.
운영 지표는 성공률, 근거성, 도구 정확도, 비용, 지연 시간, 루프, 승인 거절률을 함께 봐야 한다.
실제 실패 로그를 평가 데이터셋으로 만들고, 버전 관리된 회귀 테스트로 개선 여부를 확인해야 한다.
퀴즈
trace와 span의 차이를 설명하라.
최종 답변만 평가하면 에이전트 디버깅이 어려운 이유는 무엇인가?
tool call accuracy를 평가할 때 도구 이름 외에 무엇을 확인해야 하는가?
LLM-as-judge를 사용할 때 주의할 점은 무엇인가?
approval rejection rate가 높을 때 가능한 원인 두 가지를 적어보라.
체크리스트
모든 요청에 trace_id가 생성된다.
LLM generation, retrieval, tool call, state update가 span으로 기록된다.
guardrail과 approval 이벤트가 같은 trace에 남는다.
민감 정보 마스킹 정책이 있다.
실패 로그에서 평가 데이터셋을 만들었다.
프롬프트·모델·도구 변경 전후를 같은 데이터셋으로 비교한다.
최종 답변뿐 아니라 도구 호출과 검색 근거도 평가한다.
비용과 latency 지표를 함께 본다.
고위험 작업은 별도 코호트로 평가한다.
다음 장 연결
이번 장에서는 에이전트를 어떻게 관측하고 평가할지 배웠다. 다음 장에서는 이 데이터를 운영 환경에서 어떻게 관리할지 다룬다. 배포 runtime, 큐, 작업자, 재시도, rate limit, 비용 예산, 알림, 운영 지표 대시보드를 연결해 실제 서비스로 운영 가능한 구조를 설계한다.
참고
1LLM Tracing | DeepEval by Confident AI
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.