Traçage GenAI avec OpenTelemetry : un guide pratique pour l'observabilité des LLM et des agents

Pourquoi le traçage GenAI avec OpenTelemetry compte maintenant

Le traçage GenAI avec OpenTelemetry donne aux équipes d'ingénierie un moyen d'inspecter les workflows LLM et agents sans traiter l'appel au modèle comme une boîte noire. Cela peut sembler austère jusqu'au moment où quelque chose casse. L'API renvoie 200. L'application ne plante pas. L'utilisateur reçoit une réponse. Pourtant, la réponse peut être superficielle, trop coûteuse pour la tâche, construite à partir du mauvais contexte récupéré ou influencée par un appel d'outil que personne n'a remarqué lors de la revue.

C'est la partie délicate du travail d'IA en production. Les journaux standard peuvent prouver qu'une requête a eu lieu. Ils expliquent rarement pourquoi un workflow d'IA s'est comporté comme il l'a fait.

OpenTelemetry GenAI n'est pas un autre produit de supervision à acheter. C'est un ensemble de conventions sémantiques pour décrire les opérations d'IA générative dans un format cohérent. Les recommandations officielles d'OpenTelemetry couvrent les requêtes de modèle, les réponses, les événements, les métriques, les exceptions, les spans d'agents et la télémétrie associée. Si les équipes décrivent les fournisseurs, modèles, prompts, complétions, usages de tokens, outils et étapes d'agent avec des conventions partagées, les traces deviennent plus faciles à interroger, comparer et déplacer entre les backends d'observabilité.

Mon avis : la plupart des équipes IA attendent trop longtemps avant de standardiser cela. Elles ajoutent le traçage après le premier incident douloureux, lorsque les versions de prompts, les règles de routage et le comportement des outils sont déjà dispersés entre journaux, notebooks et captures de tableaux de bord. Le meilleur moment est avant qu'un workflow ne devienne important.

Des journaux applicatifs aux traces de modèles, d'outils et d'agents

La plupart des équipes de production surveillent déjà les bases : latence HTTP, codes de statut, appels à la base de données, profondeur de file, défaillances de dépendances et taux d'erreur. Les systèmes LLM échouent de façons plus discrètes. Une réponse générée peut être mauvaise parce qu'un modèle de prompt a changé, que la récupération a sélectionné des sources faibles, que le modèle a été routé vers un autre fournisseur, qu'un outil a renvoyé des données partielles, que le streaming s'est arrêté trop tôt, qu'une nouvelle tentative a modifié le contexte final ou que la validation a autorisé une réponse qui aurait dû être bloquée.

Le traçage donne une forme à ces étapes. Au lieu d'une seule opération opaque nommée générer une réponse, une trace peut montrer l'assemblage du prompt, la récupération, l'invocation du modèle, la sélection d'outil, l'exécution d'outil, la validation et l'assemblage de la réponse comme des spans liés. Cela compte lorsqu'un prototype devient un workflow géré. Le débogage, la revue d'incident, les contrôles de confidentialité et la revue des coûts exigent plus que des captures d'écran et des journaux JSON ad hoc.

Ce que les conventions sémantiques GenAI ajoutent

Les conventions GenAI d'OpenTelemetry donnent aux équipes un vocabulaire partagé pour les opérations de modèle. Un appel de modèle peut se trouver dans la même trace distribuée que la requête web, le service de récupération, la requête de base de données et l'outil en aval. À haut niveau, les conventions couvrent le système ou fournisseur GenAI, les noms d'opérations, les modèles de requête et de réponse, l'usage de tokens, les prompts et complétions sous forme d'événements lorsqu'ils sont capturés, les exceptions, les métriques et les spans liés aux agents.

La limite est aussi importante que le bénéfice. Le traçage aide les équipes à reconstruire ce qui s'est passé pendant une requête. Il ne prouve pas que la réponse finale était correcte, sûre ou utile. Il faut toujours des évaluations, du red teaming lorsque c'est approprié, des contrôles d'accès, des journaux propres aux fournisseurs, une revue de confidentialité et du jugement produit.

