Exportando Rastreamentos do TrueFoundry AI Gateway para o Honeycomb com OpenTelemetry

O TrueFoundry AI Gateway emite rastreamentos OpenTelemetry para cada solicitação que processa e os publica assincronamente via NATS para um exportador OTEL que os encaminha para qualquer backend compatível com OTLP via HTTP ou gRPC. Honeycomb é um desses backends. Ele aceita dados OTLP em https://api.honeycomb.io/v1/traces via HTTP com codificação protobuf e autentica usando o x-honeycomb-team cabeçalho. Assim que os rastreamentos chegam, o Honeycomb indexa cada atributo de span e os disponibiliza para consultas ad hoc sem a necessidade de qualquer esquema pré-declarado.

Esta publicação aborda como o gateway TrueFoundry gera e exporta rastreamentos, o que o Honeycomb faz com eles assim que chegam e como os dois sistemas se conectam no nível do protocolo.

Como o Gateway Gera e Exporta Rastreamentos

O TrueFoundry AI Gateway é construído sobre o framework Hono e executa como um pod de gateway sem estado em 1 vCPU e 1 GB de RAM, lidando com mais de 250 solicitações por segundo com aproximadamente 3 ms de latência adicionada. O gateway é compatível com OpenTelemetry e gera spans em todo o ciclo de vida de cada solicitação de entrada.

A árvore de spans abrange cinco estágios. O primeiro é o manipulador HTTP de entrada, que registra a chegada da solicitação juntamente com os metadados do cliente. O segundo é a autenticação, onde o gateway verifica o token JWT contra uma chave pública em cache baixada do provedor de identidade. Nenhuma chamada de autenticação externa é feita durante esta etapa. O terceiro é a resolução do modelo, onde o gateway resolve o identificador lógico do modelo para um endpoint de provedor físico usando uma tabela de roteamento em memória sincronizada do plano de controle via NATS. O quarto é a chamada do provedor de saída, onde o gateway traduz a solicitação do formato compatível com OpenAI para o formato do provedor de destino via um adaptador e a encaminha. O quinto é o tratamento de resposta de streaming, onde o gateway captura a contagem de tokens e os motivos de conclusão à medida que a resposta é transmitida de volta.

Os atributos de span seguem as gen_ai.* convenções semânticas juntamente com atributos específicos do TrueFoundry. O gen_ai.request.model atributo registra o identificador do modelo. Os gen_ai.usage.prompt_tokens e gen_ai.usage.completion_tokens atributos registram o consumo de tokens. Os tfy.input e tfy.output atributos carregam o texto completo do prompt e da resposta. O tfy.input_short_hand atributo carrega uma versão truncada para exibição. O tfy.span_type atributo identifica a categoria do span, como ChatCompletion ou MCPGateway.

Após a conclusão da solicitação, o gateway publica esses spans no NATS de forma assíncrona. Um exportador OTEL em segundo plano lê a partir desse caminho assíncrono e encaminha os spans para o endpoint externo configurado. Esse design significa que a exportação de rastreamento nunca adiciona latência ao caminho da solicitação. O gateway não falha uma solicitação se o endpoint OTEL externo estiver inacessível. O caminho de exportação é aditivo e não substitui o próprio armazenamento interno de rastreamento da TrueFoundry.

Para cargas de trabalho onde o conteúdo do prompt e da resposta não deve sair do ambiente, o gateway oferece um Excluir Dados da Solicitação alternador. Quando ativado, ele remove tfy.input e tfy.output e tfy.input_short_hand dos spans antes da exportação. Todos os outros atributos de span, incluindo contagens de tokens, latências e metadados do modelo, continuam a fluir.

O Gateway MCP segue o mesmo modelo de rastreamento. Cada invocação de ferramenta gera um span registrando o usuário chamador e o servidor MCP, o nome da ferramenta, o payload completo da requisição e da resposta, e a latência. Esses spans aparecem na mesma árvore de rastreamento que os spans de chamadas LLM, permitindo visibilidade de rastreamento de ponta a ponta em fluxos de trabalho agentivos.

O que o Honeycomb faz com os Dados de Rastreamento

O Honeycomb ingere dados OTLP e armazena cada span como uma linha com colunas arbitrárias. Não há um esquema fixo. Cada atributo que o TrueFoundry emite, seja gen_ai.usage.prompt_tokens ou tfy.span_type ou http.response.status_code torna-se uma coluna consultável no Honeycomb no momento em que o primeiro span que a contém chega.

A primitiva de consulta central no Honeycomb é a BubbleUp análise. Dado um conjunto de rastreamentos lentos ou falhos, o BubbleUp calcula quais valores de atributo estão estatisticamente super-representados nesse conjunto em comparação com a linha de base. Para o tráfego do gateway LLM, isso significa identificar se um pico de latência está correlacionado com um modelo específico, um usuário específico ou um servidor MCP específico, sem precisar escrever uma consulta manualmente.

