Capítulo 5.3 — Tracing semântico¶
🎯 Objetivo¶
Definir, em nível operacional, o conteúdo mínimo de um trace em sistemas de IA. Sem padronização, traces ficam ilegíveis e a investigação de incidente vira garimpo.
🧠 Tipos de span¶
| Tipo | Atributos chave |
|---|---|
| LLM call | model.name, model.version, prompt.version, input/output tokens, cost, latency, ttft |
| Embedding | model.name, dimensions, batch_size, latency |
| Tool call | tool.name, tool.version, args (redigido), result_size, error |
| Retrieval | index, dimensions, top_k, filters, scores |
| Agent execution | agent.name, agent.version, total tokens, steps, decision_path |
| Handoff (multi-agent / A2A) | from, to, task_id, payload size |
| Human approval | requester, approver, decision, latency |
| Policy decision | policy.bundle, decision, reason |
| ML inference | model.name, model.version, features hashing, latency, output |
📊 Campos mínimos sugeridos¶
trace.id, span.id, parent.id,
agent.name, agent.version,
model.name, model.version, prompt.version,
tenant.id (hash), user.id (hash),
input.tokens, output.tokens, cached.tokens,
cost.usd, latency.ms, ttft.ms,
retriever.index, retriever.dimensions, retriever.scores,
tool.name, tool.version,
policy.bundle, policy.decision, policy.reason,
guardrail.triggered, guardrail.action,
error.code, error.kind (if any)
🧠 Sampling consciente¶
Tracing 100% em escala é caro. Sampling mal feito esconde exatamente o caso interessante. Estratégias úteis:
- Tiered sampling. Alto em erros, alto em casos novos, alto em tenants críticos; mais baixo em tráfego rotineiro.
- Head sampling (decidido no início) é mais barato; tail sampling (decidido depois) captura caudas com mais fidelidade.
- Forçar 100% em incidentes ativos com toggle operacional.
🧠 Replay de traces¶
Salvar traces estruturados permite replay: re-executar a mesma entrada contra versão candidata e medir diferença. Replay é a forma mais honesta de "test in production" sem afetar usuário real.
Para que replay funcione:
- Inputs precisam estar capturados em forma reproduzível.
- PII precisa estar redigida desde a captura.
- Tools com efeito colateral precisam ter mock/replay mode.
🚨 Custo de observabilidade¶
Tracing semântico não é grátis. Custos típicos:
- Volume de span por tarefa: dezenas em agentes complexos.
- Retenção: regulação pode exigir 6–24 meses para audit.
- Backend: armazenamento + indexação + queries.
Decisões de redução de custo passam por: sampling, compactação de payload, retenção em camadas (hot/warm/cold) e separação entre trace de operação (curto prazo) e trace de auditoria (longo prazo).