Observabilidade de API LLM: métricas, traces, logs e custo

A observabilidade de API LLM é a prática de transformar cada chamada de modelo em evidências estruturadas suficientes para responder a quatro perguntas de produção:

1. A requisição foi bem-sucedida?
2. Quanto tempo o usuário esperou?
3. O que a requisição consumiu e custou?
4. Por que o sistema escolheu aquele modelo, retry ou fallback?

O monitoramento HTTP comum é necessário, mas não é suficiente. Um 200 OK ainda pode conter JSON inválido, uma resposta vazia, uma resposta recusada, uma chamada de ferramenta quebrada ou uma saída que viole o contrato da aplicação. Uma requisição também pode ser bem-sucedida após três tentativas e, silenciosamente, custar quatro vezes mais do que o esperado.

O objetivo prático não é registrar todos os prompts. É criar um pequeno contrato de telemetria consistente que conecte os resultados da aplicação com modelo, provedor, rota, latência, uso de tokens, retries e custo — sem vazar dados do usuário.

Este guia mostra como construir esse contrato com métricas, traces, logs estruturados, objetivos de nível de serviço, dashboards e alertas.

O que a observabilidade de API LLM deve explicar

Um sistema de observabilidade útil permite que um engenheiro de plantão vá rapidamente de um sintoma à causa.

A primeira regra de design é simples: meça o contrato da aplicação, não apenas o contrato de transporte.

As cinco camadas de telemetria

O monitoramento de API LLM fica mais fácil quando você separa cinco camadas em vez de forçar todos os sinais para um único dashboard.

1. Métricas de requisição

Métricas mostram tendências e alimentam alertas. Registre contadores e histogramas para:

• Contagem de requisições
• Latência ponta a ponta
• Tempo até o primeiro token para respostas em streaming
• Latência do provedor ou da chamada ao modelo
• Requisições bem-sucedidas, com falha, canceladas e com timeout
• Respostas HTTP 429 e 5xx
• Tentativas de retry e fallback
• Tokens de entrada, saída e em cache
• Custo estimado e reconciliado

As métricas devem ter rótulos com cardinalidade limitada. Bons rótulos incluem provider, model, route, environment, status e error_type. Evite rótulos de alta cardinalidade, como IDs de usuário, IDs de requisição, texto de prompt ou URLs completas.

2. Traces distribuídos

Um trace explica o caminho de uma requisição pela sua API, fila, camada de retrieval, chamadas de ferramenta, gateway e provedor de modelo.

Uma hierarquia prática de trace se parece com isto:

POST /support/reply
├── retrieve_customer_context
├── llm.route
│   ├── llm.attempt provider_a/model_primary
│   └── llm.attempt provider_b/model_fallback
├── validate_structured_output
└── persist_draft

Cada tentativa de modelo deve ser seu próprio span. Se dois provedores forem tentados, o trace precisa mostrar duas tentativas em vez de esconder ambas dentro de um único span opaco llm.call.

As convenções semânticas de IA Generativa do OpenTelemetry fornecem um vocabulário compartilhado útil para spans, métricas e eventos de IA generativa. Trate a versão da convenção como parte do seu esquema de telemetria para que você possa migrar de forma deliberada quando os atributos evoluírem.

3. Logs estruturados

Logs capturam decisões discretas e contexto de diagnóstico que seriam caros demais ou detalhados demais para serem usados como rótulos de métricas.

Eventos úteis incluem:

• llm.request.started
• llm.route.selected
• llm.retry.scheduled
• llm.fallback.selected
• llm.response.validated
• llm.request.completed
• llm.request.failed

Cada evento deve incluir os mesmos campos de correlação: request_id, trace_id, route, model, provider, prompt_version e attempt.

4. Sinais de qualidade e contrato

A qualidade não pode ser inferida a partir de códigos de status. Adicione validadores determinísticos sempre que possível:

• JSON analisado com sucesso
• Os campos obrigatórios do schema existem
• O nome da ferramenta e os argumentos são अनुमति?
• A lista de citações está presente quando exigido
• O comprimento da saída está dentro dos limites do produto
• O estado de recusa ou segurança é reconhecido
• As verificações de regras de negócio passam

Para tarefas subjetivas, anexe depois resultados de avaliação amostrados. Mantenha a telemetria online da requisição e a avaliação offline unidas por meio de um request ID ou sample ID estável.