Le manque d'observabilité dans les applications LLM et les agents

La supervision traditionnelle des performances applicatives est forte sur la santé des services. Elle peut montrer qu'un endpoint était lent, qu'une dépendance a expiré ou qu'une requête de base de données a échoué. Pour les applications LLM, ces signaux sont nécessaires mais incomplets. Une trace de service normale manque souvent la construction du prompt, la version du modèle de prompt, les identifiants des documents récupérés, le choix du modèle, les paramètres d'échantillonnage, la raison d'arrêt, le routage des outils, le comportement de nouvelle tentative, les décisions de sécurité et les résultats d'évaluation.

Les agents élargissent ce manque. Ils peuvent planifier, appeler des outils, inspecter des résultats, appeler à nouveau le modèle, récupérer de la mémoire, transférer à un autre workflow, exécuter des validations et s'arrêter selon une règle de terminaison. Certaines étapes peuvent échouer alors que l'utilisateur reçoit tout de même une réponse finale. Les équipes qui travaillent sur des systèmes agentiques devraient aussi lire plus largement sur la fiabilité et la supervision des agents IA, car le traçage montre le chemin suivi par un agent tandis que la supervision décide si ce chemin était acceptable.

Une première version pratique de l'observabilité LLM enregistre généralement le modèle et le fournisseur, le nom de l'opération, le modèle demandé, le modèle de réponse lorsqu'il est disponible, les paramètres de requête, la latence, les nombres de tokens lorsqu'ils sont disponibles, la raison d'arrêt, le nom de l'outil, le statut du résultat d'outil, les identifiants de sources de récupération, les catégories d'erreurs, les indicateurs de sécurité et les résultats d'évaluation. La capture du contenu nécessite une politique plus stricte. Les prompts et complétions peuvent contenir des données utilisateur, des documents privés, des secrets, des contrats, du code source, des informations de santé, des données financières ou une stratégie interne. Beaucoup d'équipes devraient commencer avec des métadonnées, des IDs, des hachages et des extraits caviardés plutôt qu'avec le contenu complet.

Ce qu'OpenTelemetry GenAI standardise

Les conventions sémantiques d'OpenTelemetry définissent un langage commun pour la télémétrie. Dans le domaine GenAI, elles décrivent des attributs et événements qui rendent les opérations de modèle reconnaissables entre services et outils. Un span d'invocation de modèle peut identifier le fournisseur GenAI, le nom de l'opération, le modèle demandé, le modèle de réponse, les paramètres de requête, l'usage de tokens et les métadonnées de réponse. Les noms exacts des attributs doivent être vérifiés dans le dépôt OpenTelemetry GenAI actuel avant l'implémentation, car les conventions changent encore.

Les événements sont utiles parce qu'une requête de modèle n'est pas toujours bien représentée par des attributs de span statiques. Une interaction de chat peut contenir plusieurs messages. Une réponse en streaming peut produire des morceaux au fil du temps. Un appel d'outil peut être associé à un message assistant puis à un résultat d'outil ultérieur. La sécurité reste prioritaire. Les événements peuvent transporter du texte sensible si la capture du contenu est activée. Les équipes qui construisent des workflows documentaires peuvent trouver utile le guide Optijara sur les pipelines d'IA documentaire, puisque les systèmes documentaires combinent souvent récupération, extraction, génération et contraintes de confidentialité.

OpenTelemetry Protocol, généralement abrégé en OTLP, donne aux équipes une voie pour envoyer la télémétrie vers des backends d'observabilité compatibles. La prise en charge côté backend varie. Certains outils affichent clairement les traces GenAI. D'autres les traitent comme des spans ordinaires avec des attributs. Avant de considérer cela comme prêt pour la production, vérifiez l'interrogeabilité, la visualisation des traces, le comportement de rétention et le contrôle d'accès dans le backend que votre équipe utilise réellement.

