Como construir observabilidade LLM neutra em termos de provedor com OpenTelemetry

A observabilidade do LLM é interrompida quando cada equipe de aplicativo registra as respostas do provedor em seu próprio formato. Durante um incidente, as equipes da plataforma precisam responder a perguntas concretas: qual equipe fez a solicitação, qual API escopo de chave foi usado, qual modelo foi solicitado, qual provedor realmente atendeu, se ocorreu uma nova tentativa ou fallback, quantos tokens foram consumidos, qual intervalo de latência foi alterado e qual classe de erro causou a falha. Eles também precisam dessas respostas sem copiar prompts brutos, conclusões, chaves de provedor ou identificadores de clientes em armazenamentos de registros genéricos.

A resposta prática é instrumentar o gateway multimodelo API como o ponto de controle de observabilidade. O rastreamento no nível do aplicativo ainda é importante, mas o gateway é onde a seleção do provedor, as novas tentativas, os substitutos, a contabilidade de uso, a propriedade da solicitação e a aplicação da privacidade podem ser normalizados antes que a telemetria chegue às ferramentas downstream. Para equipes que operam um LLM corporativo API, essa se torna a diferença entre dados de depuração dispersos e um modelo operacional neutro em termos de provedor.

Defina primeiro o contrato de observabilidade

Comece com um contrato de atributos escrito, não com capturas de tela do painel. O contrato deve definir os metadados mínimos que cada solicitação LLM deve emitir, quais campos têm permissão para sair do gateway, quais campos são restritos e quais campos nunca são exportados.

Um contrato de linha de base útil inclui propriedade, roteamento, modelo, uso, latência e metadados de resultado. Os atributos de propriedade identificam a organização, a equipe, o ambiente, a carga de trabalho, o aplicativo e o escopo API da chave. Os atributos de roteamento identificam a rota do gateway, a versão da política, o provedor solicitado, o modelo solicitado, o provedor selecionado, o modelo selecionado, a contagem de novas tentativas, a contagem de fallback e se o streaming foi usado. Os atributos de uso capturam tokens de entrada, tokens de saída, tokens de entrada armazenados em cache, tokens de raciocínio quando disponíveis, contagem de solicitações e classe de custo estimada. Os atributos de resultado capturam o status, o código de erro do provedor quando seguro, a classe de erro normalizada, o resultado da validação, o estado de tempo limite e o modelo de resposta final.

Mantenha o contrato neutro em relação ao provedor. Um erro específico do provedor, como resposta de limite de taxa, resposta de modelo sobrecarregado, falha de validação de esquema, recusa de segurança, tempo limite ou erro de janela de contexto, deve mapear para uma classe de erro normalizada que os painéis podem agrupar entre provedores. O código de erro do provedor original pode ser útil, mas deve ser tratado como dados de diagnóstico restritos, não como uma dimensão primária do painel.

Use um modelo de span centrado no gateway

Uma estrutura de rastreamento clara evita que a telemetria LLM se torne uma pilha plana de spans. Use um intervalo de solicitação de aplicativo de entrada, um intervalo de operação LLM lógica e intervalos filho para o trabalho que o gateway executa.

Uma hierarquia típica é semelhante a esta:

inbound.http_request
  llm.operation
    llm.provider_attempt
    llm.provider_attempt.retry
    llm.provider_attempt.fallback
    retrieval.query
    tool.call
    output.validation

O intervalo de solicitação de entrada representa a solicitação do chamador para o gateway. A extensão lógica da operação LLM representa a tarefa LLM visível ao usuário, mesmo que o gateway faça diversas tentativas do provedor. Os períodos de tentativa do provedor capturam cada chamada real para um modelo upstream API. Os períodos de recuperação, ferramenta e validação devem ser filhos da operação lógica quando fazem parte da produção da resposta final.

Essa separação é importante durante incidentes. Se uma solicitação retornar de um modelo para outro, a operação lógica poderá ser bem-sucedida enquanto a primeira tentativa do provedor falhar. Se a saída final falhar na validação do esquema, a tentativa do provedor poderá ser tecnicamente bem-sucedida enquanto a operação lógica falhar. Sem períodos separados, os painéis ocultam falhas do provedor por trás de respostas bem-sucedidas do usuário final ou exageram falhas que foram recuperadas com sucesso.

