Exporter les traces de la passerelle IA de TrueFoundry vers Opik avec OpenTelemetry

Lorsqu'un appel LLM est lent, coûteux ou erroné, vous souhaitez visualiser l'intégralité de la requête : le prompt, le modèle, les jetons, les appels d'outils et la latence. Si vos traces sont stockées dans un outil et vos évaluations dans un autre, cette vision est fragmentée. Ce guide explique comment envoyer les traces de TrueFoundry AI Gateway vers Comet Opik via OpenTelemetry, afin que chaque requête traitée par la passerelle apparaisse dans Opik sous forme de trace complète, sans aucune modification de votre code applicatif.

Pourquoi exporter les traces de la passerelle vers Opik

La TrueFoundry AI Gateway se place déjà en amont de chaque appel de modèle, acheminant plus de 1 000 LLM via une API compatible OpenAI avec une surcharge d'environ 3 à 4 ms et plus de 350 RPS sur un seul vCPU. Étant sur le chemin de chaque requête, c'est l'endroit idéal pour émettre des traces. La passerelle est nativement compatible avec OpenTelemetry, l'exportation vers un autre backend relève donc de la configuration et non du développement.

Opik est une plateforme d'observabilité et d'évaluation LLM créée par Comet. Elle ingère les spans OpenTelemetry et les restitue sous forme de traces LLM, incluant les entrées, sorties, consommation de jetons, latence et coût par appel, tout en vous permettant d'exécuter des évaluations sur ce trafic. Pointer la passerelle vers Opik signifie que vos requêtes de production deviennent des traces que vous pouvez inspecter et noter au sein d'un même outil. Les traces sont toujours enregistrées dans TrueFoundry par défaut ; l'exportation les duplique vers Opik.

Voici comment procéder à la configuration.

Prérequis

• Un compte TrueFoundry avec AI Gateway configuré et du trafic actif.
• Un compte Comet pour Opik (cloud, auto-hébergé ou entreprise), avec votre clé API, le nom de votre espace de travail et le nom du projet cible.
• Accès aux paramètres de l'AI Gateway dans le tableau de bord TrueFoundry.

Guide d'intégration étape par étape

Opik ingère uniquement les traces et accepte le protocole OTLP via HTTP ; la configuration se résume donc à un exportateur et trois en-têtes. Aucun code n'est à écrire.

Étape 1 : Obtenez votre clé Opik et votre espace de travail

Dans Opik, ouvrez les paramètres de votre compte et copiez votre clé API. Notez le nom de votre espace de travail depuis le sélecteur d'espace, et choisissez le nom du projet dans lequel vous souhaitez que les traces soient enregistrées. Le projet est créé lors de la première ingestion s'il n'existe pas encore.

Étape 2 : Configurez l'exportateur de traces OTEL

Dans le tableau de bord, accédez à AI Gateway, puis Settings, et enfin OTEL Config. Activez l'exportateur de traces et renseignez l'endpoint Opik ainsi que les en-têtes.

Pour exporter les traces vers Opik, configurez votre exportateur OpenTelemetry pour utiliser le protocole HTTP avec un encodage Protobuf (Proto), en pointant vers l'endpoint https://www.comet.com/opik/api/v1/private/otel/v1/traces. L'authentification et le routage sont gérés via trois en-têtes de requête : le Autorisation L'en-tête doit contenir votre clé API Opik en tant que valeur brute ; notez qu'aucun Bearer préfixe ne doit être inclus, tandis que les en-têtes Comet-Workspace et projectName doivent être définis respectivement sur le nom de votre espace de travail et le nom de votre projet. Ces en-têtes garantissent que les traces entrantes sont authentifiées et enregistrées dans l'espace de travail et le projet corrects au sein d'Opik.

Laissez l'exportateur de métriques désactivé. Opik ingère des traces, pas des métriques OTLP. Enregistrez, et les nouvelles requêtes commenceront à être répliquées vers Opik.

