Exportando Traces do Gateway de IA TrueFoundry para o OpenLIT via OTLP

O TrueFoundry AI Gateway gera spans OpenTelemetry para cada requisição LLM e os publica assincronamente via NATS. OpenLIT é uma plataforma de observabilidade auto-hospedada que aceita traces e métricas OTLP via HTTP ou gRPC e os armazena em ClickHouse. Conectar os dois exige configurar o exportador OTEL do gateway para apontar para o endpoint do coletor OpenLIT. Nenhuma alteração de código é necessária em qualquer aplicação.

Este post aborda o caminho de geração de traces OTEL dentro do TrueFoundry AI Gateway e o ClickHouse modelo de armazenamento que o OpenLIT utiliza e a superfície de configuração para interligar os dois sistemas. Não é um guia de configuração passo a passo. É uma explicação de como a integração funciona no nível da arquitetura.

Como o TrueFoundry AI Gateway Gera e Exporta Traces

O TrueFoundry AI Gateway é construído sobre o Hono framework e executa como um pod sem estado. Um único pod com 1 vCPU e 1 GB de RAM lida com mais de 250 requisições por segundo com aproximadamente 3 ms de latência adicionada. Esse perfil de desempenho só é possível porque o gateway não realiza chamadas externas no caminho da requisição. A autenticação é feita contra chaves públicas em cache. As verificações de autorização são feitas contra um mapa em memória de usuários para modelos. A lógica de roteamento de modelos é executada inteiramente em memória.

A geração de traces OTEL segue este mesmo princípio. Quando uma requisição é concluída, o gateway publica os dados do span assincronamente para o NATS. O exportador OTEL lê a partir deste caminho assíncrono e encaminha o span para o endpoint externo configurado. O exportador nunca toca no caminho da requisição. Um backend OTEL lento ou inacessível nunca atrasa uma requisição.

Os spans que o gateway emite carregam um conjunto específico de atributos. O atributo tfy.input contém o corpo completo da requisição enviada ao LLM. O tfy.output atributo contém a resposta completa. O tfy.input_short_hand atributo contém um resumo condensado do input, incluindo sinalizadores booleanos para indicar se a requisição continha arquivos, imagens ou áudio. O tfy.span_type atributo identifica o tipo de operação, como ChatCompletion ou AgentResponse. Convenções semânticas padrão gen_ai.* também estão incluídas, abrangendo contagens de tokens, identificadores de modelo e motivos de conclusão.

O gateway também expõe um Excluir Dados da Requisição alternador. Quando ativado, o exportador remove tfy.input e tfy.output e tfy.input_short_hand dos spans antes de encaminhá-los. Isso é relevante para equipes que precisam rotear telemetria para uma plataforma externa sem enviar o conteúdo do prompt ou da resposta para fora de sua infraestrutura.

A exportação é aditiva. Ativar um destino OTEL externo não substitui nem interrompe o próprio armazenamento interno de rastreamentos da TrueFoundry. Ambos os caminhos recebem os mesmos spans.

O que o OpenLIT faz com os rastreamentos

OpenLIT é uma plataforma de observabilidade nativa do OpenTelemetry. Não requer um sidecar, um wrapper de SDK ou qualquer modificação na camada de aplicação. Ele aceita spans através do protocolo OTLP padrão na porta 4318 para HTTP e na porta 4317 para gRPC e os grava no ClickHouse.

ClickHouse armazena rastreamentos no otel_traces tabela e métricas na otel_metrics tabela. O esquema segue diretamente o modelo de dados do OpenTelemetry. Cada span é armazenado como uma linha com um SpanAttributes coluna do tipo Map(String, String) que contém todos os atributos chave-valor emitidos pelo gateway. A consulta de um atributo específico utiliza a sintaxe de acesso de mapa:

SELECT
    Timestamp,
    SpanAttributes['tfy.span_type'] AS span_type,
    SpanAttributes['tfy.data_routing.destination'] AS destination,
    StatusCode,
    Duration / 1e9 AS duration_sec
FROM openlit.otel_traces
WHERE SpanAttributes['tfy.span_type'] = 'ChatCompletion'
ORDER BY Timestamp DESC
LIMIT 20;

O painel do OpenLIT lê dessas tabelas ClickHouse e renderiza linhas do tempo de requisições, distribuições de latência e taxas de erro. Como a camada de armazenamento é uma instância padrão do ClickHouse, as equipes também podem executar SQL arbitrário diretamente nela para relatórios personalizados ou pipelines de alerta.

OpenLIT inclui seu próprio OTel Collector juntamente com o painel e o banco de dados. O coletor é o ponto de entrada para todos os spans e métricas recebidos. Ele recebe dados via OTLP e os grava no ClickHouse usando o exportador ClickHouse. A configuração do coletor define pipelines separados para traces, métricas e logs, cada um suportado por um processador em lote e um limitador de memória.