Antes de substituir um modelo em produção, use um fluxo de avaliação de modelos de IA repetível em vez de depender apenas da latência agregada e do preço dos tokens.

5. Custo e resultados de negócio

Contagens de tokens são sinais de uso, não resultados de negócio. Conecte o uso do modelo à unidade com a qual seu produto se importa:

• Custo por resposta de suporte aceita
• Custo por tarefa de programação concluída
• Custo por imagem de produto gerada aprovada por um revisor
• Custo por lead qualificado enriquecido
• Custo por extração estruturada bem-sucedida

A fórmula mais útil é:

custo efetivo por tarefa aceita = custo total do modelo / tarefas aceitas

Isso expõe falsas economias. Um modelo mais barato que cause mais retries, falhas de validação ou retrabalho humano pode aumentar o custo efetivo.

Um contrato mínimo de telemetria para cada chamada de modelo

Comece com um esquema de eventos versionado. Os nomes exatos dos campos podem seguir seu stack de observabilidade, mas os conceitos devem permanecer estáveis.

{
  "schema_version": "llm-observability.v1",
  "timestamp": "2026-07-30T09:00:00Z",
  "request_id": "req_internal_01",
  "trace_id": "7c4b...",
  "environment": "production",
  "feature": "support_reply",
  "route": "support-default",
  "provider": "provider-a",
  "model": "model-primary",
  "prompt_version": "support-reply-v12",
  "attempt": 1,
  "stream": true,
  "status": "success",
  "http_status": 200,
  "latency_ms": 1840,
  "time_to_first_token_ms": 410,
  "input_tokens": 1640,
  "output_tokens": 284,
  "cached_input_tokens": 900,
  "estimated_cost_usd": 0.0068,
  "validator": "aprovado",
  "fallback_reason": null,
  "provider_request_id": "redacted-or-scoped-value"
}

Não torne prompts e respostas brutos campos obrigatórios. Armazene-os apenas quando houver uma necessidade definida, uma política de retenção aprovada, controles de acesso apropriados e um caminho seguro de redação.

Métricas que devem estar no primeiro dashboard

Não comece com 40 painéis. Construa um dashboard operacional que responda se os usuários estão recebendo resultados válidos dentro do orçamento de latência e custo.

Tráfego e sucesso

• Solicitações por minuto
• Taxa de sucesso de transporte
• Taxa de sucesso validado
• Taxa de cancelamento
• Taxa de timeout
• Razão de amplificação de retries
• Taxa de fallback

Taxa de sucesso validado deve ser o principal sinal de disponibilidade:

taxa de sucesso validado = solicitações que passam no contrato da aplicação / solicitações elegíveis

Isso é mais rigoroso e mais útil do que respostas 2xx / solicitações.

Latência

Acompanhe distribuições em vez de médias:

• Latência p50, p95 e p99 de ponta a ponta
• Latência p50, p95 e p99 da chamada ao provedor
• Tempo até o primeiro token p50 e p95
• Espera na fila p95
• Execução de ferramenta p95
• Duração da validação p95

Separe rotas com streaming e sem streaming. Uma solicitação com streaming pode parecer responsiva com um bom tempo até o primeiro token, mesmo quando o tempo total de conclusão é longo.

Confiabilidade

• Taxa de 429 por provedor e modelo
• Taxa de 5xx por provedor e modelo
• Taxa de erro de rede
• Taxa de resposta malformada ou inválida pelo schema
• Taxa de falha em chamada de ferramenta
• Estado aberto do circuit breaker
• Taxa de orçamento de retries esgotado

Se limites de taxa forem uma causa frequente, use uma estratégia de retry de LLM para limites de RPM e TPM com limite em vez de retries não coordenados em cada worker da aplicação.

Uso e custo

• Tokens de entrada e saída por recurso
• Tokens por tarefa aceita
• Custo estimado por solicitação
• Custo por tarefa aceita
• Custo de retry
• Delta de custo de fallback
• Gasto diário versus orçamento
• Estimativa de custo versus fatura do provedor ou exportação de uso

Mantenha tanto estimated_cost quanto reconciled_cost. O primeiro permite monitoramento quase em tempo real; o segundo corrige as estimativas depois que os dados oficiais de cobrança chegam.

Como rastrear retries e roteamento de fallback

