Exportation des traces de la passerelle LLM vers Traceloop avec OpenTelemetry

TrueFoundry AI Gateway exporte les traces OpenTelemetry vers Traceloop via OTLP/HTTP en utilisant le https://api.traceloop.com/v1/traces point de terminaison et un jeton Bearer dans l' Authorization en-tête. Chaque requête LLM qui transite par la passerelle produit un arbre de spans qui apparaît dans le tableau de bord Traceloop sans aucune modification du code de l'application ou de la topologie de déploiement.

Cet article couvre le chemin de génération des traces au sein de la TrueFoundry AI Gateway et comment Traceloop ingère et présente ces données. Il décrit également les options de configuration et les contrôles de confidentialité des données disponibles au niveau de la passerelle.

Comment la passerelle génère des traces

La TrueFoundry AI Gateway est construite sur le framework Hono et fonctionne comme un pod sans état, gérant plus de 250 requêtes par seconde sur un seul vCPU avec environ 3 ms de latence ajoutée par requête. La passerelle fonctionne selon une architecture divisée où un plan de contrôle gère la configuration et un ou plusieurs pods de passerelle traitent le trafic d'inférence.

Lorsqu'une requête arrive, la passerelle exécute la séquence suivante dans le chemin critique :

1. Jeton JWT validé par rapport aux clés publiques mises en cache en mémoire (téléchargées une fois depuis l'IdP et rafraîchies via NATS)
2. Autorisation vérifiée par rapport à une carte utilisateur-modèle en mémoire maintenue à jour par NATS pub/sub
3. L'identifiant du modèle est résolu en un point de terminaison de fournisseur physique via la logique de routage du modèle virtuel exécutée en mémoire.
4. La requête est traduite du format compatible OpenAI vers le format du fournisseur cible via une couche d'adaptation.
5. La requête est transmise au fournisseur et la réponse est diffusée en continu au client.

Aucune de ces étapes n'effectue d'appels externes, à l'exception de l'appel au fournisseur lui-même. La limitation de débit exécute l'algorithme du "Sliding Window Token Bucket" sur l'état en mémoire. L'évaluation des garde-fous (lorsqu'elle est configurée) s'exécute concurremment à l'appel du modèle pour les vérifications d'entrée et séquentiellement pour les vérifications de sortie.

Une fois la requête terminée, la passerelle publie l'arbre de traces de manière asynchrone vers NATS. L'exportateur OTEL lit à partir de ce chemin asynchrone et transmet les traces au point de terminaison externe configuré. Étant donné que le chemin d'exportation est entièrement découplé du chemin de requête, un backend OTEL lent ou inaccessible n'ajoute jamais de latence au client et ne provoque jamais l'échec d'une requête. Si Traceloop est inaccessible, les traces sont abandonnées au niveau de l'exportateur et enregistrées en interne. Le stockage interne des traces de TrueFoundry n'est pas affecté car l'exportation est additive.

La passerelle génère des traces à travers cinq étapes : le gestionnaire HTTP entrant, l'authentification, la résolution du modèle, l'appel sortant au fournisseur et l'assemblage de la réponse en continu. Chaque trace porte un ensemble cohérent d'attributs.

Les gen_ai.* attributs suivent les conventions sémantiques OpenTelemetry pour les systèmes d'IA générative. Cela signifie que les données de trace arrivant dans Traceloop sont structurellement identiques à ce que toute application instrumentée avec OpenLLMetry produirait.

‍

Ce que Traceloop fait avec les données

Traceloop est une plateforme d'observabilité LLM construite sur OpenLLMetry, qui est sa couche d'instrumentation OpenTelemetry open-source. Le backend de Traceloop accepte les données de trace OTLP/HTTP et les indexe pour le tableau de bord Traceloop. La plateforme est native des traces. Les métriques telles que l'utilisation des jetons, la latence et le coût sont calculées à partir des attributs des traces plutôt que d'un flux de métriques OTLP séparé. C'est pourquoi la configuration du seul exportateur de traces dans TrueFoundry est suffisante — il n'y a pas de /v1/metrics point de terminaison dans la surface d'ingestion de Traceloop.