Mapear atributos do OpenTelemetry GenAI por trás de um mapeador interno

As convenções semânticas do OpenTelemetry existem para que os produtores de telemetria usem nomes e atributos comuns em bases de código, bibliotecas e plataformas.O projeto OpenTelemetry agora aponta convenções de IA generativa para um repositório GenAI separado, e essas convenções definem atributos de solicitação e resposta de modelo, como nome do provedor, modelo solicitado, modelo de resposta, tokens de entrada, tokens de saída, tokens de raciocínio e tokens de entrada em cache.

Use esses atributos GenAI onde eles couberem, mas não espalhe nomes de atributos brutos por todo o código do gateway. Envolva-os atrás de um pequeno mapeador de telemetria. Esse mapeador deve aceitar um registro de solicitação interno e produzir atributos de span padronizados.

record LlmTelemetryContext {
  organization_id
  team_id
  environment
  api_key_scope
  route_name
  route_policy_version
  workload_class
  provider_requested
  model_requested
  provider_selected
  model_response
  input_tokens
  output_tokens
  cached_input_tokens
  reasoning_tokens
  retry_count
  fallback_count
  normalized_error_class
}

O mapeador pode emitir atributos OpenTelemetry GenAI para os campos padrão e atributos de gateway privados para o contexto de negócios. Mantenha os atributos privados em um namespace controlado, por exemplo llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy e llm_gateway.workload_class.

Esse design oferece telemetria neutra em relação ao fornecedor e protege a base de código contra rotatividade. As convenções GenAI ainda estão evoluindo, portanto, o mapeador é onde os nomes podem mudar sem editar cada manipulador, módulo de nova tentativa, adaptador de streaming e componente de validação.

Separar metadados de conteúdo confidencial

Traços LLM são extraordinariamente sensíveis porque os dados de depuração mais úteis podem ser os mesmos dados que não devem ser amplamente retidos: prompts, documentos recuperados, parâmetros de ferramenta, conclusões, identificadores de usuário, identificadores de cliente e provedor bruto credenciais. A postura padrão deve ser a observabilidade dos metadados primeiro.

Os campos padrão recomendados incluem hash de prompt, ID do modelo de prompt, versão do prompt, ID do esquema, nome da ferramenta, coleção de recuperação, nome da rota, contagens de token, latência, classe de erro normalizada e status de validação. Esses campos respondem a muitas questões operacionais sem exportar conteúdo bruto.

A captura bruta de prompt e conclusão deve ser opcional, limitada no tempo, com acesso controlado e editada antes da exportação. Não ative-o globalmente como um recurso conveniente. Quando a captura de conteúdo for necessária para um incidente de produção, anexe um sinalizador de depuração a um conjunto restrito de solicitações, roteie esses rastreamentos para um back-end restrito e defina uma janela de retenção curta.

Hashing de identificadores não é anonimização automática. Se o espaço de entrada for pequeno ou previsível, os valores hash podem ser revertidos por adivinhação. Para identificadores confidenciais de clientes ou usuários, considere exclusão, IDs substitutos, agrupamento, truncamento ou hash de chave com controles de chave rígidos. Use hashes principalmente para correlação estável quando o risco for compreendido, não como uma resposta geral de privacidade.

Aplicar privacidade no coletor

A orientação do OpenTelemetry diz que dados confidenciais devem ser tratados antes da exportação. O Coletor pode remover, fazer hash, filtrar, redigir ou transformar atributos de telemetria usando processadores como atributos, filtro, redação e transformação. Isso torna o Coletor uma segunda linha de defesa depois da própria instrumentação do gateway.

Um pipeline prático do Coletor deve usar uma lista de permissões para atributos de baixo risco, excluir campos brutos de prompt e resposta por padrão, mascarar valores que correspondam a padrões bloqueados e rotear rastreamentos de maior sensibilidade separadamente quando a captura de conteúdo estiver explicitamente habilitada. O processador de atributos do OpenTelemetry Collector suporta ações como exclusão e hash. O processador de redação foi projetado para excluir atributos que não estão em uma lista de permissões e mascarar valores que correspondam a padrões bloqueados.