Retries e fallbacks são onde o monitoramento básico geralmente falha. Se todas as tentativas compartilham um único campo de status, uma solicitação cara e degradada pode parecer saudável.

Registre estes campos para cada tentativa:

Um playbook de roteamento de fallback de API LLM em produção deve definir a política de decisão. A observabilidade deve então provar que o roteador a seguiu.

Padrão de instrumentação em TypeScript

O exemplo a seguir mantém a telemetria independente de um SDK específico de modelo. Ele registra um span de rota pai e um span filho para cada tentativa.

import { context, SpanStatusCode, trace } from "@opentelemetry/api";

const tracer = trace.getTracer("ai-gateway");

type ModelAttempt = {
  provider: string;
  model: string;
  reason: "primary" | "retry" | "fallback";
};

export async function runModelRoute(
  attempts: ModelAttempt[],
  callModel: (attempt: ModelAttempt) => Promise<{
    text: string;
    usage?: { inputTokens?: number; outputTokens?: number };
    providerRequestId?: string;
  }>,
) {
  return tracer.startActiveSpan("llm.route", async (routeSpan) => {
    routeSpan.setAttribute("app.llm.route", "support-default");
    routeSpan.setAttribute("app.llm.attempt_limit", attempts.length);

    try {
      for (const [index, attempt] of attempts.entries()) {
        const result = await tracer.startActiveSpan(
          "llm.attempt",
          { attributes: {
            "gen_ai.system": attempt.provider,
            "gen_ai.request.model": attempt.model,
            "app.llm.attempt": index + 1,
            "app.llm.reason": attempt.reason,
          } },
          context.active(),
          async (attemptSpan) => {
            const startedAt = performance.now();

            try {
              const response = await callModel(attempt);
              const valid = response.text.trim().length > 0;

              attemptSpan.setAttribute("app.llm.validated", valid);
              attemptSpan.setAttribute(
                "gen_ai.usage.input_tokens",
                response.usage?.inputTokens ?? 0,
              );
              attemptSpan.setAttribute(
                "gen_ai.usage.output_tokens",
                response.usage?.outputTokens ?? 0,
              );
              attemptSpan.setAttribute(
                "app.llm.latency_ms",
                performance.now() - startedAt,
              );

              if (!valid) {
                throw new Error("response_validation_failed");
              }

              attemptSpan.setStatus({ code: SpanStatusCode.OK });
              return response;
            } catch (error) {
              attemptSpan.recordException(error as Error);
              attemptSpan.setStatus({
                code: SpanStatusCode.ERROR,
                message: (error as Error).message,
              });
              return null;
            } finally {
              attemptSpan.end();
            }
          },
        );

        if (result) {
          routeSpan.setAttribute("app.llm.selected_attempt", index + 1);
          routeSpan.setStatus({ code: SpanStatusCode.OK });
          return result;
        }
      }

      throw new Error("llm_route_exhausted");
    } catch (error) {
      routeSpan.recordException(error as Error);
      routeSpan.setStatus({
        code: SpanStatusCode.ERROR,
        message: (error as Error).message,
      });
      throw error;
    } finally {
      routeSpan.end();
    }
  });
}

Em produção, adicione seus contadores de métricas e eventos de log estruturados junto com os spans. Capture também os identificadores de solicitação do provedor quando उपलब्धíveis; eles costumam ser essenciais ao escalar um incidente para o provedor do modelo. Mantenha esses identificadores fora das mensagens de erro públicas.

Logs sem vazamento de prompt

O padrão mais seguro é o logging com foco em metadados primeiro.

Logar por padrão

• IDs internos de request e de trace
• ID de request do provedor
• Nome do recurso e da rota
• Provedor, modelo e alias de deployment
• Versão do template de prompt
• Parâmetros como temperatura e número máximo de tokens de saída
• Uso de tokens
• Latência e tempo até o primeiro token
• Classe do erro e decisão de retry
• Resultado do validador
• Nomes de ferramentas sanitizados

Não logar por padrão

• Prompts ou respostas brutos
• Chaves de API ou headers de autorização
• Segredos do cliente
• Documentos recuperados
• Argumentos de ferramentas contendo dados pessoais ou regulados
• Caminhos completos de arquivos ou registros de banco de dados
• URLs assinadas

