Trace e span

Trace é o registro completo de uma requisição do início ao fim, atravessando todos os componentes do sistema. Span é cada etapa dentro desse registro: uma chamada ao modelo, uma busca no índice, a execução de uma ferramenta. Cada span tem início, duração, entradas, saídas e erros. Em agentes, o trace de uma única tarefa pode ter dezenas de spans aninhados, um para cada passo do raciocínio e cada ferramenta usada. É a unidade básica de depuração em sistemas de IA.

Em Produto, quando uma resposta sai errada, o trace responde onde o problema aconteceu: na recuperação, no prompt, no modelo ou em uma ferramenta. Vale pedir para ver um trace real antes de aprovar uma arquitetura. Se o time não consegue mostrar o caminho de uma requisição, não há como operar o sistema com segurança. Por exemplo, um trace de 14 segundos mostra: 0,3 segundo na busca, 1,1 segundo no reranker e 12 segundos em três chamadas sequenciais ao modelo que poderiam rodar em paralelo. O diagnóstico e a solução estão no trace.

Use trace para investigar um caso específico. Use métricas agregadas para acompanhar tendências ao longo do tempo. Use logs para eventos que não fazem parte da estrutura de uma requisição. Uma forma simples de diferenciar: o trace é a história de uma requisição; a métrica é a estatística de todas.

Google Dapper (2010) definiu tracing distribuído; padronizado pelo OpenTracing/OpenCensus e depois OpenTelemetry (2019).

Sigelman et al., Dapper (Google, 2010); OpenTelemetry documentation, Traces