Por exemplo, o gateway pode evitar a emissão de conteúdo bruto por padrão, enquanto o Coletor ainda exclui atributos como llm.prompt.raw, llm.completion.raw, provider.api_key, authorization e cookie se eles aparecerem devido a um bug ou integração de biblioteca. Trate isso como um controle de defesa em profundidade, não como um motivo para emitir dados inseguros casualmente.

Repetições, substitutos e validação de instrumentos separadamente

Repetições e substitutos geralmente são invisíveis em API métricas agregadas. Essa invisibilidade causa dois problemas operacionais. Primeiro, a latência pode diminuir porque uma resposta bem-sucedida pode ocultar várias tentativas fracassadas.Em segundo lugar, o custo pode aumentar porque uma única solicitação de usuário pode criar várias chamadas de modelo upstream.

Cada período de tentativa do provedor deve incluir o número da tentativa, o motivo da nova tentativa, o provedor selecionado, o modelo selecionado, o orçamento de tempo limite, a latência, o uso do token quando disponível e o resultado. Se ocorrer um fallback, o período de fallback deverá identificar a política de rota original, o motivo do fallback e o modelo realmente usado para a resposta final.

A validação de saída estruturada deve ser seu próprio período ou evento. Capture o ID do esquema, a versão do esquema, o resultado da validação, a contagem de tentativas de reparo e o status final. Não armazene a saída inválida completa por padrão. Uma falha de validação é operacionalmente diferente de um erro de transporte de provedor, e os painéis não devem confundi-los.

Crie painéis em torno de perguntas, não de provedores

A observabilidade neutra do provedor deve responder diretamente a perguntas operacionais. Painéis úteis incluem latência p95 e p99 por modelo, provedor, equipe, ambiente e classe de carga de trabalho; utilização de tokens por equipe e rota; taxa de falha por classe de erro normalizada; tentar novamente a amplificação por política de rota; frequência de fallback por modelo solicitado; erros de janela de contexto por modelo de prompt; falhas de validação de saída estruturada por esquema; e amostras de exemplos de rastreamento para solicitações com falha, caras ou lentas.

Mantenha o faturamento e os relatórios de uso total fora dos rastreamentos de amostra. A amostragem final é útil para depuração, mas pode distorcer os totais. Totais de tokens, contagens de solicitações e livros de custos devem vir de contadores sem amostragem, livros de solicitações ou sistemas de reconciliação de cobrança. Os rastreamentos devem explicar por que ocorreu uma solicitação cara ou lenta; eles não devem ser a única fonte de verdade financeira.

Use a amostragem final para rastreamentos de alto valor

O processador de amostragem final do OpenTelemetry Collector pode tomar decisões de amostragem após a conclusão dos períodos, incluindo políticas baseadas em atributos e valores numéricos. Isso é útil para o tráfego LLM porque muitas vezes você sabe se um rastreamento é valioso somente após a conclusão da resposta.

Retenha rastreamentos para erros de provedor, falhas de validação, latência muito alta, uso de token extraordinariamente caro, falhas na janela de contexto, tentativas de fallback e solicitações marcadas de depuração manualmente. Amostra de tráfego bem-sucedido de rotina a uma taxa mais baixa. Isso mantém os rastreamentos com maior probabilidade de explicar incidentes enquanto controla o volume de armazenamento.

Um modelo de política razoável é simples: sempre mantenha erros, sempre mantenha solicitações acima de um limite de latência ou token, sempre mantenha rastreamentos marcados com depuração e faça amostras probabilisticamente de solicitações comuns bem-sucedidas. Revisite os limites à medida que o tráfego muda. Um limite útil durante a adoção inicial pode ser muito baixo quando o tráfego de produção aumentar.

Adicionar testes de contrato para telemetria

A telemetria deve ser testada como um contrato API porque painéis downstream, alertas, controles de custos e fluxos de trabalho de incidentes dependem dele. Adicione testes que executem solicitações de gateway representativas e afirmem que os intervalos e atributos necessários são emitidos.