Quando a captura de conteúdo for necessária para depuração ou avaliação, amostre-o separadamente, faça a redação antes de armazenar, restrinja o acesso, criptografe-o e defina um período curto de retenção. O guia de gerenciamento seguro de chaves de API cobre os controles adjacentes para segredos, logging, rotação e resposta a incidentes.

SLOs para funcionalidades baseadas em LLM

Um objetivo de nível de serviço de LLM deve descrever a funcionalidade visível para o usuário, não a conta do provedor.

Exemplos de SLOs para uma funcionalidade estruturada de resposta a suporte:

Esses números são exemplos, não metas universais. Defina-os a partir das expectativas dos usuários, da complexidade da tarefa, do comportamento do provedor e da economia unitária.

Use orçamentos de erro para decidir quando desacelerar lançamentos de funcionalidades, apertar a política de rota ou deslocar tráfego. Um provedor pode atingir sua própria meta de disponibilidade enquanto seu produto falha em cumprir o SLO porque o enfileiramento, as ferramentas, a validação ou o comportamento de fallback adicionam falhas.

Alerta sobre sintomas, diagnóstico com causas

Acione um operador para impacto ao usuário. Use alertas de menor severidade ou anotações no dashboard para causas prováveis.

Sintomas que merecem pager

• A taxa de sucesso validada viola o SLO
• O p95 do tempo até o primeiro token excede o limite voltado ao usuário
• A taxa de rota esgotada aumenta drasticamente
• O custo por tarefa aceita excede o limite
• Uma funcionalidade crítica não tem nenhum alvo saudável compatível com o contrato

Sinais de diagnóstico

• A taxa de 429 de um provedor aumenta
• A taxa de falha de schema de um modelo muda
• A amplificação de retry aumenta
• O tempo de espera na fila cresce
• O circuit breaker abre
• O uso de tokens muda após uma release de prompt

Evite acionar pager para todo 5xx do provedor. Se o fallback estiver funcionando e os usuários ainda receberem respostas válidas dentro do orçamento de latência, o evento pode exigir investigação sem acordar o engenheiro de plantão.

Um modelo operacional com três dashboards

Dashboard 1: Experiência do usuário

Mostre disponibilidade validada, latência, tempo até o primeiro token, conclusão de tarefas e erros visíveis ao usuário por funcionalidade.

Painel 2: Roteamento e provedores

Mostre a participação de tráfego, erros do provedor, retries, fallbacks, circuit breakers, exaustão de rotas e latência por modelo e destino.

Painel 3: Uso e economia

Mostre tokens, gasto estimado, gasto reconciliado, custo por tarefa aceita, desvio do orçamento e principais funcionalidades por custo.

Mantenha as anotações de implantação e de versão do prompt em todos os três. Caso contrário, uma regressão que começa imediatamente após uma release pode parecer uma variação aleatória do provedor.

Checklist de rollout

1. Defina um esquema de eventos versionado.
2. Gere um ID interno de requisição na fronteira do produto.
3. Propague o contexto de trace por filas, ferramentas e chamadas ao modelo.
4. Crie um span filho para cada tentativa de modelo.
5. Registre os IDs de requisição do provedor quando retornados.
6. Adicione validação determinística da saída.
7. Rastreie explicitamente os motivos de retry e fallback.
8. Calcule o custo estimado a partir de uma tabela de preços versionada.
9. Reconcilie as estimativas com exports de uso ou faturamento autoritativos.
10. Construa primeiro um dashboard de resultado do usuário antes dos dashboards do provedor.
11. Defina um SLO para sucesso validado e latência.
12. Mascare ou exclua prompts, respostas, segredos e dados sensíveis de ferramentas.
13. Execute testes de falha para timeout, 429, 5xx, saída malformada e exaustão de rotas.
14. Revise a cardinalidade dos rótulos antes de habilitar métricas em produção.
15. Amostre traces por risco: retenha erros e requisições lentas com mais intensidade do que sucessos rotineiros.

Erros comuns de observabilidade

Tratar todo 200 como sucesso

Adicione validadores de contrato e reporte o sucesso validado separadamente.

Registrar prompts brutos para cada requisição

Isso cria problemas de privacidade, segurança, retenção e custo. Prefira metadados e amostragem controlada.

Esconder retries dentro de uma única duração

Crie um span e um evento por tentativa para que os operadores possam ver a amplificação.

Usar nomes de modelo como a única identidade da rota

