Pular para conteúdo

Capítulo 2.12 — Observabilidade de LLMs

🎯 Objetivo

Definir o mínimo necessário para tornar uma chamada de LLM operável. Este capítulo trata da camada de modelo isoladamente; observabilidade de agentes e do sistema completo está na Parte 5.

🧠 Por que tracing de LLM é diferente

Em uma API tradicional, "o que aconteceu" é resumido por: status, latência, payload. Em LLM, a mesma chamada precisa responder também:

  • Qual modelo respondeu? Em qual versão?
  • Qual prompt foi enviado? Em qual versão?
  • Quantos tokens entraram, saíram, vieram do cache?
  • Qual o custo?
  • Que documentos o retriever entregou?
  • Qual decisão a policy tomou?
  • Que tool foi chamada, com quais argumentos (redigidos)?
  • Algum guardrail acionou? Algum fallback?

Sem esses campos, um incidente de LLM é uma caixa-preta. Logging textual genérico não basta.

🧠 Campos mínimos de tracing por chamada

  • request_id, tenant_id (hash), user_id (hash).
  • model.name, model.version, prompt.version, prompt.template_id.
  • input.tokens, output.tokens, cached.tokens.
  • cost.usd, latency.ms, ttft.ms, tpot.ms (quando disponível).
  • sampling.temperature, sampling.top_p.
  • retriever.index, retriever.dimensions, retriever.top_k, retriever.scores.
  • tool.name, tool.version, tool.args (redigido), tool.result_size.
  • policy.bundle, policy.decision, policy.reason.
  • guardrail.triggered, guardrail.action.
  • error.code, error.kind (se aplicável).
  • safety.classification (se houver classificação de risco).

🧠 Padronização: OpenTelemetry GenAI

OpenTelemetry mantém GenAI semantic conventions com nomes canônicos para atributos de span de LLM, embeddings, retrieval e agents. Adotar essa convenção desde o começo evita reescrever dashboards e queries depois que o backend de tracing trocar.

🛡️ Princípios

  • Redaction antes de log. PII, segredos e dados sensíveis nunca vão crus para tracing.
  • Sampling consciente. 100% pode ser caro; 1% pode esconder o caso difícil. Use sampling tier (mais alto em erros, em casos novos, em tenants críticos).
  • Versão sempre. Modelo, prompt, schema, tool, policy. Sem versão, não é debugável.

📚 Referências