Os testes devem verificar se uma solicitação bem-sucedida emite o intervalo de operação LLM lógico, um intervalo de tentativa do provedor, modelo solicitado, modelo de resposta, nome do provedor, contagens de token quando disponíveis, metadados de escopo de equipe ou chave, versão da política de rota e status final. Os testes de repetição devem declarar contagens de tentativas e motivos de repetição. Os testes de fallback devem confirmar tanto a tentativa fracassada quanto a tentativa final bem-sucedida do provedor. Os testes de validação devem declarar o ID do esquema, o status de validação e a contagem de tentativas de reparo.

Os testes de segurança são igualmente importantes. Afirme que chaves brutas de provedor, cabeçalhos de autorização, cookies, prompts brutos, conclusões brutas e identificadores de clientes não aprovados estão ausentes da telemetria exportada.Esses testes devem falhar quando um desenvolvedor adiciona um novo atributo de span sem classificá-lo.

Lista de verificação de implementação

• Contrato de atributos: Defina atributos obrigatórios, opcionais, restritos e proibidos.
• Hierarquia de span: Separe solicitações de entrada, operações LLM lógicas, tentativas de provedor, novas tentativas, fallbacks, chamadas de recuperação, chamadas de ferramenta, e validação.
• Mapeamento semântico: Use atributos OpenTelemetry GenAI onde eles se ajustam e atributos de gateway privado para propriedade e contexto de roteamento.
• Política de privacidade: Padrão para hashes, IDs de modelo, IDs de esquema, nomes de ferramentas, contagens de token, latência e classes de erro em vez de brutos content.
• Processadores coletores: Excluem campos proibidos, editam padrões bloqueados, listam atributos de baixo risco e encaminham rastreamentos confidenciais separadamente.
• Política de amostragem: Amostra traseira de rastreamentos de alto valor e mantém métricas agregadas sem amostragem.
• Painéis: Crie visualizações sobre latência, uso, falhas, novas tentativas, substitutos, validação e fatores de custo.
• Alertas: Alerta sobre classes de erro normalizadas, mudanças de latência p99, amplificação de novas tentativas, picos de substitutos, falhas de validação e token anomalias.
• Testes de contrato: Afirmar que a telemetria necessária está presente e a telemetria confidencial está ausente.

Compensações para decidir explicitamente

A instrumentação em nível de gateway fornece metadados consistentes rapidamente, mas pode perder o contexto específico do aplicativo, a menos que as equipes passem metadados de solicitação estruturados, como locatário, fluxo de trabalho, modelo de prompt e recurso nome. Torne esses metadados parte do contrato de solicitação de gateway em vez de depender de registros de formato livre.

A captura completa de conteúdo melhora a depuração e a avaliação, mas aumenta a privacidade, a segurança, a retenção e a carga de controle de acesso. Muitas equipes devem começar apenas com hashes, IDs de modelo, IDs de esquema e trechos editados.

As classes de erro neutras em termos de provedor tornam os painéis utilizáveis ​​em várias APIs de modelo, mas compactam detalhes específicos do provedor. Mantenha os códigos de erro brutos do provedor somente quando for seguro e restrinja o acesso a eles.

As convenções do OpenTelemetry GenAI reduzem o aprisionamento, mas as convenções continuarão a evoluir. Um mapeador interno oferece os benefícios da padronização sem permitir que nomes de atributos instáveis ​​vazem pela base de código.

Conclusão

A observabilidade LLM neutra em termos de provedor não é apenas o rastreamento adicionado às chamadas de modelo. É um contrato operacional na camada de gateway: intervalos consistentes, modelo normalizado e metadados de provedor, contexto de propriedade, uso de token, visibilidade de novas tentativas e fallback, controles de privacidade, regras de amostragem e testes que evitam o vazamento de dados confidenciais.

Comece com o gateway porque ele já vê as decisões mais importantes: quem fez a solicitação, qual política a encaminhou, qual provedor a atendeu, quanto custou em tokens, quanto tempo levou, se a lógica de recuperação foi executada e o que falhou. Depois que essa base estiver estável, as equipes de aplicativos poderão adicionar um contexto de fluxo de trabalho mais rico sem que cada equipe invente seu próprio sistema de observabilidade LLM.

Leitura relacionada

• telemetria de roteamento de fallback