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.
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.
Resumo
- Ideia Central: Observabilidade para aplicações LLM significa rastrear cada chamada de modelo e invocação de ferramenta como um span, registrar o prompt/resposta/contagem de tokens para cada chamada em um esquema estruturado, e alertar sobre anomalias de custo ou confiabilidade, os mesmos três pilares usados para qualquer sistema distribuído, aplicados às chamadas do Claude.
- Por que Importa: Um loop de agente pode chamar um modelo cinco vezes, invocar três ferramentas e falhar na quarta etapa, e sem rastreamento você só vê "a requisição falhou", não onde ou por quê.
- Conceitos Chave: span, trace, log estruturado, uso de tokens, anomalia de custo, taxa de cache-miss.
- Quando Usar: Qualquer integração do Claude além de um único script descartável se beneficia disso, mas torna-se indispensável quando você tem loops de agente multi-etapa, uso de ferramentas ou gastos em produção pelos quais você é responsável.
- Limitações / Trade-offs: Observabilidade adiciona sobrecarga de latência, volume de logs e tempo de engenharia; instrumentar excessivamente um protótipo de baixo risco desperdiça esforço que seria melhor empregado no envio.
- Tópicos Relacionados: Rastreamento OpenTelemetry, esquemas de logging estruturado, dashboards de custo, alertas de gastos, correlação de deploy.
Fundamentos
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.
Mecânicas e Interações
É 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".
Considerações Avançadas e Aplicações
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.
Conceitos Equivocados Comuns
- "Registrar a resposta é suficiente." - Sem contagens de tokens e um ID de requisição ligando o log a um span de trace, você pode ver o que voltou, mas não por que foi lento ou caro em relação ao resto da execução.
- "Observabilidade é apenas para capturar falhas." - Uma grande parte do valor é proativa: capturar um pico de gastos ou uma taxa crescente de cache-miss antes que se torne um incidente, não apenas diagnosticá-lo após o fato.
- "Rastreamento e logging são a mesma coisa." - O rastreamento mostra a forma e a ordem de uma execução multi-etapa; o logging estruturado mostra o conteúdo de uma chamada; você precisa de ambos para depurar completamente um agente.
- "Isso só importa em grande escala." - Mesmo um projeto paralelo de agente único se beneficia do logging básico de prompt/resposta/token, pois o custo da API do Claude e os padrões de recusa são fáceis de julgar mal sem nenhum registro.
- "O rastreamento de custos é uma preocupação financeira, não de engenharia." - Um loop de agente descontrolado é um bug de confiabilidade que, por acaso, aparece primeiro como uma anomalia de gastos, então a mesma equipe que gerencia a latência deve gerenciar os alertas de custo.
FAQs
A observabilidade de LLM é realmente diferente da observabilidade de aplicações regulares?
- Na maioria, os mesmos três pilares (traces, logs, métricas), aplicados a um novo tipo de chamada.
- As reais diferenças são o que rastreamos: contagens de tokens, identidade do modelo e custo por chamada, nenhum dos quais existe em telemetria típica de serviço web.
- A latência ainda importa, mas uma chamada rápida e cara e uma chamada lenta e barata precisam ser distinguíveis, o que dashboards de latência simples não fazem.
Preciso especificamente de OpenTelemetry, ou posso usar meu próprio formato de rastreamento?
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.
Qual é a configuração mínima viável de observabilidade para uma pequena integração do Claude?
- Registrar o prompt, resposta, modelo, contagens de tokens, latência e um ID de requisição para cada chamada, em um esquema consistente.
- Isso sozinho, sem rastreamento ou dashboards, captura a maioria dos problemas iniciais de custo e qualidade.
- Adicione rastreamento assim que tiver loops de agente multi-etapa onde a ordem das chamadas importa.
Por que o uso de tokens importa tanto quanto a latência?
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.
O que é uma "taxa de cache-miss" e por que eu alertaria sobre ela?
É 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.
Como um trace realmente me ajuda a depurar uma execução de agente lenta, concretamente?
- Ele mostra a lista ordenada de spans (chamadas de modelo e chamadas de ferramenta) para uma requisição, com a duração por span.
- Você pode ver imediatamente se a lentidão é um span dominante ou distribuída uniformemente entre vários.
- A partir daí, você pula para o log estruturado para o ID de requisição desse span específico para ver o prompt e o conteúdo da resposta reais.
Todo span deve ser registrado e rastreado com amostragem de 100%?
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.
Qual é a diferença entre um "span" e um "trace"?
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.
Por que vincular métricas de custo do Claude ao mesmo dashboard das minhas outras métricas de infraestrutura?
- Engenheiros já monitoram esse dashboard diariamente; um dashboard separado apenas para LLM é ignorado.
- Anomalias de custo e latência na camada de modelo frequentemente se correlacionam com os mesmos deploys que afetam o resto do sistema.
- Isso torna o custo um sinal de confiabilidade de primeira classe em vez de uma surpresa mensal na fatura.
O que devo colocar em uma entrada de log estruturado para uma chamada de API do Claude?
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.
Como os deploys se encaixam na observabilidade para aplicações LLM?
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.
Vale a pena instrumentar um pequeno protótipo antes que ele tenha usuários reais?
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.
Relacionados
- Noções Básicas de Observabilidade - o ponto de partida mínimo: registrar um prompt, resposta e contagem de tokens para cada chamada.
- Instrumentando Loops de Agente com Rastreamento OpenTelemetry - como emitir os spans descritos no modelo mental desta página.
- Registro Estruturado de Prompts, Respostas e Contagens de Tokens - o esquema de log que acompanha o rastreamento.
- Integrando Dashboards de Uso e Custo do Claude com Datadog - colocando métricas do Claude ao lado de seus outros dashboards de infraestrutura.
- Alertando sobre Picos de Gastos e Aumento das Taxas de Cache-Miss - transformando esses sinais em alertas proativos.
- Correlacionando Latência e Erros com Deploys de Código - uma lista de verificação para o fluxo de trabalho de correlação de deploy.
- Modelo de ADR: Definindo seu Esquema de Spans OTel para Chamadas de Ferramentas - documentando decisões de nomenclatura de spans e amostragem.
- Melhores Práticas de Observabilidade - uma lista de verificação consolidada para esta seção.
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.