Exporte traces do TrueFoundry AI Gateway para o Opik com OpenTelemetry

Quando uma chamada de LLM está lenta, cara ou incorreta, você quer ver a solicitação completa: o prompt, o modelo, os tokens, as chamadas de ferramenta e a latência. Se seus rastreamentos ficam em uma ferramenta e sua avaliação em outra, essa visão fica dividida. Este guia mostra como enviar rastreamentos do TrueFoundry AI Gateway para o Comet Opik via OpenTelemetry, para que cada solicitação processada pelo gateway apareça no Opik como um rastreamento completo, sem alterações no código da sua aplicação.

Por que exportar rastreamentos do gateway para o Opik

OTrueFoundry AI Gateway O gateway já atua à frente de cada chamada de modelo, roteando mais de 1.000 LLMs através de uma única API compatível com OpenAI, com aproximadamente 3-4 ms de sobrecarga e mais de 350 RPS em uma única vCPU. Por estar no caminho de cada solicitação, ele é o local natural para emitir rastreamentos. O gateway é compatível com OpenTelemetry nativamente, portanto, exportar para outro backend é uma questão de configuração, não de engenharia.

O Opik é uma plataforma de observabilidade e avaliação de LLM criada pela Comet. Ele ingere spans de OpenTelemetry e os renderiza como rastreamentos de LLM, com entradas, saídas, uso de tokens, latência e custo por chamada, permitindo que você execute avaliações sobre esse tráfego. Apontar o gateway para o Opik significa que suas solicitações de produção se tornam rastreamentos que você pode inspecionar e pontuar na mesma ferramenta. Os rastreamentos continuam sendo enviados para o TrueFoundry por padrão; a exportação os espelha para o Opik.

Veja como configurar.

Pré-requisitos

• Uma conta TrueFoundry com o AI Gateway configurado e tráfego fluindo através dele.
• Uma conta Comet para o Opik (nuvem, auto-hospedada ou enterprise), com sua chave de API, nome do workspace e um nome de projeto de destino.
• Acesso às configurações do AI Gateway no painel do TrueFoundry.

Guia de integração passo a passo

O Opik ingere apenas rastreamentos e aceita OTLP via HTTP, portanto, a configuração consiste em um exportador com três cabeçalhos. Não há código para escrever.

Passo 1: Obtenha sua chave e workspace do Opik

No Opik, abra as configurações da sua conta e copie sua chave de API. Anote o nome do seu workspace no seletor de workspace e decida o nome do projeto onde deseja que os rastreamentos sejam armazenados. O projeto é criado na primeira ingestão, caso ainda não exista.

Passo 2: Configure o exportador de rastreamentos OTEL

No painel, vá para AI Gateway, depois Configurações e, em seguida, Configuração OTEL. Habilite o exportador de rastreamentos e preencha o endpoint e os cabeçalhos do Opik.

Para exportar rastreamentos para o Opik, configure seu exportador OpenTelemetry para usar o protocolo HTTP com codificação Protobuf (Proto), apontando para o endpoint https://www.comet.com/opik/api/v1/private/otel/v1/traces. A autenticação e o roteamento são tratados por meio de três cabeçalhos de solicitação: o Authorization cabeçalho deve conter sua chave de API do Opik como um valor bruto; observe que não há Bearer deve ser incluído, enquanto o Comet-Workspace e projectName devem ser definidos com o nome do seu workspace e o nome do projeto, respectivamente. Esses cabeçalhos garantem que os rastreamentos recebidos sejam autenticados e registrados no workspace e projeto corretos dentro do Opik.

Deixe o exportador de métricas desativado. O Opik ingere rastreamentos, não métricas OTLP. Salve, e as novas solicitações começarão a ser espelhadas no Opik.

Passo 3: Verifique se os rastreamentos chegaram

Envie uma solicitação pelo gateway e, em seguida, abra a visualização de Rastreamentos (Traces) no Opik para o seu projeto. Você deverá ver os spans do gateway com entradas, saídas, contagem de tokens e latência preenchidos. Uma chamada de modelo aparece como um rastreamento de chat-completion; execuções de agentes mostram a árvore aninhada de spans de modelos e chamadas de ferramentas.

O que você desbloqueia: observabilidade completa de LLM no Opik

Rastreamento distribuído em toda a solicitação

Uma execução de agente aparece como um único rastreamento com as chamadas de modelo e de ferramentas aninhadas abaixo, para que você possa acompanhar uma solicitação de várias etapas de ponta a ponta, em vez de ler linhas de log desconexas.

Avaliação em tráfego real de produção

Como suas solicitações em tempo real agora são rastreadas no Opik, você pode criar conjuntos de dados a partir delas e executar avaliações no tráfego que você realmente atende, em vez de usar uma amostra sintética.

Visibilidade de custo e latência

Cada rastreamento carrega o uso de tokens, latência e custo, para que você possa encontrar as chamadas lentas ou caras sem precisar reunir dados de ferramentas separadas.

Nenhuma alteração no código da aplicação

A exportação é configurada uma única vez no gateway. Todo serviço que passa pelo gateway é rastreado, e você não precisa adicionar um SDK ou editar qualquer aplicação para conseguir isso.

Perguntas frequentes

P: O que é observabilidade de LLM por meio de um gateway de IA? R: Significa que cada chamada de modelo feita por suas aplicações é rastreada no gateway, com o prompt, a resposta, os tokens, a latência e o custo capturados para cada solicitação. No TrueFoundry AI Gateway, isso é baseado em OpenTelemetry, portanto, você pode exportar esses rastreamentos para um backend como o Comet Opik sem precisar instrumentar seu código.

P: Exportar para o Opik impede que os rastreamentos sejam enviados para o TrueFoundry? R: Não. Os rastreamentos continuam sendo armazenados no TrueFoundry por padrão. A exportação OTEL os espelha para o Opik adicionalmente, para que você mantenha ambos.

P: Posso exportar métricas para o Opik além de traces? R: Não. O Opik ingere apenas traces, portanto, você deve configurar o exportador de traces e manter as métricas desativadas. Para métricas de gateway, você deve usar um backend de métricas como Grafana, Datadog ou Prometheus.

P: Quantos LLMs a TrueFoundry suporta? R: Mais de 1.000 LLMs por meio de uma única API compatível com OpenAI. Você alterna os modelos alterando o nome do modelo na solicitação, mantendo a mesma URL e credenciais.

P: Ele se integra à minha stack de observabilidade existente? R: Sim. O gateway é compatível com OpenTelemetry e se conecta ao Grafana, Datadog, Prometheus ou, como neste caso, ao Comet Opik, rastreando cada solicitação desde o prompt até a execução da ferramenta e do modelo.

Leituras relacionadas

• O que é um gateway de LLM? - a arquitetura por trás desta integração
• Solução de Rastreamento de Custos de LLM - aprofundando na visibilidade de gastos
• Observabilidade no AI Gateway - como o rastreamento em nível de gateway se encaixa no cenário mais amplo de observabilidade

Conclusão

A observabilidade não deve exigir a re-instrumentação de cada serviço. Com o TrueFoundry AI Gateway exportando traces de OpenTelemetry para o Comet Opik, cada solicitação que o gateway processa se torna um trace completo que você pode inspecionar e avaliar, configurado uma vez e aplicado em todos os lugares. Comece no TrueFoundry AI Gateway.