O Honeycomb organiza os dados em conjuntos de dados. O gateway TrueFoundry define service.name como tfy-llm-gateway e o Honeycomb roteia os spans para um conjunto de dados com esse nome por padrão. Para rotear spans para um conjunto de dados diferente, o x-honeycomb-dataset o cabeçalho é adicionado à configuração do exportador juntamente com x-honeycomb-team. Vários conjuntos de dados podem ser usados para separar o tráfego de produção e de staging ou para separar os rastreamentos do gateway LLM dos rastreamentos do gateway MCP.

A Rastreamentos aba no Honeycomb apresenta a visualização em cascata de spans. Cada linha é um span. A hierarquia mostra relações pai-filho, assim, um span raiz MCPGateway: resources/list com spans aninhados MCP: resources/templates/list e um span de saída POST https://... corresponde diretamente ao que o gateway executou. As barras de duração permitem visualizar a distribuição de latência rapidamente. O contador Spans com erros isola os rastreamentos com falhas.

A Visão Geral aba agrega o Total de Spans, Total de Erros e Total de Exceções ao longo da janela de tempo selecionada e renderiza o Volume de Rastreamentos, Volume de Spans e Volume de Erros como gráficos de séries temporais. Esta visualização reflete a saúde do gateway num relance, sem a necessidade de construir um painel do zero.

Clicar em qualquer ID de Rastreamento expande a cascata completa de spans para aquele rastreamento. Cada span mostra seu nome de serviço, duração e quaisquer sinalizadores de erro. Spans filhos aninhados refletem a hierarquia de chamadas internas do gateway, tornando possível isolar qual estágio introduziu latência por solicitação.

A Superfície de Integração

O gateway TrueFoundry exporta rastreamentos via OTLP HTTP com codificação protobuf. O Honeycomb aceita este formato em dois endpoints regionais.

A autenticação usa um único cabeçalho. O x-honeycomb-team cabeçalho transporta a chave de API de ingestão do Honeycomb. A chave deve ter o Enviar Eventos escopo de permissão. Não há fluxo OAuth nem troca de token de portador. A chave é enviada como um valor de cabeçalho simples em cada solicitação de exportação.

x-honeycomb-team: <sua-chave-api-ingestao-honeycomb>

O roteamento de conjunto de dados é controlado por um segundo cabeçalho opcional. Quando x-honeycomb-dataset é omitido, o Honeycomb usa service.name dos atributos do recurso para determinar o conjunto de dados de destino. Quando é definido explicitamente, todos os spans nesse lote de exportação são gravados no conjunto de dados nomeado, independentemente de service.name.

x-honeycomb-dataset: tfy-llm-gateway-production

O gateway TrueFoundry não anexa automaticamente caminhos de sinal ao endpoint configurado. O caminho completo, incluindo /v1/traces deve estar presente no campo do endpoint. Isso difere do exportador OTLP HTTP do OpenTelemetry Collector, que anexa /v1/traces automaticamente com base no tipo de sinal do pipeline. No Collector, uma única URL base como https://api.honeycomb.io:443 é suficiente porque o Coletor resolve o caminho a partir da definição do pipeline. No TrueFoundry, o endpoint é usado literalmente.

A superfície de configuração no TrueFoundry mapeia diretamente para os campos que o Honeycomb exige.

O Atributos Adicionais de Recurso campo anexa pares chave-valor ao bloco de recurso de cada span exportado. Isso é útil para adicionar uma tag de ambiente de implantação ou um identificador de cluster que ainda não esteja presente nos atributos do span.

A Excluir Dados de Solicitação caixa de seleção remove tfy.input e tfy.output e tfy.input_short_hand antes que os spans saiam do gateway. O Honeycomb ainda receberá todos os atributos estruturais, incluindo contagens de tokens, latências, nomes de modelos e sinalizadores de erro.

Resumo da Arquitetura

Quando uma solicitação chega ao gateway do TrueFoundry, a árvore de spans completa é montada na memória durante o processamento da solicitação e publicada no NATS após a conclusão da resposta. O exportador OTEL assina este tópico NATS e agrupa os spans antes de enviá-los para https://api.honeycomb.io/v1/traces via HTTPS com o x-honeycomb-team cabeçalho presente. O Honeycomb escreve cada span como uma linha no tfy-llm-gateway dataset. Os spans ficam disponíveis para consulta em segundos após a chegada.

Nenhuma alteração no código da aplicação é necessária. Nenhum contêiner sidecar é implantado junto ao gateway. Nenhum SDK é incorporado ao cliente. A integração é uma superfície de configuração no gateway: uma URL de endpoint e um cabeçalho de autenticação. Clientes existentes que chamam o gateway através da API compatível com OpenAI continuam a funcionar sem modificação.

O princípio que torna esta integração confiável é o caminho de exportação assíncrono. A exportação de rastreamentos é desacoplada do ciclo de vida da requisição via NATS. Uma interrupção da API do Honeycomb ou uma partição de rede entre o gateway e o endpoint de ingestão do Honeycomb não afeta a disponibilidade da inferência. O gateway processa as requisições e publica os spans no NATS, independentemente de a exportação downstream ser bem-sucedida. Isso significa que o pipeline de observabilidade pode ser configurado, reconfigurado e reiniciado sem afetar o caminho de atendimento de requisições.

‍