Rastreie provedor, implantação ou alias de conta, região e política de rota. O mesmo modelo pode se comportar de forma diferente entre destinos.

Disparar alertas com base na latência média

Médias escondem problemas na cauda. Use p95 e p99, e separe o tempo até o primeiro token do tempo total de conclusão.

Confiar para sempre no custo estimado

Tabelas de preços, tratamento de cache e contabilidade do provedor podem mudar. Reconcilie as estimativas com dados de faturamento e registre a versão da tabela de preços.

Permitir que os rótulos de telemetria cresçam sem limites

IDs de requisição e identificadores de clientes pertencem a traces ou logs, não a rótulos de métricas.

Onde um gateway de API de IA ajuda

Aplicações multi-provedor, de outro modo, precisam de adaptadores separados para autenticação, nomenclatura de modelos, retries, campos de uso, erros e exports de faturamento. Um gateway pode reduzir essa superfície de integração ao oferecer à aplicação uma fronteira de API estável, preservando ao mesmo tempo os detalhes do provedor e do modelo na telemetria interna.

Flatkey fornece uma chave de API, um endpoint compatível com OpenAI e acesso a modelos de grandes provedores. Isso torna possível centralizar o contrato de telemetria do lado da aplicação, mesmo quando as cargas de trabalho usam diferentes modelos de texto, imagem ou vídeo. O gateway não substitui a observabilidade em nível de produto: sua aplicação ainda deve registrar a funcionalidade, a versão do prompt, o resultado da validação, a latência visível ao usuário e o desfecho da tarefa aceita.

Se a sua equipe estiver consolidando provedores, comece com o guia de arquitetura de gateway de API de IA e depois adicione o contrato de telemetria neste artigo antes de mover o tráfego de produção.

Perguntas frequentes

O que é observabilidade de API LLM?

Observabilidade de API LLM é a coleta e a correlação de métricas, traces, logs, verificações de qualidade, uso e dados de custo para recursos movidos por modelos. Ela explica tanto o comportamento do provedor quanto se a aplicação retornou um resultado válido para o usuário.

O que devo monitorar em uma API LLM?

Monitore a taxa de sucesso validada, a latência ponta a ponta, o tempo até o primeiro token, a latência do provedor, as taxas de 429 e 5xx, as tentativas de repetição, os fallbacks, o uso de tokens, o custo estimado, o custo por tarefa aceita e as falhas no contrato de saída.

Prompts e respostas devem ser armazenados em traces?

Não por padrão. Armazene primeiro os metadados. Capture o conteúdo apenas para uma finalidade definida de depuração ou avaliação, com redação, controles de acesso, criptografia, amostragem e uma política de retenção.

Qual é a diferença entre monitoramento de LLM e observabilidade de LLM?

O monitoramento informa que uma métrica conhecida ultrapassou um limite. A observabilidade fornece evidências correlacionadas suficientes para investigar novos modos de falha na aplicação, rota, provedor, modelo, ferramentas e contrato de saída.

Como calculo o custo de LLM por solicitação?

Multiplique as unidades faturáveis de entrada, saída, entrada em cache, mídia ou outras unidades de uso por uma tabela de preços versionada e, em seguida, adicione o custo de tentativas de repetição e de fallback. Concilie a estimativa com os dados de faturamento do provedor ou do gateway.

Qual ID de solicitação devo armazenar?

Crie seu próprio ID interno de solicitação e ID de trace e, depois, armazene também o ID de solicitação do provedor quando a API retornar um. Os IDs internos conectam seus sistemas; o ID do provedor ajuda no suporte externo e na escalada de incidentes.

Crie o contrato de telemetria antes do incidente

O melhor momento para decidir o que uma chamada ao modelo deve registrar é antes da chegada do tráfego de produção. Comece com sucesso validado, distribuições de latência, um span por tentativa, rótulos de métricas com limites definidos, logs com metadados primeiro e custo por tarefa aceita. Em seguida, teste o sistema forçando as falhas que você espera que o roteador trate.

Essa base transforma um relato vago — “o recurso de IA está lento e caro” — em uma decisão rastreável: qual recurso, qual rota, qual modelo, qual tentativa, qual falha, quanto atraso e quanto custo.

Explore os preços da Flatkey quando estiver pronto para comparar rotas multmodelo por trás de uma única API compatível com OpenAI.