AI 에이전트를 디버깅할 수 있도록 로깅하는 방법

만약 여러분이 에이전트를 배포했고, 특정 실행에서 실패한 이유를 설명하려고 한다면, 이 글이 도움이 될 것입니다. 이는 첫 실제 사용자가 에이전트에 접근하기 전에 마련해야 할 실용적인 로깅 설정입니다.

입력과 최종 답변만을 로깅하는 경우, 실행 중 일부만 실패하는 에이전트는 거의 아무것도 남기지 않습니다. 모델은 계획을 세우고(planned), 도구를 호출하고(called tools), 결과를 읽고(read the results) 과정 중에 마음을 바꾸는데, 이 모든 것이 기록되지 않습니다. 에이전트는 비결정적(non deterministic)이므로, 입력을 다시 재생한다고 해서 실패가 재현되지는 않습니다. 나중에 디버깅할 수 있는 유일한 방법은 발생한 모든 단계를 기록해 두는 것입니다.

하나의 이벤트 스키마로 시작하기

에이전트가 방출하는 모든 이벤트는 동일한 핵심 필드를 공유해야 합니다: 밀리초 단위의 타임스탬프, 작업을 위한 세션 ID, 해당 작업 내에서 이벤트를 순서화하는 단계 인덱스(step index), 고정된 목록에서 가져온 이벤트 유형(llm_call, tool_call, tool_response, planning, evaluation, error, completion), 그리고 로그 레벨입니다.

각 이벤트 유형은 자체 페이로드(payload)를 추가합니다. llm_call은 모델, 입력 및 출력 토큰, 지연 시간(latency)을 전달합니다. tool_call은 도구 이름과 그 인자를 전달합니다. completion은 결과, 총 단계 수, 총 토큰 수, 그리고 총 비용을 전달합니다. 에러는 로그 레벨이 무엇으로 설정되었든 항상 실패한 단계의 전체 페이로드를 전달합니다.

로그가 수집되는 곳에서 스키마를 검증해야 합니다. 필드가 누락되어도 경고만 발생하게 하더라도 말입니다. 단계별 로깅 설정에는 각 이벤트 유형에 대한 전체 필드가 나열되어 있습니다.

모든 LLM 호출과 모든 도구를 래핑하기

LLM 클라이언트 주변에 하나의 래퍼(wrapper)를 두고, 에이전트가 모델에 접근할 수 있는 유일한 방법으로 만드세요. 이 래퍼는 시작 시간을 기록하고, 응답에서 토큰 수를 가져오며, 지연 시간을 계산하고, 이벤트를 방출합니다. 따라서 어떤 호출도 로깅되지 않고 지나갈 수 없습니다. INFO 레벨에서는 프롬프트의 첫 100자와 마지막 100자 및 그 길이를 로깅하는 것으로 충분하며, 이는 보통 프롬프트 버전을 식별하기에 충분합니다. 전체 프롬프트와 응답은 DEBUG 용도로 저장하세요.

도구(Tools)는 한 가지 중요한 차이점으로 동일하게 처리됩니다: 호출과 응답을 두 개의 별도 이벤트로 기록합니다. 도구 호출이 시작되었으나 응답이 도착하지 않는 경우, 이 간극은 두 항목이 분리되어 기록될 때만 나타납니다.

로그를 트레이스로 변환하기

모든 이벤트가 세션 ID와 단계 인덱스를 갖게 되면, 각 작업을 위한 트레이스(trace)를 조립할 수 있습니다. 이는 전체 작업을 위한 루트 스팬(root span), 각 LLM 호출을 위한 자식 스팬(child span), 그리고 해당 LLM 호출에 의해 트리거된 도구 호출들을 중첩한 형태입니다. 재시도(retry)는 동일한 부모 아래의 형제 스팬(sibling span)이 되므로, 첫 번째 시도가 실패했음을 한눈에 볼 수 있습니다.

에이전트 트레이스가 마이크로서비스(microservice) 트레이스와 다른 점은 추론 컨텍스트(reasoning context)입니다. 에이전트가 LLM 호출을 세 번 하고 도구 호출을 두 번 했다고만 말하는 스팬은 무엇이 일어났는지 알려줍니다. 반면, 첫 번째 검색에서 아무것도 반환되지 않아 모델이 쿼리를 재작성했다는 것을 기록하는 스팬은 왜 그런 일이 일어났는지 알려줍니다. 이 에이전트 결정 추적(tracing agent decisions) 가이드에서는 스팬 설계에 대해 더 깊이 다룹니다.

무엇보다 세 가지 숫자를 확인하세요

배포 전에 완벽한 모니터링 시스템을 구축하려다 결국 아무것도 갖추지 못한 채 출시하는 팀들이 많습니다. 다음 세 가지 지표가 에이전트 배포가 잘못되는 가장 흔한 방법을 포착합니다: 작업 성공률(task success rate), 작업당 비용(cost per task), 그리고 오류율(error rate)입니다. 비용은 사람들을 놀라게 하는 부분인데, 실제 트래픽은 테스트가 예측했던 것보다 2~5배 비싼 경우가 많기 때문에, 간단한 일일 비용 알림을 첫날부터 설정하는 것이 가치가 있습니다.

세 가지 지표 중 하나가 변동할 때(예: 작업 성공률이 떨어질 때) LLM 호출 수/작업당 및 도구 성공률을 추가해야 그 이유를 알 수 있습니다. 이 무엇을 먼저 모니터링할지(what to monitor first) 가이드는 나머지 지표들을 추가하는 순서를 제시합니다.

핵심 요약

로깅은 모든 것이 놓이는 기반입니다. 메트릭(Metrics)은 로깅으로부터 계산되며, 트레이스(Traces)는 로깅으로부터 조립되고, 모든 조사 과정은 결국 로깅에 쿼리합니다. 스키마와 래퍼(wrappers)를 초기에 올바르게 설정하는 것은 하루의 비용을 들일 뿐이지만, 이를 건너뛰면 그동안 수집했을 모든 데이터의 가치를 잃게 됩니다. 전체 AI 에이전트 관측 가능성 가이드에서는 대시보드, 비용 추적 및 모니터링이 포착하는 일반적인 실패 패턴을 다룹니다.