Exportation des traces de la passerelle IA TrueFoundry vers OpenLIT via OTLP

Le TrueFoundry AI Gateway génère des spans OpenTelemetry pour chaque requête LLM et les publie de manière asynchrone via NATS. OpenLIT est une plateforme d'observabilité auto-hébergée qui accepte les traces et métriques OTLP via HTTP ou gRPC et les stocke dans ClickHouse. La connexion des deux systèmes nécessite de configurer l'exportateur OTEL de la passerelle pour qu'il pointe vers le point de terminaison du collecteur OpenLIT. Aucune modification de code n'est requise dans aucune application.

Cet article couvre le chemin de génération des traces OTEL au sein du TrueFoundry AI Gateway et le ClickHouse modèle de stockage que OpenLIT utilise, ainsi que la surface de configuration pour relier les deux systèmes. Ce n'est pas un guide d'installation étape par étape. C'est une explication du fonctionnement de l'intégration au niveau architectural.

Comment le TrueFoundry AI Gateway génère et exporte les traces

Le TrueFoundry AI Gateway est construit sur le Hono framework et fonctionne comme un pod sans état. Un seul pod avec 1 vCPU et 1 Go de RAM gère plus de 250 requêtes par seconde avec environ 3 ms de latence ajoutée. Ce profil de performance n'est possible que parce que la passerelle n'effectue aucun appel externe dans le chemin de la requête. L'authentification s'effectue à l'aide de clés publiques mises en cache. Les vérifications d'autorisation s'effectuent à l'aide d'une carte en mémoire des utilisateurs vers les modèles. La logique de routage des modèles s'exécute entièrement en mémoire.

La génération de traces OTEL suit ce même principe. Lorsqu'une requête est terminée, la passerelle publie les données de span de manière asynchrone vers NATS. L'exportateur OTEL lit à partir de ce chemin asynchrone et transmet le span au point de terminaison externe configuré. L'exportateur ne touche jamais le chemin de la requête. Un backend OTEL lent ou inaccessible ne bloque jamais une requête.

Les spans émises par la passerelle comportent un ensemble spécifique d'attributs. L'attribut tfy.input contient le corps complet de la requête envoyé au LLM. L' tfy.output attribut contient la réponse complète. Le tfy.input_short_hand l'attribut contient un résumé condensé de l'entrée, incluant des indicateurs booléens pour savoir si la requête contenait des fichiers, des images ou de l'audio. L' tfy.span_type attribut identifie le type d'opération, tel que ChatCompletion ou AgentResponse. Les conventions sémantiques standard gen_ai.* sont également incluses, couvrant les nombres de jetons, les identifiants de modèle et les raisons de fin.

La passerelle expose également un Exclure les données de requête commutateur. Lorsqu'il est activé, l'exportateur supprime tfy.input et tfy.output et tfy.input_short_hand des spans avant de les transmettre. Ceci est pertinent pour les équipes qui doivent acheminer la télémétrie vers une plateforme externe sans envoyer le contenu des invites ou des réponses en dehors de leur infrastructure.

L'exportation est additive. L'activation d'une destination OTEL externe ne remplace ni n'interrompt le stockage interne des traces de TrueFoundry. Les deux chemins reçoivent les mêmes spans.

Ce qu'OpenLIT fait avec les traces

OpenLIT est une plateforme d'observabilité native d'OpenTelemetry. Elle ne nécessite pas de sidecar, d'enveloppe SDK ni aucune modification de la couche applicative. Elle accepte les spans via le protocole OTLP standard sur le port 4318 pour HTTP et le port 4317 pour gRPC et les écrit dans ClickHouse.

ClickHouse stocke les traces dans le otel_traces table et les métriques dans la otel_metrics table. Le schéma suit directement le modèle de données OpenTelemetry. Chaque span est stocké comme une ligne avec une colonne SpanAttributes de type Map(String, String) qui contient tous les attributs clé-valeur émis par la passerelle. L'interrogation d'un attribut spécifique utilise la syntaxe d'accès aux maps :

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;

Le tableau de bord OpenLIT lit ces tables ClickHouse et affiche les chronologies de requêtes, les distributions de latence et les taux d'erreur. Étant donné que la couche de stockage est une instance ClickHouse standard, les équipes peuvent également exécuter directement des requêtes SQL arbitraires pour des rapports personnalisés ou des pipelines d'alerte.

OpenLIT intègre son propre collecteur OTel aux côtés du tableau de bord et de la base de données. Le collecteur est le point d'entrée pour tous les spans et métriques entrants. Il reçoit les données via OTLP et les écrit dans ClickHouse en utilisant l'exportateur ClickHouse. La configuration du collecteur définit des pipelines distincts pour les traces, les métriques et les logs, chacun étant soutenu par un processeur de lots et un limiteur de mémoire.

Les trois composants sont livrés sous forme d'un seul chart Helm. Le collecteur et le tableau de bord s'exécutent à l'intérieur du même pod Kubernetes. ClickHouse s'exécute en tant que StatefulSet distinct avec une revendication de volume persistant. Un conteneur d'initialisation dans le pod OpenLIT attend que ClickHouse réponde sur le port 8123 avant de démarrer les processus du collecteur et du tableau de bord. Ce séquençage signifie que la version Helm est autonome et que l'ordre de déploiement est géré automatiquement.