La carte de traces GenAI d'Optijara

La carte de traces GenAI d'Optijara est un cadre orienté décision pour concevoir l'observabilité des LLM et des agents. Elle transforme le traçage, qui passe d'une habitude de collecte de données à une activité de conception de production. La question n'est pas ce que pouvons-nous journaliser. La meilleure question est quelle décision cette trace doit-elle nous aider à prendre, quels spans exposent cette décision et quel contenu doit rester hors de la télémétrie.

Commencez par les décisions, pas par les tableaux de bord. Les questions utiles pour une trace incluent quel appel de modèle a été lent, quel fournisseur a traité la requête, quelle version du modèle de prompt a été utilisée, quels documents ont été récupérés, quel outil a échoué, si les nouvelles tentatives ont changé la réponse finale, si la validation a réussi et quel workflow a produit un usage inhabituel.

Une politique compacte lisible par machine peut aider les équipes d'ingénierie et de gouvernance à s'aligner avant que l'instrumentation ne se diffuse :

{
  "framework": "Optijara GenAI Trace Map",
  "trace_goal": "debug and evaluate one production AI workflow",
  "required_spans": ["entry", "prompt_assembly", "retrieval", "model_call", "tool_call", "validation", "evaluation"],
  "content_policy": {
    "forbidden": ["secrets", "credentials", "unredacted private documents"],
    "redacted": ["user text", "tool output"],
    "sampled": ["prompt events", "completion events"],
    "retained": ["metadata", "trace ids", "template versions", "document ids"]
  }
}

Modèles d'implémentation, d'un appel LLM aux agents

L'implémentation la plus simple trace une requête de modèle dans une trace applicative existante. Le span parent est la requête utilisateur ou la tâche en arrière-plan. Le span enfant est l'opération GenAI. Il doit capturer le fournisseur ou système, le modèle demandé, le nom de l'opération, les paramètres pertinents, la latence, le statut, l'usage de tokens lorsqu'il est disponible, le modèle de réponse lorsqu'il est disponible et les détails d'exception si l'appel échoue.

La génération augmentée par récupération nécessite plus qu'un span de modèle. Une trace RAG utile inclut généralement la réécriture de requête, la recherche d'embeddings, le reranking, les IDs de documents sélectionnés, l'assemblage du contexte, la génération finale, la validation des citations et l'assemblage de la réponse. Les IDs de documents comptent parce qu'ils permettent aux équipes d'auditer quelles sources ont influencé la réponse sans placer des documents confidentiels complets dans la télémétrie.

Pour les agents, représentez le workflow comme un arbre. Le span racine est la tâche utilisateur. Les spans enfants peuvent inclure la planification, les appels de modèle, la sélection d'outil, chaque exécution d'outil, la validation de sortie d'outil, la réflexion, les lectures de mémoire, la validation de réponse et la terminaison. Si l'agent appelle des outils en parallèle, chaque appel d'outil doit être visible comme un span frère avec statut et durée.

user_task: investigate_invoice_question
  prompt_assembly: support_agent_v4
  model_call: plan_next_step
  tool_call: search_orders status=ok
  tool_call: fetch_invoice status=timeout
  model_call: revise_plan_after_timeout
  tool_call: fetch_invoice status=ok retry=1
  validation: policy_and_schema_check status=passed
  response_assembly: final_answer

LangSmith documente la prise en charge du traçage OpenTelemetry, ce qui constitue un exemple utile d'intégration d'écosystème. L'instrumentation de framework peut réduire le travail manuel sur les spans, surtout lorsque les équipes utilisent déjà un framework pour les chaînes, les outils ou les agents. Traitez cette instrumentation comme un point de départ, puis inspectez les traces exportées. Cela va bien avec une hygiène d'ingénierie plus large comme l'utilisation de uv pour les workflows de projets Python, où des outils reproductibles et des environnements cohérents rendent le déploiement de l'observabilité plus facile à maintenir.

