Exportando Traces do Gateway LLM para o Traceloop com OpenTelemetry

TrueFoundry AI Gateway exporta rastreamentos OpenTelemetry para Traceloop via OTLP/HTTP utilizando o https://api.traceloop.com/v1/traces endpoint e um token Bearer no Authorization cabeçalho. Cada requisição LLM que passa pelo gateway produz uma árvore de spans que aparece no painel do Traceloop sem quaisquer alterações no código da aplicação ou na topologia de implantação.

Esta publicação aborda o caminho de geração de rastreamentos dentro do TrueFoundry AI Gateway e como Traceloop ingere e exibe esses dados. Também descreve as opções de configuração e os controles de privacidade de dados disponíveis no nível do gateway.

Como o Gateway Gera Rastreamentos

O TrueFoundry AI Gateway é construído sobre o framework Hono e executa como um pod sem estado, processando mais de 250 requisições por segundo em uma única vCPU com aproximadamente 3 ms de latência adicionada por requisição. O gateway opera em uma arquitetura dividida onde um plano de controle gerencia a configuração e um ou mais pods de gateway processam o tráfego de inferência.

Quando uma requisição chega, o gateway executa a seguinte sequência no caminho crítico:

1. Token JWT validado contra chaves públicas armazenadas em cache na memória (baixado uma vez do IdP e atualizado via NATS)
2. Autorização verificada contra um mapa de usuário para modelo em memória mantido atualizado por NATS pub/sub
3. Identificador do modelo resolvido para um endpoint de provedor físico através da lógica de roteamento do Modelo Virtual executando em memória
4. Requisição traduzida do formato compatível com OpenAI para o formato do provedor de destino através de uma camada adaptadora
5. Requisição encaminhada ao provedor e a resposta transmitida de volta ao cliente

Nenhuma dessas etapas faz chamadas externas, exceto a própria chamada ao provedor. O controle de taxa executa o algoritmo Sliding Window Token Bucket contra o estado em memória. A avaliação de guardrail (quando configurada) é executada concorrentemente com a chamada do modelo para verificações de entrada e sequencialmente para verificações de saída.

Após a conclusão da requisição, o gateway publica a árvore de spans assincronamente para o NATS. O exportador OTEL lê a partir deste caminho assíncrono e encaminha os spans para o endpoint externo configurado. Como o caminho de exportação é totalmente desacoplado do caminho da requisição, um backend OTEL lento ou inacessível nunca adiciona latência ao cliente e nunca causa falha em uma requisição. Se Traceloop estiver inacessível, os spans são descartados no exportador e registrados internamente. O armazenamento interno de rastreamento da TrueFoundry não é afetado porque a exportação é aditiva.

O gateway gera spans em cinco estágios: o manipulador HTTP de entrada, autenticação, resolução do modelo, a chamada de provedor de saída e a montagem da resposta de streaming. Cada span carrega um conjunto consistente de atributos.

Os gen_ai.* atributos seguem as Convenções Semânticas OpenTelemetry para Sistemas de IA Generativa. Isso significa que os dados de rastreamento que chegam ao Traceloop são estruturalmente idênticos ao que qualquer aplicação instrumentada com OpenLLMetry produziria.

‍

O que o Traceloop Faz com os Dados

Traceloop é uma plataforma de observabilidade LLM construída sobre OpenLLMetry, que é sua camada de instrumentação OpenTelemetry de código aberto. O backend do Traceloop aceita dados de rastreamento OTLP/HTTP e os indexa para o painel do Traceloop. A plataforma é nativa de rastreamento. Métricas como uso de tokens, latência e custo são calculadas a partir de atributos de span, em vez de um fluxo de métricas OTLP separado. É por isso que configurar apenas o Traces Exporter no TrueFoundry é suficiente — não há /v1/metrics endpoint na superfície de ingestão do Traceloop.

