Exportation des traces de la passerelle TrueFoundry AI vers SigNoz 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. SigNoz Cloud accepte ces spans via OTLP/HTTP sur un point d'ingestion régional authentifié par une clé d'ingestion par espace de travail. Pour connecter les deux, il faut configurer l'exportateur OTEL de la passerelle avec l'URL d'ingestion de SigNoz et ajouter l'en-tête signoz-ingestion-key . Aucune modification de l'instrumentation au niveau de l'application n'est requise.

Cet article aborde le chemin de génération des traces OTEL au sein de la passerelle TrueFoundry AI, le pipeline d'ingestion et de stockage utilisé par SigNoz Cloud, ainsi que la surface de configuration pour relier les deux systèmes. Ce n'est pas un guide de configuration, mais une explication du fonctionnement de l'intégration au niveau architectural.

Comment la passerelle TrueFoundry AI génère et exporte les traces

La TrueFoundry AI Gateway est construite sur le framework Hono 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 supplémentaire. Ce débit est possible car 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, téléchargées une seule fois depuis le fournisseur d'identité. Les vérifications d'autorisation s'effectuent à l'aide d'une carte en mémoire des utilisateurs vers les modèles, synchronisée via NATS. La logique de routage des modèles s'exécute entièrement en mémoire à partir d'une copie locale de la configuration de routage.

La génération de traces OTEL suit le même principe de zéro appel externe. 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 n'intervient jamais dans le chemin de la requête. Un backend OTEL lent ou inaccessible ne bloque jamais une requête et n'ajoute jamais de latence visible pour le client.

La passerelle génère des spans à plusieurs points du cycle de vie de la requête. La gestion des requêtes HTTP entrantes, l'authentification, la résolution des modèles et l'appel au fournisseur externe produisent chacun des spans qui sont assemblés en une trace. Les spans contiennent un ensemble spécifique d'attributs. L'attribut tfy.input contient le corps complet de la requête envoyée au LLM. L'attribut tfy.output contient le corps complet de la réponse. L'attribut tfy.input_short_hand contient un résumé condensé de l'entrée avec des drapeaux booléens pour le contenu de fichier, d'image et audio. Le tfy.span_type attribut identifie le type d'opération comme ChatCompletion, AgentResponse ou MCPGateway, selon le chemin de passerelle qui a traité la requête. Les conventions gen_ai.* sémantiques sont également incluses, couvrant le nombre de jetons d'invite, le nombre de jetons de complétion, les identifiants de modèle et les raisons de fin.

La passerelle expose également un Exclure les données de requête commutateur dans la configuration OTEL. Lorsqu'il est activé, l'exportateur supprime tfy.input et tfy.output et tfy.input_short_hand des spans avant de les transmettre. C'est le réglage approprié pour les équipes qui ont besoin d'une visibilité complète des traces pour l'analyse de la latence et des erreurs, mais qui ne doivent pas transmettre le contenu des invites ou des réponses à une plateforme externe.

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

Ce que SigNoz fait des traces

SigNoz est construit autour d'un collecteur OpenTelemetry personnalisé qui accepte les données de télémétrie et les écrit dans ClickHouse. Le collecteur est configuré pour ingérer des données via les protocoles OTLP standard et fournit une traduction de protocole pour une intégration transparente avec les outils de surveillance existants et traite les données avec enrichissement de métadonnées avant de les écrire dans le stockage.

Le pipeline d'ingestion suit l'architecture du collecteur OpenTelemetry avec des récepteurs, des processeurs et des exportateurs. Le récepteur OTLP accepte les spans de trace via gRPC sur le port 4317 et HTTP sur le port 4318. Un processeur de lot regroupe les spans pour plus d'efficacité avant l'exportation. Le signozspanmetrics processeur génère des métriques RED (Taux, Erreur et Durée) directement à partir des données de span afin que le taux de requêtes, le taux d'erreurs et les percentiles de latence soient disponibles en tant que métriques interrogeables sans aucune instrumentation séparée. Les spans de trace sont écrites dans la distributed_signoz_index_v3 table dans ClickHouse. Les métriques générées sont acheminées vers la signoz_metrics.distributed_samples_v4 table.

SigNoz Cloud utilise une architecture par locataire. Chaque locataire dispose de sa propre instance SigNoz, de son propre ClickHouse pour le stockage des données de télémétrie, de son propre collecteur OTel pour l'ingestion et de son propre point d'accès régional. L'infrastructure partagée gère l'ingestion initiale : une passerelle OpenTelemetry reçoit la télémétrie, la regroupe par lots et la transmet à un tampon de streaming Redpanda avant que l'instance SigNoz par locataire ne la consomme et l'écrive dans ClickHouse. Cela signifie que le ingest.<region>.signoz.cloud:443 point d'accès est une couche d'ingestion partagée. L' signoz-ingestion-key en-tête achemine les données vers le pipeline par locataire correct après l'ingestion.

Le service de requête SigNoz lit les données de ClickHouse en utilisant des requêtes SQL optimisées qui exploitent le format de stockage en colonnes pour l'agrégation sur de grands volumes de données de span. L'explorateur de traces affiche les spans individuels, filtrables par nom de service, opération, statut et durée, comme illustré ci-dessous.