Une fois déployé, TrueFoundry affiche les deux pods dans un état d'exécution : openlit-0 exécutant le tableau de bord et le collecteur OTel et openlit-db-0 exécutant ClickHouse.

Le tableau de bord OpenLIT est accessible à l'URL du domaine de cluster exposé. La page de connexion répertorie les principales fonctionnalités de la plateforme, y compris le traçage de bout en bout, l'analyse des coûts et des jetons, et l'évaluation LLM-as-a-Judge.

La surface d'intégration

La TrueFoundry AI Gateway se connecte à OpenLIT via deux configurations d'exportateur OTEL : une pour les traces et une pour les métriques. Les deux utilisent l'encodage HTTP et Proto. Aucun en-tête d'authentification n'est requis car le point de terminaison du collecteur OpenLIT se trouve dans le même cluster Kubernetes que la passerelle. Le trafic entre les deux reste sur le réseau interne du cluster.

Configuration de l'exportateur de traces OTEL

Configuration de l'exportateur de métriques OTEL

‍

Le openlit service Kubernetes expose trois ports. Le port 3000 sert au tableau de bord. Le port 4317 accepte OTLP via gRPC. Le port 4318 accepte OTLP via HTTP. Les trois utilisent le même nom de service et la même entrée DNS. Le chemin d'exportation asynchrone basé sur NATS dans la passerelle signifie que même si le collecteur OpenLIT est temporairement indisponible, la passerelle continue de traiter les requêtes normalement. Les spans qui ne peuvent pas être livrés sont abandonnés au niveau de l'exportateur et journalisés sans que des erreurs ne soient remontées à l'appelant.

Le chart Helm OpenLIT est hébergé à l'adresse https://openlit.github.io/helm/ sous le nom de chart openlit. Le chart accepte un bloc de valeurs qui définit les paramètres de connexion ClickHouse pour le tableau de bord et le collecteur, ainsi que la configuration de persistance pour la base de données. Le tableau de bord se connecte à ClickHouse en utilisant la INIT_DB_HOST variable d'environnement qui doit pointer vers le service ClickHouse StatefulSet en utilisant son nom DNS interne openlit-db.NAMESPACE.svc.cluster.local.

La configuration du collecteur est stockée dans un ConfigMap nommé openlit-otel-config. Il définit trois pipelines. Le pipeline de traces passe par un limiteur de mémoire réglé à 1500 MiB avec une limite de pic de 512 MiB et un processeur de lot avant d'être transmis à l'exportateur ClickHouse. Le pipeline de métriques suit la même chaîne de traitement. Le pipeline de logs omet le limiteur de mémoire et utilise uniquement le processeur de lot. Les trois pipelines écrivent dans la même instance ClickHouse en utilisant le protocole TCP natif sur le port 9000.

Le VirtualService pour le tableau de bord utilise la passerelle Istio de TrueFoundry istio-system/tfy-wildcard et achemine le trafic du domaine du cluster vers le service interne openlit sur le port 3000. C'est le seul composant qui nécessite une exposition externe. Les points d'accès du collecteur restent internes.

Référence DNS du service interne

Résumé de l'architecture

Une requête entre dans la TrueFoundry AI Gateway et est traitée entièrement en mémoire par rapport à l'état d'authentification mis en cache et à la configuration de routage. La passerelle transmet la requête au fournisseur LLM et diffuse la réponse au client. Une fois la réponse terminée, la passerelle publie une trace (span) sur NATS contenant tous les attributs de la requête et de la réponse, le nombre de jetons et la latence. L'exportateur OTEL récupère la trace de NATS de manière asynchrone et la transmet via OTLP/HTTP au collecteur OpenLIT fonctionnant sur le port 4318 à l'intérieur du cluster. Le collecteur écrit la trace dans ClickHouse. Le tableau de bord OpenLIT lit les données de ClickHouse et rend la trace disponible pour inspection.

L'onglet Métriques affiche les données agrégées de séries temporelles provenant de la otel_metrics table. Le volume des requêtes de la passerelle et les tendances de latence sont disponibles sur des fenêtres temporelles sélectionnables, de 24 heures à 3 mois.

Aucun sidecar n'est requis. Aucune modification du SDK n'est requise. Aucun code d'instrumentation n'est ajouté à aucune application. La seule modification de configuration consiste à définir les points d'accès de l'exportateur OTEL dans les TrueFoundry AI Gateway paramètres. La passerelle génère et publie déjà les traces. La configuration de l'exportateur détermine leur destination.

Le principe architectural qui rend cette intégration fonctionnelle est la séparation entre le chemin de la requête et le chemin de la télémétrie. Étant donné que les traces sont publiées sur NATS une fois la réponse complète, la fiabilité du backend d'observabilité n'a aucun effet sur la latence ou la disponibilité de la passerelle. OpenLIT reçoit ce que la passerelle publie. Si OpenLIT est indisponible, la passerelle continue de fonctionner et reprend l'exportation lorsque la connectivité est rétablie.

‍