Traceloop organise les données autour de trois abstractions fondamentales. Les traces sont l'unité de niveau supérieur et correspondent directement à une requête LLM ou à un flux de travail agentique. Les spans au sein d'une trace représentent des opérations individuelles (un appel LLM, une invocation d'outil et une étape de récupération). Les environnements correspondent aux étapes de déploiement et chaque environnement possède sa propre clé API, permettant aux traces de Développement, de Staging et de Production de rester isolées dans le tableau de bord.

Le Traceloop tableau de bord affiche l'utilisation des jetons au fil du temps, les distributions de latence, les taux d'erreur et les ventilations par modèle directement à partir de gen_ai.* attributs de span. Étant donné que TrueFoundry renseigne ces attributs sur chaque span, le tableau de bord Traceloop est entièrement rempli sans aucune instrumentation SDK au niveau de la couche applicative.

‍
‍

Traceloop prend également en charge la gestion de versions de prompts et les pipelines de tests de régression, mais ces fonctionnalités opèrent au niveau du SDK d'application et sont hors du cadre de cette intégration. L'intégration au niveau de la passerelle couvre la surface d'observabilité complète : chaque requête qui passe par TrueFoundry génère une trace dans Traceloop, quel que soit le fournisseur ou le modèle de LLM appelé.

La surface d'intégration

La connexion entre TrueFoundry et Traceloop est une seule requête POST OTLP/HTTP vers https://api.traceloop.com/v1/traces transportant des lots de spans encodés en Proto. L'authentification se fait via un jeton Bearer dans l'en-tête Authorization . Le jeton est une clé API Traceloop associée à un environnement spécifique.

TrueFoundry expose cette configuration sous AI Gateway → Controls → Settings → OTEL Config. La section d'exportation des traces Otel accepte les champs suivants.

Le point de terminaison doit inclure le chemin complet /v1/traces . L'exportateur de TrueFoundry n'ajoute pas automatiquement les chemins de signal. Cela diffère de l'exportateur OTel Collector otlphttp qui ajoute automatiquement le chemin à partir de l'URL de base. Les deux mènent à la même destination.

Les clés API Traceloop sont générées par environnement depuis la page Environnements du tableau de bord Traceloop. Une clé n'est affichée qu'une seule fois lors de sa création. La valeur de la clé est transmise dans l'en-tête sous la forme Bearer <key> incluant le Bearer préfixe en tant que chaîne de caractères littérale.

Contrôles de confidentialité des données

La passerelle propose une option Exclure les données de requête dans la section Configuration OTEL. Lorsqu'elle est activée, l'exportateur supprime tfy.input et tfy.output et tfy.input_short_hand de chaque span avant de les transmettre à Traceloop. Les attributs de span restants (nombre de jetons, noms de modèles, latence et métadonnées de routage) ne sont pas affectés. Cette option est appropriée lorsque les invites ou les complétions contiennent des informations personnelles identifiables (PII) de l'utilisateur ou du contenu propriétaire qui ne doivent pas quitter les limites du cluster.

Le champ Attributs de ressource supplémentaires permet d'ajouter des paires clé-valeur personnalisées à chaque span exporté. Ceci est utile pour le marquage d'environnement, l'attribution de centres de coûts et le filtrage multi-locataire au sein d'un même environnement Traceloop.

‍

Synthèse de l'architecture

Chaque requête LLM via TrueFoundry AI Gateway génère un arbre de spans couvrant l'authentification, le routage, l'appel au fournisseur et la réponse. Une fois la requête terminée, la passerelle publie cet arbre de spans sur NATS de manière asynchrone. L'exportateur OTEL lit les données de NATS et envoie des lots encodés en Proto à https://api.traceloop.com/v1/traces avec un jeton Bearer. Traceloop indexe les spans et affiche l'utilisation des jetons, la latence et les détails du modèle dans son tableau de bord à partir des gen_ai.attributs sur chaque span.

Aucun sidecar n'est requis. Aucune modification du code de l'application n'est nécessaire. Aucun SDK OpenLLMetry n'a besoin d'être ajouté aux services appelant la passerelle. L'intégration fonctionne entièrement au niveau de la passerelle et couvre 100 % du trafic qui la traverse, quel que soit l'état d'instrumentation de l'application appelante.

La propriété architecturale qui rend cela si propre est la publication asynchrone sur NATS. Étant donné que l'exportation des spans est découplée du chemin de requête, l'intégration n'ajoute aucune latence aux appels d'inférence et n'introduit aucune dépendance de disponibilité vis-à-vis de Traceloop. La passerelle traite les requêtes à plein débit, que Traceloop soit accessible ou non.

‍