‍

L'explorateur de métriques accepte les requêtes compatibles PromQL sur les métriques RED générées. Étant donné que la passerelle émet des attributs standard gen_ai.* en plus des attributs tfy.* SigNoz peut afficher à la fois des données de performance HTTP génériques et des données spécifiques aux LLM dans la même vue de trace.

La surface d'intégration

Le Passerelle IA TrueFoundry se connecte à SigNoz via deux configurations d'exportateur OTEL : une pour les traces et une pour les métriques. Les deux utilisent l'encodage HTTP et Proto. L'en-tête signoz-ingestion-key est requis sur les deux exportateurs. Le format du point de terminaison inclut la région en tant que sous-domaine et se connecte sur le port 443 via HTTPS. La configuration est accessible sous Passerelle IA → Contrôles → Paramètres → Configuration OTEL dans le tableau de bord TrueFoundry, comme indiqué ci-dessous.

‍

Configuration de l'exportateur de traces OTEL

Configuration de l'exportateur de métriques OTEL

La région est dérivée de l'URL d'ingestion de SigNoz Cloud visible dans les paramètres du compte. Pour une URL d'ingestion de https://ingest.in2.signoz.cloud , la région est in2 et le point de terminaison des traces devient https://ingest.in2.signoz.cloud:443/v1/traces. La clé d'ingestion est une information d'identification limitée à l'espace de travail disponible sous Paramètres → Paramètres d'ingestion dans le tableau de bord SigNoz Cloud.

Contrairement aux cibles d'observabilité auto-hébergées où le trafic reste à l'intérieur du cluster via HTTP simple, SigNoz Cloud est un point de terminaison externe accessible via l'internet public. L'exportateur de la passerelle établit une connexion TLS au port 443 et envoie des spans dans des lots OTLP/HTTP encodés en protobuf. Le chemin d'exportation asynchrone basé sur NATS dans la passerelle signifie que même si le point de terminaison d'ingestion SigNoz est temporairement inaccessible, la passerelle continue de traiter les requêtes normalement. Les spans qui ne peuvent pas être livrées sont abandonnées au niveau de l'exportateur et journalisées sans remonter d'erreurs à l'appelant.

Les deux exportateurs peuvent être activés indépendamment. L'activation de l'exportateur de traces uniquement envoie les données de span à SigNoz tout en maintenant l'exportation des métriques désactivée. L'activation des deux envoie les données de span au distributed_signoz_index_v3 données de table et de métriques vers le signoz_metrics.distributed_samples_v4 tableau à partir duquel SigNoz génère les vues de métriques RED dans l'explorateur de métriques.

Filtrage par service dans SigNoz

La passerelle définit service.name à tfy-llm-gateway sur toutes les spans en tant qu'attribut de ressource. Dans l'explorateur de traces SigNoz, le filtrage par service.name = tfy-llm-gateway isole tout le trafic de la passerelle. Le filtrage par tfy.span_type = ChatCompletion réduit davantage aux requêtes d'inférence LLM. L'attribut tfy.data_routing.destination identifie quel modèle ou modèle virtuel a traité la requête et peut être utilisé pour regrouper les distributions de latence par modèle.

Synthèse de l'architecture

Une requête entre dans la Passerelle IA TrueFoundry et est traitée entièrement en mémoire. 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 span sur NATS contenant tous les attributs de requête et de réponse, le nombre de jetons et la latence. L'exportateur OTEL récupère la span de NATS de manière asynchrone et la transmet via OTLP/HTTP avec le signoz-ingestion-key en-tête vers le point d'ingestion régional SigNoz sur le port 443. La passerelle OTel SigNoz partagée reçoit la span et la regroupe dans Redpanda. Le collecteur par locataire SigNoz consomme depuis Redpanda et applique le signozspanmetrics processeur pour générer des métriques RED, puis écrit les spans dans distributed_signoz_index_v3 et les métriques dans signoz_metrics.distributed_samples_v4 dans l'instance ClickHouse par locataire. Le service de requête SigNoz lit depuis ClickHouse et affiche la trace dans l'explorateur de traces et les métriques générées dans l'explorateur de métriques.

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 à ajouter deux points de terminaison d'exportateur OTEL dans les paramètres de configuration OTEL de la passerelle TrueFoundry AI. La passerelle génère et publie déjà les spans. La configuration de l'exportateur et la clé d'ingestion déterminent leur destination.

Le principe architectural qui permet à cette intégration de fonctionner est la séparation complète entre le chemin de la requête et le chemin d'exportation de la télémétrie. La passerelle publie la télémétrie vers NATS une fois que la réponse est déjà en transit. Le point d'ingestion SigNoz peut être lent, temporairement indisponible ou géographiquement éloigné sans aucun effet sur la latence ou la fiabilité de la passerelle. La portabilité OTEL signifie que les mêmes données de span qui transitent vers SigNoz aujourd'hui peuvent transiter vers tout autre backend compatible OTLP sans modifier la configuration de la passerelle, au-delà de l'URL du point de terminaison et de l'en-tête d'authentification.

‍