30초 답변
기업용 AI Agent는 API 성공률만 봐서는 운영할 수 없다. 한 번의 사용자 요청을 의도 분류, RAG 검색, 모델 호출, Tool 선택과 실행, 사람 승인, 최종 응답까지 하나의 trace로 묶고 각 단계의 버전·지연·비용·결과·오류를 기록해야 한다. 그래야 “답이 틀렸다”를 검색 실패, 잘못된 Tool 선택, 권한 오류, 모델 응답 오류 중 하나로 좁힐 수 있다.
단, 관측성을 이유로 prompt와 문서 원문을 무제한 저장해서는 안 된다. Tool 인자와 결과에는 개인정보·영업정보·인증정보가 섞일 수 있다. 기본 로그는 식별자·구간·상태·수치 중심으로 두고, 원문은 마스킹·표본 수집·접근 통제·보존 기한을 갖춘 경우에만 남긴다.
이 글의 핵심
- 사용자 요청 하나를 끝까지 연결하는 trace가 운영의 기본 단위다.
- 모델 품질, 검색 품질, Tool 성공, 사용자 완료를 서로 다른 지표로 본다.
- 원문 로그는 진단에 유용하지만 동시에 새로운 데이터 유출 경로가 될 수 있다.
왜 서버 로그만으로는 부족할까
일반 API는 요청, 처리, 응답의 경로가 비교적 고정적이다. Agent는 같은 질문에도 분류 결과, 검색 문서, 선택한 모델, 호출한 Tool, 재시도 횟수가 달라질 수 있다. 최종 응답만 저장하면 어느 단계에서 잘못됐는지 알기 어렵다.
예를 들어 “지난달 미결 주문을 정리해줘”라는 요청이 실패했다고 하자.
- 의도 분류가 보고서 작성이 아니라 일반 Q&A로 갔을 수 있다.
- 데이터 조회 Tool은 맞았지만 기간 인자가 잘못 생성됐을 수 있다.
- 사용자의 권한 때문에 일부 주문이 제외됐을 수 있다.
- 조회는 맞았지만 모델이 집계 결과를 잘못 설명했을 수 있다.
- 최종 응답은 맞지만 40초가 걸려 사용자가 취소했을 수 있다.
이 다섯 상황은 모두 겉으로는 “Agent가 제대로 안 됐다”로 보인다. 그러나 담당 팀과 해결 방법은 전혀 다르다.
Trace의 최소 구조
Trace는 한 번의 사용자 목표를 나타낸다. 그 아래 span은 실제 처리 단계를 나타낸다.
| 계층 | 예시 | 반드시 남길 것 |
|---|---|---|
| Trace | 월간 주문 보고서 생성 | trace ID, 사용자 세션의 익명 식별자, 업무 유형, 시작·종료, 최종 상태 |
| 분류 span | intent routing | 분류기·prompt 버전, 선택 경로, 신뢰 구간, 지연 |
| 검색 span | hybrid retrieval | index 버전, filter, top-k, 문서 ID, 검색 지연 |
| 모델 span | 요약 생성 | provider·model·prompt 버전, token, cache, 지연, 종료 사유 |
| Tool span | 주문 API 조회 | Tool 이름·버전, 권한 범위, 상태 코드, 재시도, 지연 |
| 승인 span | 외부 전송 승인 | 승인 대상, 위험 등급, 승인·거절·만료 |
| 응답 span | 최종 답변 | 출력 형식 검증, 인용 포함 여부, 사용자에게 도달한 시점 |
OpenTelemetry의 GenAI semantic conventions은 모델 호출, Agent, Tool 실행, retrieval 같은 작업을 공통 속성으로 표현하려는 표준화 작업을 제공한다. 상태가 발전 중인 필드는 버전을 고정하고 내부 스키마와의 매핑을 문서화해야 한다.
OpenAI Agents SDK의 tracing도 Agent 실행, handoff, generation, guardrail, function 호출을 span으로 연결하는 방식을 제공한다. 특정 SDK를 쓰지 않더라도 “사용자 목표 하나를 여러 실행 구간으로 분해한다”는 원칙은 그대로 적용할 수 있다.
세 종류의 지표를 분리하자
1. 시스템 지표
- 요청 수와 오류율
- p50·p95·p99 지연
- provider timeout과 rate limit
- token·cache 사용
- Tool 호출 성공률과 재시도
시스템 지표는 서비스가 기술적으로 작동하는지 보여준다. 답이 유용한지는 알려주지 않는다.
2. 품질 지표
- 검색 결과의 관련성
- 근거 문서와 답변의 일치
- 필요한 내용을 빠뜨리지 않았는지
- Tool과 인자의 정확성
- schema validation 통과율
- 평가셋 기준 task success
품질 지표는 샘플링된 온라인 평가와 배포 전 오프라인 평가를 함께 사용한다. 모델 평가 점수 하나를 전체 시스템 품질로 부르지 않는다.
3. 사용자 결과 지표
- 업무 완료율
- 취소·재시도·재질문
- 사람 이관률
- 출처 열람률
- 결과 수정률
- 승인 거절 이유
응답 생성 성공이 곧 사용자 성공은 아니다. 사용자가 결과를 복사한 뒤 전부 다시 고쳤다면 기술적으로는 200이지만 제품으로는 실패에 가깝다.
원문을 기록하기 전에 답해야 할 질문
Tool 호출 인자와 결과, 시스템 지침, 검색된 문서에는 민감정보가 포함될 수 있다. OpenTelemetry의 GenAI 속성 문서도 Tool 인자·결과와 입력·출력 내용이 민감할 수 있음을 경고한다.
원문 로그를 켜기 전에 다음을 결정한다.
- 어떤 진단 목적에 필요한가?
- 식별자·해시·요약만으로 해결할 수 없는가?
- 개인정보와 비밀정보를 어디서 마스킹하는가?
- 누가 볼 수 있고 모든 열람이 감사되는가?
- 보존 기간과 삭제 요청은 어떻게 처리하는가?
- 개발·스테이징·운영의 수집 수준이 분리되어 있는가?
기본값은 content off가 안전하다. 장애 재현이 필요한 특정 trace만 짧은 기간 승인을 받아 상세 수집하는 방식이 낫다.
제품 기본값이 이 안전한 권고와 같다고 가정하지 않는다. 예를 들어 OpenAI Agents SDK는 tracing이 기본 활성화되고 trace_include_sensitive_data 기본값도 true이므로, 운영에서는 해당 옵션을 명시적으로 false로 설정하거나 tracing을 비활성화한 뒤 승인된 수집 정책에 따라 켠다.
실패를 분류하는 운영 코드
자유 텍스트 오류만 남기면 집계할 수 없다. 다음처럼 안정적인 실패 분류를 둔다.
- routing.no_match
- retrieval.no_relevant_document
- retrieval.permission_filtered
- model.timeout
- model.refusal
- output.schema_invalid
- tool.permission_denied
- tool.rate_limited
- tool.invalid_result
- approval.rejected
- user.cancelled
- budget.exceeded
실제 예외 메시지는 별도 필드에 두되 대시보드와 알림은 이 분류를 기준으로 만든다.
사용자가 느끼는 진행 상태도 관측 대상이다
장시간 작업에서 백엔드 trace만 완벽해도 사용자에게 아무 상태를 보여주지 않으면 실패 경험이 된다. UI 이벤트를 같은 trace에 연결한다.
- 요청 접수 시점
- 첫 진행 상태가 보인 시점
- 첫 유용한 결과가 보인 시점
- 승인 요청 시점
- 취소 클릭과 실제 중단 시점
- 최종 결과 표시 시점
이렇게 해야 “모델은 8초였는데 사용자는 18초를 기다렸다” 같은 프런트엔드·큐·승인 지연을 찾을 수 있다.
도입 순서
1단계: 공통 ID와 구간
trace ID를 웹, Agent orchestrator, retrieval, Tool gateway에 전달한다. 업무 유형과 최종 상태만으로도 첫 지도를 만들 수 있다.
2단계: 버전과 비용
model, prompt, Tool, index 버전을 모든 trace에 붙인다. 변경 후 실패가 늘었는지 비교할 수 있어야 한다.
3단계: 품질과 사용자 결과
평가셋, 온라인 표본 평가, 사용자 완료 이벤트를 연결한다.
4단계: 알림과 Runbook
오류율만이 아니라 no-answer 급증, 권한 거절 급증, task success 하락, 작업당 비용 초과에도 알림을 둔다.
실무 체크리스트
- 사용자 목표 하나가 하나의 trace ID로 연결된다.
- routing, retrieval, model, Tool, approval, response span이 구분된다.
- model·prompt·Tool·index 버전이 기록된다.
- p95 지연과 작업당 비용을 계산할 수 있다.
- 실패에 안정적인 분류 코드가 있다.
- 원문 내용 수집은 기본 비활성이다.
- 마스킹, 접근 통제, 보존 기한, 삭제 절차가 있다.
- 사용자 취소·수정·이관·완료 이벤트가 trace와 연결된다.
- 알림마다 담당자와 Runbook이 지정되어 있다.
자주 묻는 질문
모든 prompt와 응답을 저장해야 디버깅할 수 있지 않나?
아니다. 대부분의 용량·지연·라우팅·권한·Tool 오류는 식별자와 구조화된 상태만으로 찾을 수 있다. 원문은 꼭 필요한 표본에 한해 마스킹과 짧은 보존 기간으로 수집하는 편이 안전하다.
모델 provider의 대시보드만 보면 충분한가?
provider 대시보드는 모델 호출을 보여주지만 사내 retrieval, Tool, 승인, 사용자 완료까지 연결하지 못할 수 있다. 조직의 업무 trace가 상위 기준이어야 한다.
관측성 도입의 첫 KPI는 무엇이 좋은가?
먼저 실패를 재현하고 담당 단계로 분류할 수 있는 비율을 본다. 그 다음 p95 지연, task success, 작업당 비용, 이관률을 업무 유형별로 비교한다.