O Traceloop organiza os dados em torno de três abstrações principais. Os rastreamentos são a unidade de nível superior e correspondem diretamente a uma requisição LLM ou a um fluxo de trabalho de agente. Spans dentro de um rastreamento representam operações individuais (uma chamada LLM, uma invocação de ferramenta e uma etapa de recuperação). Ambientes mapeiam para estágios de implantação e cada ambiente tem sua própria chave de API, permitindo que os rastreamentos de Desenvolvimento, Staging e Produção permaneçam isolados no painel.

O Traceloop painel exibe o uso de tokens ao longo do tempo, distribuições de latência, taxas de erro e detalhamentos de modelo diretamente de IA generativa.* atributos de span. Como o TrueFoundry preenche esses atributos em cada span, o painel do Traceloop é totalmente preenchido sem qualquer instrumentação de SDK na camada de aplicação.

‍
‍

Traceloop também suporta versionamento de prompts e pipelines de teste de regressão, mas esses recursos operam no nível do SDK da aplicação e estão fora do escopo desta integração. A integração em nível de gateway cobre toda a superfície de observabilidade: cada requisição que passa pelo TrueFoundry produz um rastreamento no Traceloop, independentemente do provedor ou modelo de LLM que é chamado.

A Superfície de Integração

A conexão entre TrueFoundry e Traceloop é um único POST OTLP/HTTP para https://api.traceloop.com/v1/traces transportando lotes de span codificados em Proto. A autenticação é um token Bearer no Authorization cabeçalho. O token é uma chave de API do Traceloop com escopo para um ambiente específico.

O TrueFoundry expõe esta configuração em Gateway de IA → Controles → Configurações → Configuração OTEL. A seção Otel Traces Exporter aceita os seguintes campos.

O endpoint deve incluir o caminho completo /v1/traces caminho. O exportador do TrueFoundry não anexa automaticamente os caminhos de sinal. Isso difere do OTel Collector otlphttp exporter que anexa o caminho automaticamente a partir da URL base. Ambos resolvem para o mesmo destino.

As chaves de API do Traceloop são geradas por ambiente a partir da página Ambientes no painel do Traceloop. Uma chave é exibida apenas uma vez no momento da criação. O valor da chave é passado no cabeçalho como Bearer <key> incluindo o Bearer prefixo como uma string literal.

Controles de Privacidade de Dados

O gateway oferece um Excluir Dados de Requisição alternador na seção Configuração OTEL. Quando ativado, o exportador remove tfy.input e tfy.output e tfy.input_short_hand de cada span antes de encaminhar para o Traceloop. Os atributos de span restantes (contagens de tokens, nomes de modelos, latência e metadados de roteamento) não são afetados. Este alternador é apropriado quando prompts ou conclusões contêm PII do usuário ou conteúdo proprietário que não deve sair do limite do cluster.

O campo Atributos de Recurso Adicionais permite anexar pares chave-valor personalizados a cada span exportado. Isso é útil para marcação de ambiente, atribuição de centro de custo e filtragem multi-inquilino dentro de um único ambiente Traceloop.

‍

Resumo da Arquitetura

Cada requisição LLM através do TrueFoundry AI Gateway produz uma árvore de spans que abrange autenticação e roteamento, a chamada do provedor e a resposta. Após a conclusão da requisição, o gateway publica esta árvore de spans no NATS de forma assíncrona. O exportador OTEL lê do NATS e envia lotes codificados em Proto para https://api.traceloop.com/v1/traces com um token Bearer. O Traceloop indexa os spans e exibe o uso de tokens, latência e detalhamentos do modelo em seu painel a partir dos gen_ai.atributos em cada span.

Nenhum sidecar é necessário. Nenhuma alteração no código da aplicação é necessária. Nenhum SDK OpenLLMetry precisa ser adicionado aos serviços que chamam o gateway. A integração opera inteiramente na camada do gateway e cobre 100% do tráfego que passa por ele, independentemente do estado de instrumentação da aplicação chamadora.

A propriedade arquitetural que torna isso elegante é a publicação assíncrona no NATS. Como a exportação de spans é desacoplada do caminho da requisição, a integração adiciona latência zero às chamadas de inferência e não introduz dependência de disponibilidade no Traceloop. O gateway processa as requisições com total rendimento, independentemente de o Traceloop estar acessível ou não.

‍