Boas Práticas de Observabilidade

Instrumentar bem uma aplicação Claude significa que um pico de custo, uma regressão de latência ou uma regressão de cache aparecem em um dashboard ou em uma página dentro de uma hora, não na fatura do próximo mês.

Esta lista de verificação consolida as práticas abordadas nesta seção em regras contra as quais você pode verificar sua própria instrumentação.

Como Usar Esta Lista de Verificação

• Trate a seção A como o mínimo inegociável para qualquer integração Claude além de um script descartável.
• As seções B e C valem o esforço assim que você tiver loops de agente com várias etapas ou tráfego de produção para monitorar.
• Revise esta lista após seu primeiro incidente real e anote qual regra o teria detectado mais cedo.
• Use as caixas de seleção como uma auditoria literal de sua instrumentação atual, não apenas como um exercício de leitura.

A - Fundamentos de Logging

• Registre cada chamada Claude em um esquema estruturado consistente. Capture prompt, resposta, modelo, contagem de tokens, latência e um ID de solicitação para cada chamada, não apenas para as que falham.
• Use logging.Logger, não print. A saída estruturada através de um framework de logging real integra-se com filtragem de nível de log e a maioria dos agentes de agregação de logs prontos para uso.
• Registre erros no mesmo esquema que os sucessos. Uma forma compartilhada com um campo status permite que uma única consulta cubra ambos os resultados em vez de manter logs de erro separados.
• Gere o ID da solicitação antes da chamada, não depois. Isso garante que você tenha um identificador mesmo quando a chamada gerar uma exceção.
• Centralize a construção de logs em uma única função ou adaptador. Construir o dicionário de log inline em cada local de chamada é como os esquemas se desviam silenciosamente em uma base de código.
• Capture campos de token relacionados ao cache defensivamente. Acesse cache_read_input_tokens e campos semelhantes com getattr(..., None), pois eles só são preenchidos quando o cache de prompt é aplicado.

B - Rastreamento e Visibilidade de Custo

• Emita um span raiz por execução de agente, com um span filho por chamada de modelo e invocação de ferramenta. Isso preserva a forma de uma execução de várias etapas, que logs planos sozinhos não conseguem mostrar.
• Siga a convenção de nomenclatura de atributos gen_ai.* nos spans. A nomenclatura consistente mantém os rastros consultáveis da mesma forma, independentemente de qual serviço ou provedor de modelo os produziu.
• Defina o status do span explicitamente em caso de erro, não apenas record_exception. Um span sem um status de erro explícito ainda pode ser renderizado como bem-sucedido em alguns visualizadores de rastros.
• Mantenha o texto completo do prompt/resposta fora dos atributos do span. Spans são para metadados curtos e estruturados; coloque o texto completo em logs estruturados em vez disso, unidos por ID de solicitação.
• Calcule e envie o custo por chamada, não apenas a contagem de tokens. A contagem de tokens sozinha não responde "quanto custou isso"; multiplique pelo preço atual por modelo e trate essa tabela de preços como configuração.
• Coloque o custo do Claude e as métricas de latência no mesmo dashboard que suas outras métricas de infraestrutura. Um dashboard separado apenas para LLM é verificado com muito menos frequência do que aquele que sua equipe já monitora diariamente.
• Marque cada métrica com pelo menos o modelo e o recurso/endpoint. Métricas de custo sem marcação não podem dizer qual modelo ou qual parte do seu produto está impulsionando os gastos.

C - Alerta e Resposta a Incidentes

• Alerta sobre gastos em relação a uma linha de base móvel, não apenas um valor fixo em dólares. Um limite fixo que se ajusta ao tráfego de hoje se torna obsoleto à medida que o uso cresce.
• Exija um piso absoluto mínimo ao lado de qualquer alerta baseado em proporção. Uma verificação apenas de proporção pode disparar em oscilações estatisticamente grandes, mas praticamente sem sentido, quando a linha de base é pequena.
• Alerta sobre a taxa de cache-miss independentemente dos gastos. É um indicador principal que muitas vezes se move antes que o gráfico de custo se curve visivelmente.
• Execute verificações de alerta em um cronograma, não inline no caminho da solicitação. A lógica de avaliação de alerta não deve adicionar latência ou um novo modo de falha ao código já no caminho crítico para os usuários.
• Use a deduplicação da sua ferramenta de paginação, não lógica de deduplicação personalizada. Reimplementar a escalada e a deduplicação na própria verificação geralmente produz um comportamento pior do que o tratamento integrado da ferramenta de paginação.
• Verifique a correlação de implantação antes de assumir um problema do lado do provedor. A maioria dos picos de latência ou erro remonta a uma implantação recente, edição de prompt ou alteração de configuração mais rapidamente do que remonta a um incidente do lado da Anthropic.
• Anote o que você verificou após cada incidente, incluindo becos sem saída. Uma nota curta de incidente economiza a próxima investigação de refazer o mesmo caminho.

D - Consistência da Equipe

• Documente seu esquema de nomenclatura de spans e atributos em um ADR antes que um segundo serviço adote o rastreamento. Sem uma decisão documentada, cada serviço inventa sua própria nomenclatura, e as consultas de rastros entre serviços se tornam impossíveis.
• Documente sua política de amostragem explicitamente, incluindo a exceção de span de erro. "Amostrar apropriadamente" não é preciso o suficiente para que cada serviço implemente da mesma maneira.
• Substitua ADRs em vez de editá-los no local quando o esquema mudar. Editar no local destrói o registro histórico de por que a decisão original foi tomada.
• Dê aos serviços existentes um prazo concreto de migração quando o esquema mudar. Um ADR sem um plano de implantação deixa serviços já instrumentados permanentemente fora de sincronia com os novos.

Aplicando a Lista de Verificação em Ordem

• Seção A primeiro, sempre. Logging estruturado custa quase nada para adicionar e é a base sobre a qual todas as outras práticas nesta lista são construídas.
• Seção B quando você tiver um loop de agente de várias etapas ou tráfego de produção que valha a pena monitorar. Rastreamento e dashboards adicionam esforço de engenharia real, então eles ganham seu lugar quando o logging sozinho para de responder às suas perguntas.
• Seção C quando B estiver no lugar. Alertar sobre métricas que ainda não existem não é possível; obtenha os sinais fluindo antes de definir limites para eles.
• Seção D assim que outra equipe ou serviço começar a instrumentar. Esperar até que três serviços já tenham divergido transforma isso de uma decisão proativa em um projeto de limpeza.

FAQs

Relacionados

• Como a Observabilidade Funciona para Aplicações LLM - o modelo mental em que esta lista de verificação é construída.
• Fundamentos de Observabilidade - o ponto de partida mínimo para a seção A.
• Instrumentando Loops de Agente com Rastreamento OpenTelemetry - as práticas de rastreamento na seção B.
• Integrando Dashboards de Uso e Custo do Claude com Datadog - as práticas de dashboard na seção B.
• Alertando sobre Picos de Gastos e Taxas Crescentes de Cache-Miss - as práticas de alerta na seção C.
• Correlacionando Latência e Erros com Implantações de Código - a lista de verificação de correlação de implantação referenciada na seção C.
• Modelo ADR: Definindo seu Esquema de Span OTel para Chamadas de Ferramentas - as práticas de ADR na seção D.

Versões da 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 anthropic 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.