Os três componentes são entregues como um único Helm chart. O coletor e o painel são executados dentro do mesmo pod Kubernetes. O ClickHouse é executado como um StatefulSet separado com uma reivindicação de volume persistente. Um contêiner de inicialização no pod OpenLIT aguarda o ClickHouse responder na porta 8123 antes de iniciar os processos do coletor e do painel. Essa sequência significa que o lançamento do Helm é autocontido e a ordem de implantação é tratada automaticamente.

Uma vez implantado, o TrueFoundry mostra ambos os pods no estado Running: openlit-0 executando o painel e o OTel Collector e openlit-db-0 executando o ClickHouse.

O painel do OpenLIT é acessível na URL do domínio do cluster exposto. A página de login lista as principais capacidades da plataforma, incluindo rastreamento de ponta a ponta, análise de custos e tokens e avaliação LLM-as-a-Judge.

A Superfície de Integração

O TrueFoundry AI Gateway conecta-se ao OpenLIT através de duas configurações de exportador OTEL: uma para rastreamentos e outra para métricas. Ambas usam codificação HTTP e Proto. Não são necessários cabeçalhos de autenticação porque o endpoint do coletor OpenLIT está dentro do mesmo cluster Kubernetes que o gateway. O tráfego entre os dois permanece na rede interna do cluster.

Configuração do Exportador de Rastreamentos OTEL

Configuração do Exportador de Métricas OTEL

‍

O openlit serviço Kubernetes expõe três portas. A porta 3000 serve o painel. A porta 4317 aceita OTLP via gRPC. A porta 4318 aceita OTLP via HTTP. Todas as três estão no mesmo nome de serviço e entrada DNS. O caminho de exportação assíncrono baseado em NATS no gateway significa que, mesmo que o coletor OpenLIT esteja temporariamente indisponível, o gateway continua processando as solicitações normalmente. Os spans que não podem ser entregues são descartados no nível do exportador e registrados sem apresentar erros ao chamador.

O gráfico Helm do OpenLIT está hospedado em https://openlit.github.io/helm/ sob o nome do gráfico openlit. O gráfico aceita um bloco de valores que define os parâmetros de conexão do ClickHouse para o painel e o coletor, e a configuração de persistência para o banco de dados. O painel conecta-se ao ClickHouse usando a INIT_DB_HOST variável de ambiente que deve apontar para o serviço ClickHouse StatefulSet usando seu nome DNS interno openlit-db.NAMESPACE.svc.cluster.local.

A configuração do coletor é armazenada em um ConfigMap chamado openlit-otel-config. Ele define três pipelines. O pipeline de rastreamentos passa por um limitador de memória configurado para 1500 MiB com um limite de pico de 512 MiB e um processador em lote antes de ser encaminhado para o exportador ClickHouse. O pipeline de métricas segue a mesma cadeia de processadores. O pipeline de logs omite o limitador de memória e usa apenas o processador em lote. Todos os três pipelines gravam na mesma instância do ClickHouse usando o protocolo TCP nativo na porta 9000.

O VirtualService para o painel usa o gateway Istio do TrueFoundry istio-system/tfy-wildcard e encaminha o tráfego do domínio do cluster para o serviço interno openlit na porta 3000. Este é o único componente que requer exposição externa. Os endpoints do coletor permanecem internos.

Referência DNS de Serviço Interno

Resumo da Arquitetura

Uma requisição entra no TrueFoundry AI Gateway e é processada inteiramente em memória contra o estado de autenticação em cache e a configuração de roteamento. O gateway encaminha a requisição para o provedor LLM e transmite a resposta de volta ao cliente. Após a conclusão da resposta, o gateway publica um span no NATS contendo os atributos completos da requisição e da resposta, contagens de tokens e latência. O exportador OTEL coleta o span do NATS assincronamente e o encaminha via OTLP/HTTP para o coletor OpenLIT executando na porta 4318 dentro do cluster. O coletor grava o span no ClickHouse. O painel OpenLIT lê do ClickHouse e disponibiliza o rastreamento para inspeção.

A aba Métricas exibe dados agregados de séries temporais da otel_metrics tabela. O volume de requisições do Gateway e as tendências de latência estão disponíveis em janelas de tempo selecionáveis, de 24 horas a 3 meses.

Nenhum sidecar é necessário. Nenhuma alteração no SDK é necessária. Nenhum código de instrumentação é adicionado a qualquer aplicação. A única alteração de configuração é definir os endpoints do exportador OTEL nas TrueFoundry AI Gateway configurações. O gateway já gera e publica os spans. A configuração do exportador determina para onde eles vão.

O princípio arquitetônico que faz esta integração funcionar é a separação entre o caminho da requisição e o caminho da telemetria. Como os spans são publicados no NATS após a conclusão da resposta, a confiabilidade do backend de observabilidade não tem efeito na latência ou disponibilidade do gateway. OpenLIT recebe o que o gateway publica. Se o OpenLIT estiver indisponível, o gateway continua a operar e retoma a exportação quando a conectividade é restaurada.

‍