Plan d'adoption et d'évaluation

Un déploiement sûr commence avec un workflow et une checklist de test. Vérifiez la continuité de trace entre services. Confirmez que les noms d'attributs GenAI correspondent à la documentation OpenTelemetry actuelle que votre équipe a choisi de suivre. Vérifiez le comportement d'échantillonnage. Testez le caviardage des prompts. Inspectez les réponses en streaming. Confirmez si l'usage de tokens est disponible auprès de votre fournisseur et comment il est représenté. Assurez-vous que les erreurs d'outils sont capturées comme des erreurs d'outils, et pas seulement comme des exceptions génériques. Interrogez les traces dans le backend et confirmez que les ingénieurs d'astreinte peuvent trouver ce dont ils ont besoin.

Évitez de capturer les prompts complets par défaut. Évitez de vous appuyer sur un seul tableau de bord comme source de vérité. Évitez de traiter les nombres de tokens comme exacts chez tous les fournisseurs et dans tous les workflows. Évitez d'instrumenter chaque fonction utilitaire. Évitez d'ignorer la politique de rétention et d'accès. Évitez d'utiliser les traces comme preuve qu'une réponse était bonne. Les conventions OpenTelemetry continuent d'évoluer, les équipes devraient donc verrouiller les versions d'instrumentation, documenter les hypothèses et revoir les changements de conventions avant un déploiement large.

Erreurs courantes des équipes

Le moyen le plus rapide de créer un risque d'observabilité est de journaliser d'abord les prompts et complétions, puis de discuter de la politique ensuite. Les prompts peuvent contenir des données personnelles, des documents confidentiels, des identifiants, du code source, des plans d'affaires privés ou des informations réglementées. Définissez les champs interdits, caviardés, échantillonnés et conservés avant l'instrumentation.

Le traçage limité au modèle est trop étroit pour les agents. Beaucoup d'échecs se produisent hors du modèle : la récupération renvoie un contexte faible, un outil expire, la validation est ignorée, la mémoire contient des informations périmées ou l'assemblage de la réponse supprime un détail important. Si la trace s'arrête au span du modèle, l'équipe peut blâmer la mauvaise couche.

Chaque attribut doit répondre à une question. Qui utilisera ce champ, pendant quel workflow et quelle décision soutiendra-t-il ? Si personne ne peut répondre, le champ est probablement du bruit. Les traces sont une preuve de processus. Les évaluations sont une preuve de qualité de sortie, et même les évaluations demandent une conception soigneuse de la grille.

Comment choisir votre premier projet de traçage

Le meilleur premier projet n'est pas toujours la fonctionnalité IA la plus complexe. Choisissez un workflow où l'observabilité changera bientôt les décisions.

Un premier jalon pratique est une requête de bout en bout avec un arbre de trace lisible. La trace doit se connecter aux journaux applicatifs via l'ID de trace. Elle doit montrer l'assemblage du prompt, la récupération si elle existe, l'appel du modèle, les résultats d'outils s'ils existent, la validation de réponse et un signal d'évaluation ou de revue. Le caviardage doit être vérifié avant tout déploiement plus large.

Si votre équipe passe de prototypes à des workflows IA en production, Optijara peut aider à cartographier les traces, les évaluations et les contrôles de gouvernance avant que l'instrumentation ne devienne bruyante ou risquée. L'objectif devrait être une observabilité neutre vis-à-vis des fournisseurs, qui aide les équipes à déboguer, évaluer et exploiter les systèmes IA avec des limites claires.

Le traçage GenAI avec OpenTelemetry est le plus utile lorsque les équipes standardisent avant de passer à l'échelle, tracent les décisions plutôt que chaque appel possible, protègent le contenu sensible, relient les traces aux évaluations et gardent les conventions sous revue à mesure que l'écosystème mûrit.