Étape 3 : Vérifiez que les traces sont bien reçues

Envoyez une requête via la passerelle, puis ouvrez la vue Traces dans Opik pour votre projet. Vous devriez voir les spans provenant de la passerelle avec les entrées, les sorties, le nombre de jetons et la latence renseignés. Un appel de modèle apparaît sous forme de trace de chat-completion ; les exécutions d'agents affichent l'arborescence imbriquée des spans de modèles et d'appels d'outils.

Ce que vous débloquez : une observabilité LLM complète dans Opik

Traçage distribué sur l'ensemble de la requête

Une exécution d'agent apparaît comme une trace unique avec les appels de modèles et d'outils imbriqués en dessous, vous permettant de suivre une requête en plusieurs étapes de bout en bout plutôt que de lire des lignes de logs déconnectées.

Évaluation sur le trafic de production réel

Comme vos requêtes en direct sont désormais tracées dans Opik, vous pouvez créer des jeux de données à partir de celles-ci et exécuter des évaluations sur le trafic que vous servez réellement, plutôt que sur un échantillon synthétique.

Visibilité sur les coûts et la latence

Chaque trace contient l'utilisation des jetons, la latence et le coût, ce qui vous permet d'identifier les appels lents ou coûteux sans avoir à compiler des données provenant d'outils distincts.

Aucune modification du code applicatif

L'export est configuré une seule fois dans la passerelle. Chaque service passant par la passerelle est tracé, sans que vous ayez à ajouter de SDK ou à modifier la moindre application.

FAQ

Q : Qu'est-ce que l'observabilité LLM via une passerelle IA ? R : Cela signifie que chaque appel de modèle effectué par vos applications est tracé au niveau de la passerelle, avec la capture du prompt, de la réponse, des jetons, de la latence et du coût pour chaque requête. Sur la passerelle IA de TrueFoundry, ce processus est basé sur OpenTelemetry, ce qui vous permet d'exporter ces traces vers un backend comme Comet Opik sans avoir à instrumenter votre code.

Q : L'exportation vers Opik empêche-t-elle les traces d'être envoyées à TrueFoundry ? R : Non. Les traces sont toujours stockées par défaut dans TrueFoundry. L'exportation OTEL les duplique vers Opik, vous conservez donc les deux.

Q : Puis-je exporter des métriques vers Opik en plus des traces ? R : Non. Opik n'ingère que les traces ; vous devez donc configurer l'exportateur de traces et désactiver les métriques. Pour les métriques de la passerelle, vous devriez utiliser un backend dédié tel que Grafana, Datadog ou Prometheus.

Q : Combien de LLM TrueFoundry prend-il en charge ? R : Plus de 1 000 LLM via une API unique compatible avec OpenAI. Vous changez de modèle en modifiant simplement son nom dans la requête, tout en conservant la même URL et les mêmes identifiants.

Q : Est-ce que cela s'intègre à ma pile d'observabilité existante ? R : Oui. La passerelle est compatible avec OpenTelemetry et s'intègre à Grafana, Datadog, Prometheus ou, comme ici, Comet Opik, en traçant chaque requête depuis le prompt jusqu'à l'exécution de l'outil et du modèle.

Lectures complémentaires

• Qu'est-ce qu'une passerelle LLM ? - l'architecture derrière cette intégration
• Solution de suivi des coûts LLM - approfondir la visibilité sur les dépenses
• Observabilité dans la passerelle IA - comment le traçage au niveau de la passerelle s'inscrit dans une stratégie d'observabilité plus large

Conclusion

L'observabilité ne devrait pas nécessiter de ré-instrumenter chaque service. Grâce à la passerelle IA de TrueFoundry qui exporte les traces OpenTelemetry vers Comet Opik, chaque requête traitée par la passerelle devient une trace complète que vous pouvez inspecter et évaluer, configurée une seule fois et appliquée partout. Commencez avec la passerelle IA de TrueFoundry.