Como Funciona a Observabilidade para Aplicações LLM
Observabilidade para uma aplicação LLM responde a uma pergunta simples sob pressão: o que meu sistema com Claude está realmente fazendo agora, e por que ele ficou lento, errado ou caro.
//
Busque em todas as páginas da documentação
Observabilidade para uma aplicação LLM responde a uma pergunta simples sob pressão: o que meu sistema com Claude está realmente fazendo agora, e por que ele ficou lento, errado ou caro.
Essa pergunta soa como observabilidade de infraestrutura clássica, e na maioria das vezes é.
A diferença está no que você está observando passar pelo sistema: prompts, chamadas de ferramentas, tokens e dólares, em vez de apenas requisições HTTP e consultas de banco de dados.
Esta página constrói o modelo mental que o restante da seção de observabilidade assume: rastreamento de spans de chamadas de agente e modelo, registro de prompts e respostas em um esquema consistente, e alerta sobre anomalias de custo ou confiabilidade antes que se tornem incidentes.
Três ideias carregam quase todo o peso neste espaço: traces, logs estruturados e métricas.
Um trace é a forma de uma operação de ponta a ponta, composta por spans.
Em um agente LLM, um trace normalmente cobre uma requisição do usuário, e cada span dentro dele cobre uma chamada de modelo ou uma invocação de ferramenta, aninhados para refletir a ordem real da chamada.
Um log estruturado é diferente de um trace, embora as pessoas frequentemente os confundam.
Uma entrada de log estruturado captura o conteúdo de uma única chamada de API do Claude: o prompt, a resposta, as contagens de tokens, o modelo usado, a latência e um ID de requisição, tudo em um esquema consistente e analisável por máquina.
Pense no trace como respondendo "o que aconteceu e em que ordem", e no log estruturado como respondendo "o que exatamente enviamos e recebemos".
Você precisa de ambos, porque um trace sem conteúdo de log informa que uma chamada de ferramenta foi lenta, mas não por quê, e um log sem um trace informa o que uma chamada continha, mas não como ela se encaixou na execução maior do agente.
Uma analogia mental simples: se seu loop de agente é uma ligação telefônica entre departamentos, o trace é o registro da chamada mostrando quem ligou para quem e por quanto tempo, e o log estruturado é a transcrição do que foi realmente dito em cada chamada.
Métricas são o terceiro pilar: números agregados ao longo do tempo, como tokens por minuto, dólares por dia ou latência p95, geralmente derivados dos traces e logs em vez de capturados separadamente.
É assim que essas peças interagem durante uma execução real do agente.
Uma requisição chega, e sua instrumentação abre um span raiz para ela.
Cada vez que o agente chama o Claude, ele abre um span filho, registra a latência e o resultado, e o fecha; cada vez que invoca uma ferramenta, a mesma coisa.
Trace: handle_user_request
Span: model_call (claude-sonnet-5) 120ms
Span: tool_call (search_docs) 85ms
Span: model_call (claude-sonnet-5) 340ms
Span: tool_call (write_file) 40ms
Span: model_call (claude-sonnet-5) 95msEssa forma sozinha, visível em um visualizador de traces OpenTelemetry, diz que o agente fez três chamadas de modelo e duas chamadas de ferramenta, e que a segunda chamada de modelo foi onde a maior parte da latência ocorreu.
Independentemente, cada uma dessas três chamadas de modelo deve também produzir uma linha de log estruturado: o prompt exato enviado, o texto da resposta, input_tokens, output_tokens, e quaisquer cache_read_input_tokens, marcados com o mesmo ID de requisição do trace.
O ID da requisição é a chave de junção: ele permite que você pivote de "este span de trace foi lento" para "aqui está o prompt e a resposta exatos que o tornaram lento" sem adivinhar.
É aqui que a observabilidade de LLM diverge da observabilidade típica de serviço web: contagens de tokens e identidade do modelo são tão importantes quanto a latência, porque elas impulsionam o custo diretamente.
Um span que levou 200ms e custou 40.000 tokens de entrada é um problema muito diferente de um span que levou 200ms e custou 200 tokens, mesmo que um dashboard apenas de latência os renderizasse de forma idêntica.
As métricas então agregam isso: gasto total por hora, taxa de acerto de cache entre chamadas, taxa de erro por ferramenta, percentis de latência por modelo.
A armadilha comum ao raciocinar sobre isso é tratar "observabilidade" como sinônimo de "logging", e parar por aí.
O logging sozinho lhe dá conteúdo sem forma; você pode ver o que uma chamada fez, mas não como uma cadeia de seis chamadas degradou ao longo de uma execução de agente, e você perde a capacidade de alertar sobre tendências como "a taxa de cache-miss aumentou 15% desde o último deploy".
Em escala, três coisas separam uma equipe que pode depurar um incidente em minutos de uma que passa uma tarde adivinhando.
Primeiro, nomenclatura consistente de spans e atributos entre serviços, para que um trace do seu pipeline de ingestão e um trace do seu runtime de agente usem o mesmo vocabulário para "modelo", "ferramenta" e "ID de requisição".
Segundo, correlacionar sinais específicos de LLM (gastos, taxa de cache-miss, taxa de recusa) com os mesmos marcadores de deploy que você já usa para regressões regulares de serviço, para que um pico seja atribuível a "o deploy às 14:02" em vez de ser tratado como ruído inexplicável.
Terceiro, exportar dados de uso e custo do Claude para os mesmos dashboards que sua equipe já monitora para infraestrutura, em vez de manter um dashboard separado e facilmente ignorado, apenas para LLM.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Declarações de impressão / logging ad hoc | Rápido de adicionar, zero configuração | Sem estrutura, não consultável, sem visibilidade de custo | Scripts locais, experimentos rápidos |
| Apenas logs estruturados | Consultável, captura detalhes de prompt/resposta/token | Sem visibilidade da ordem de chamadas multi-etapa ou cadeias de latência | Integrações de chamada única, APIs simples de requisição/resposta |
| Rastreamento OTel + logs estruturados | Visibilidade completa de forma e conteúdo, unível via ID de requisição | Mais esforço de instrumentação, sobrecarga adicionada | Loops de agente multi-etapa, agentes que usam ferramentas, sistemas de produção |
| Rastreamento + logs + dashboard de custo de terceiros (ex: Datadog) | Custo e confiabilidade ficam ao lado das métricas de infra existentes, suporta alertas | Requer um pipeline de exportação e manutenção de dashboard | Equipes que já executam ferramentas de observabilidade de produção |
Um modo de falha relacionado que vale a pena nomear: amostrar cada span em 100% em um produto de agente de alto volume fica caro e barulhento rapidamente.
A maioria das equipes se contenta com amostragem completa para erros e outliers de custo, com uma taxa de amostragem menor para spans bem-sucedidos rotineiros, uma decisão que vale a pena escrever explicitamente (veja o modelo de ADR referenciado abaixo) para que permaneça consistente à medida que a equipe cresce.
OTel não é obrigatório, mas é o padrão de fato para rastreamento baseado em spans e se integra com a maioria dos dashboards existentes e ferramentas de ingestão de terceiros (como Datadog). Criar seu próprio formato de trace funciona para um único serviço, mas adiciona atrito no momento em que você deseja correlacionar traces entre serviços ou exportar para um dashboard compartilhado.
O uso de tokens impulsiona o custo diretamente e, ao contrário da latência, nem sempre se correlaciona com o tempo de relógio. Uma chamada com um grande prompt em cache pode ser rápida, mas ainda consumir tokens de entrada significativos, portanto, rastrear ambos independentemente é necessário para capturar regressões de custo que uma visão apenas de latência perderia.
É a proporção de chamadas que não atingem o cache de prompt da Anthropic, o que significa que o prompt completo é reprocessado com custo total em vez da taxa de cache mais barata. Uma taxa crescente de cache-miss geralmente sinaliza uma mudança de código que quebrou a elegibilidade do cache (por exemplo, um prefixo de prompt instável), e aumenta silenciosamente os gastos até que alguém perceba o dashboard ou receba um alerta.
Geralmente não em volume de produção significativo. Um padrão comum é amostragem completa para erros e outliers de custo/latência, com uma taxa de amostragem menor para spans bem-sucedidos rotineiros, documentada explicitamente para que toda a equipe a aplique consistentemente.
Um trace é a operação completa de ponta a ponta (tipicamente uma requisição do usuário); um span é uma unidade de trabalho dentro dele (uma chamada de modelo ou uma invocação de ferramenta). Um trace é composto por um ou mais spans aninhados.
No mínimo: o prompt, o texto da resposta, input_tokens, output_tokens, o nome do modelo, a latência e um ID de requisição. Adicione campos de token de cache (cache_read_input_tokens, cache_creation_input_tokens) assim que você depender do cache de prompt, pois esses números afetam diretamente a interpretação do custo.
Timestamps de deploy se tornam uma linha de referência em seus gráficos de latência, erros e custo. Quando uma métrica aumenta logo após um marcador de deploy, você pode atribuir a regressão a uma mudança de código específica em vez de investigar do zero, o que é muito mais rápido do que tratar cada pico como um mistério.
Rastreamento completo e dashboards provavelmente são excessivos, mas o logging estruturado básico (prompt, resposta, tokens, ID de requisição) é barato de adicionar cedo e economiza tempo significativo de depuração assim que o protótipo começa a se comportar mal ou a custar mais do que o esperado.
Versões do Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026