AI agent observability는 user request, model call, tool choice, policy decision, tool execution, downstream effect, retry, final response 전체에 걸쳐 실행 하나를 재구성할 수 있어야 합니다. log, metric, trace, evaluation은 서로 다른 질문에 답하므로 model text만 수집해서는 충분하지 않습니다.
실패했거나 비용이 많이 든 workflow에서 시작해 identifier 하나로 기준 backend result까지 추적할 수 있는지 확인하세요.
decision path와 execution path 전체를 추적하세요
sequenceDiagram
participant U as User
participant A as Agent
participant M as Model
participant P as Policy
participant T as Tool
participant B as Backend
U->>A: Request
A->>M: Model call
M-->>A: Tool selection
A->>P: Authorize identity and action
P-->>A: Decision
A->>T: Tool call with operation ID
T->>B: Downstream request
B-->>T: Authoritative result
T-->>A: Structured result
A-->>U: Response
실행에는 trace, model 및 tool 작업에는 span, trace보다 오래 지속될 수 있는 부작용에는 operation ID를 사용하세요. 가능하다면 tool-call ID를 server까지 전달합니다. database row에는 전체 trace를 저장하지 않고 operation 및 trace로 돌아가는 link만 있어야 합니다.
OpenTelemetry는 model, agent, tool span을 위한 GenAI semantic convention을 제공합니다. 이 convention은 계속 변화하므로 version을 고정하고 experimental attribute name을 애플리케이션 전체에 흩뿌리지 말고 작은 internal schema 계층을 유지하세요.
실행을 설명하는 fact를 수집하세요
Model span
provider, model, response identifier, latency, token usage, finish reason, retry count, prompt-template version을 기록하세요. policy가 허용할 때만 전체 prompt를 저장합니다. 일반 trace에는 hash, redaction된 sample, protected reference로 충분할 수 있습니다.
Tool span
표시되는 tool name과 version, tool-call ID, redaction된 argument, selection source, duration, result class, retry count, downstream operation ID를 기록하세요. “model selected tool”, “policy allowed tool”, “backend completed action”을 구분하세요.
Policy 및 approval span
represented identity, tenant, resource, action, policy version, decision, reason code, approval reference를 기록하세요. access token이나 raw secret을 기록하지 마세요. 거부된 request는 예상된 policy outcome이며 반드시 application error인 것은 아닙니다.
Recovery span
재개된 작업을 원래 workflow 및 operation에 연결하세요. system이 retry했는지, unknown outcome을 reconcile했는지, 완료된 action을 compensate했는지, human review를 위해 중단했는지 기록합니다. 실패 복구 가이드는 이 branch를 설명합니다.
설명이 아니라 pattern에는 metric을 사용하세요
aggregate metric에는 다음 항목이 포함되어야 합니다.
- 성공, 실패, 거부, 취소된 run
- task completion 및 human-escalation rate
- percentile별 model 및 tool latency
- task 및 tenant별 token과 provider cost
- tool selection, validation, authorization, backend error rate
- retry, repeated call, loop stop, unknown outcome
- queue delay, active run, checkpoint age
prompt text, user ID, tool argument, trace ID처럼 값의 수가 제한되지 않는 label은 피하세요. 이런 값은 protected log나 trace에 넣고 metric dimension은 제한적으로 유지합니다.
log를 개별적이고 redaction된 event로 유지하세요
log는 deployment change, policy decision, operation transition, provider error, cleanup에 유용합니다. 안정적인 event name과 structured field를 사용하세요. 모든 계층에 같은 전체 model payload를 기록하지 마세요.
data가 process를 떠나기 전에 redaction을 적용하세요. secret, authorization header, personal data, retrieved document, tool output이 prompt와 error에 나타날 수 있습니다. export 이후 sampling해도 이미 노출된 정보는 되돌릴 수 없습니다.
evaluation으로 quality를 측정하세요
telemetry는 무슨 일이 있었는지 알려 줍니다. 기대 동작이 없다면 response가 유용했는지, tool choice가 맞았는지 결정할 수 없습니다. production failure와 sampling한 trace를 version이 있는 evaluation set에 합친 뒤 model, prompt, tool contract를 바꾸기 전에 실행하세요.
AI agent evaluation 가이드는 deterministic assertion, model judge, repeated trial, release gate를 구분합니다.
사람이 대응할 수 있는 action을 중심으로 alert를 만드세요
deploy 후 광범위한 authorization failure, destructive-tool call 급증, trace continuity 누락, 반복되는 unknown outcome, queue age, spend limit, call 또는 time budget 초과 run처럼 대응 방법이 있는 condition에 alert를 설정하세요.
model error 하나마다 paging하지 마세요. 먼저 provider, model, tool, release, result class별로 묶습니다. dashboard는 noisy quality movement를 보여 줄 수 있지만 page는 구체적인 containment나 rollback action을 가리켜야 합니다.
dashboard를 더 만들기 전에 trace 하나를 감사하세요
실제 run 하나를 골라 수동으로 따라가세요. prompt version, tool list, policy decision, downstream request, business result, cost, retry를 확인할 수 있습니까? trace에서 영향을 받은 operation을, operation에서 trace를 찾을 수 있습니까?
아래 프롬프트는 데이터를 전송하지 않고 repository를 대상으로 이 감사를 수행합니다. 또 하나의 aggregate chart를 만드는 것보다 첫 번째 missing link를 instrumentation task로 삼는 편이 낫습니다.