Instrumenter une application d’IA pour diagnostiquer les pannes, la latence et la consommation

1. Commencez par les questions opérationnelles, pas par les champs

L’observabilité d’une application d’IA consiste à pouvoir reconstituer son comportement à partir de signaux liés entre eux : quelle requête est arrivée, quelles étapes ont été exécutées, où un problème est survenu et combien de temps chaque étape a pris. Pour une application qui appelle déjà un modèle par API, instrumenter ne signifie pas copier chaque entrée et chaque réponse dans des journaux. Il s’agit de recueillir assez de contexte pour répondre de manière reproductible aux questions opérationnelles, dans un périmètre défini et avec une politique de traitement des données claire.

Avant de choisir une bibliothèque ou de créer un tableau de bord, notez les questions auxquelles l’équipe doit pouvoir répondre pendant un incident. Par exemple : quelles versions de l’application et du prompt ont traité cette requête ? Le modèle a-t-il été appelé une seule fois ou y a-t-il eu des tentatives répétées ? Quel outil a été exécuté et combien de temps a-t-il pris ? Le retard vient-il de l’application, du réseau, du modèle ou d’un outil ? Quelles données d’utilisation l’API a-t-elle communiquées ? Ces questions orientent la conception ; les champs qui n’aident pas à y répondre ne devraient pas être ajoutés par habitude.

Il est utile de distinguer l’observabilité de l’évaluation du contenu. Cet article porte sur le parcours technique et opérationnel d’une requête : pannes, latence, nouvelles tentatives et consommation communiquée. Il ne propose pas de méthode pour déterminer si une réponse est vraie, choisir un fournisseur ou concevoir un flux conversationnel. Cette délimitation permet de garder les journaux concis et d’éviter de présenter un signal technique comme une preuve de qualité.

2. Cartographiez le cycle et définissez la corrélation

Une requête qui semble correspondre à un seul appel depuis l’interface peut comporter plusieurs opérations : validation de l’entrée, construction du prompt, appel du modèle, traitement de la réponse et, éventuellement, appel à un outil. En cas de nouvelle tentative, chaque tentative doit rester visible comme une opération distincte. Les journaux doivent permettre de regrouper ces événements sans dépendre d’identifiants que l’API externe ne garantit pas.

Créez votre propre identifiant lorsque la requête entre dans l’application, puis transmettez-le aux composants que vous contrôlez. Ajoutez des identifiants enfants ou des numéros d’étape pour distinguer les appels au modèle et aux outils. Si le fournisseur renvoie un identifiant de requête, conservez-le comme champ supplémentaire pour faciliter une demande d’assistance ou une recherche ultérieure, mais ne l’utilisez pas comme seul lien : il peut être absent dans certains types d’erreur ou certains parcours d’exécution.

Définissez également les limites temporelles de chaque mesure. La durée totale commence lorsque l’application accepte la requête et se termine lorsque la réponse est remise ou que l’échec final est enregistré. La durée d’un appel au modèle commence au lancement de cet appel et s’achève à la réception de la réponse ou de l’erreur. Un appel à un outil possède ses propres heures de début et de fin. Enregistrer des millisecondes sans préciser ces limites produit des chiffres qu’il est difficile de comparer de manière fiable.

3. Définissez un schéma minimal et consignez ce que l’API renvoie réellement

Un schéma minimal doit distinguer les données produites par votre application des champs reçus du fournisseur. Les champs internes comprennent généralement l’identifiant de requête, l’étape, le numéro de tentative, l’état, les horodatages et les versions du code et du prompt. Le modèle demandé, la configuration et l’identifiant renvoyé par le fournisseur peuvent aider à reconstituer l’exécution, mais leur origine doit être indiquée.

Les données d’utilisation communiquées par une API ne sont pas universelles. Elles peuvent varier selon le point de terminaison, le modèle, la modalité, la version ou le type de réponse ; elles peuvent aussi manquer en cas d’erreur ou de réponse partielle. La documentation disponible pour ce guide ne porte pas sur un fournisseur précis et ne permet pas d’affirmer qu’une liste de champs s’applique partout. Il faut donc créer un adaptateur pour chaque API et vérifier, dans sa documentation primaire actuelle, les noms des champs, leurs unités et les cas où ils sont présents. Enregistrez le résultat comme « utilisation déclarée par l’API », en précisant quels champs étaient présents, et ne remplacez pas les valeurs absentes par des zéros sans les distinguer.

Distinguez également le temps mesuré par l’application de toute durée communiquée par le fournisseur. Le premier mesure le parcours dans votre système ; le second, s’il existe, suit la définition du fournisseur. Indiquez toujours les unités — par exemple, des millisecondes pour les durées — et précisez si les horodatages sont enregistrés en UTC. Une convention cohérente permet de comparer les requêtes et de détecter des variations sans mélanger des horloges ou des intervalles différents.

4. Instrumentez des événements structurés de bout en bout

Les journaux structurés sont plus faciles à filtrer et à regrouper que des messages rédigés en texte libre. Définissez des noms stables pour les événements, les états et les champs ; évitez que chaque composant emploie un libellé différent pour désigner la même chose. Il n’est pas nécessaire de choisir une plateforme d’observabilité particulière pour commencer : l’application peut émettre des événements JSON, qui seront ensuite exportés vers la solution déjà utilisée par l’équipe.

Une approche utile consiste à émettre un événement de début et un événement de fin pour chaque étape, ou un seul événement de fin contenant les heures de début et de fin ainsi que le résultat si l’étape est courte et ne nécessite pas de mise à jour en temps réel. Pour les opérations longues, l’événement de fin doit conserver le lien vers la requête d’origine. Si vous utilisez des traces distribuées, transmettez le contexte à travers les services et les files d’attente que vous contrôlez ; vérifiez que l’identifiant ne se perd pas lors du passage d’une tâche synchrone à une tâche asynchrone.

L’exemple ci-dessous est un pseudo-code schématique, et non une intégration exécutable à une API. Les noms des champs de réponse et d’erreur dépendent du SDK et du fournisseur. Dans une implémentation réelle, adaptez l’extraction des données d’utilisation et des erreurs à la documentation actuelle, et vérifiez que le bloc d’exception n’enregistre pas automatiquement des corps de réponse susceptibles de contenir des données sensibles.

5. Minimisez les données sensibles avant leur stockage ou leur exportation

L’observabilité n’exige pas de conserver les prompts complets, les réponses intégrales ni les arguments d’outils pour chaque requête. Ces contenus peuvent inclure des données personnelles, des secrets, des informations commerciales ou d’autres éléments inutiles pour répondre aux questions opérationnelles. Commencez par des métadonnées et des signaux dérivés : identifiants opaques, versions, longueurs, catégories d’erreur, états et durées.

Pour chaque champ, déterminez le traitement approprié : l’exclure, le rédiger, le transformer ou le conserver avec un accès restreint et une durée limitée. Pour relier une trace à une entité métier, une clé pseudonymisée ou une référence interne que seul un système autorisé peut résoudre peut suffire. Un hachage ne garantit pas l’anonymat si la valeur d’origine est prévisible ou peut être comparée à une liste ; ne le considérez pas automatiquement comme une solution de confidentialité.

Testez la rédaction avant d’activer les journaux en production. Utilisez des exemples synthétiques couvrant des cas courants et des variantes : une adresse électronique dans une entrée, un jeton dans un en-tête ou une donnée confidentielle dans la réponse d’un outil. Vérifiez à la fois l’événement émis par l’application et celui qui arrive dans le stockage : une règle appliquée uniquement dans le tableau de bord ou après l’exportation laisse la donnée exposée pendant son transfert.

6. Créez des tableaux de bord et des alertes pour enquêter, pas pour accumuler les graphiques

Un tableau de bord utile répond à une question et indique clairement quelle action peut suivre. Commencez par trois vues : état des requêtes, distribution de la latence et utilisation déclarée. Pour l’état, affichez le nombre de requêtes terminées, échouées et sans résultat final, ventilées par catégorie d’erreur. Pour la latence, affichez la durée totale et la durée par étape, avec des percentiles en plus des moyennes : une moyenne peut masquer une longue traîne de requêtes lentes. Pour l’utilisation, n’affichez que les champs disponibles et segmentez par modèle, version ou type de requête lorsque cela aide à repérer des variations.

Les alertes doivent signaler une condition qu’une personne peut examiner ou corriger. Une hausse du taux d’erreur au-delà du niveau habituel pendant une période définie peut justifier une alerte ; un échec isolé peut rester dans les journaux sans réveiller l’équipe. Les seuils dépendent du volume et des attentes liées au service : il n’est donc pas judicieux de fixer une valeur universelle sans disposer de données. Indiquez la fenêtre d’observation, le responsable et le lien vers la requête de diagnostic ou la procédure d’intervention.

Ne présentez pas une estimation de coût calculée à partir de l’utilisation déclarée comme un montant facturé. Pour une estimation interne, multipliez les unités disponibles par les prix et les règles applicables au compte et à la configuration concernés, puis étiquetez le résultat comme une estimation. Les montants réels peuvent dépendre de conditions impossibles à déduire uniquement de l’événement de réponse ; vérifiez toute réconciliation auprès de la documentation et des données de facturation officielles et actuelles du fournisseur concerné.

7. Analysez une requête en échec de manière reproductible

Lorsqu’un incident est signalé, commencez par l’identifiant de requête et vérifiez qu’il correspond au bon environnement et à la bonne période. Rassemblez les événements et classez-les par heure et par étape. Avant d’interpréter le résultat, vérifiez que la trace est complète : existe-t-il un événement de début et de fin ? Des segments liés aux outils manquent-ils ? Le journal indique-t-il une erreur terminale ou seulement une tentative échouée ? Une exécution incomplète peut sembler être une défaillance du modèle alors que les données n’ont simplement pas été enregistrées.

Reconstituez ensuite les versions et la séquence : version du code de l’application, version du prompt, modèle demandé et tout modèle effectivement utilisé qui a pu être observé, nombre de tentatives, outils et états. Comparez la durée totale à la somme des étapes, en tenant compte du travail local, des files d’attente et des temps non instrumentés. Si la somme ne correspond pas, consignez l’écart comme une lacune de télémétrie, et non comme la preuve d’une cause.

Enfin, distinguez les faits des hypothèses. Un timeout du fournisseur peut être documenté comme résultat d’une tentative, mais il ne prouve pas à lui seul pourquoi le timeout s’est produit. Un outil lent peut expliquer une partie du temps mesuré, sans nécessairement expliquer le comportement final. Notez ce qui est établi, ce qui manque et quelle vérification permettrait de départager les hypothèses. Cette méthode évite d’attribuer une cause que les journaux ne démontrent pas.

8. Vérifiez l’instrumentation et étendez-la par étapes

L’instrumentation doit elle aussi être testée : une application peut fonctionner tout en perdant des identifiants, en omettant l’événement de clôture ou en enregistrant des données qui auraient dû être rédigées. Effectuez des tests contrôlés pour les réussites, les erreurs, les timeouts, les nouvelles tentatives et les appels à des outils. Pour chaque cas, vérifiez toute la séquence, de l’événement d’entrée au résultat final, ainsi que les autorisations et la rédaction avant l’exportation.

Commencez par un parcours de production limité et vérifiez que les requêtes de diagnostic répondent à de vraies questions. Contrôlez le volume généré et assurez-vous que l’équipe peut retrouver une requête sans devoir effectuer des recherches manuelles dans plusieurs systèmes. Ajustez la sélection des événements et la durée de conservation avant d’étendre l’instrumentation. L’objectif n’est pas de maximiser le volume de télémétrie, mais de conserver des éléments suffisants et consultables pour exploiter le système.

Les conventions de télémétrie et les champs d’utilisation des API peuvent évoluer. Versionnez votre schéma interne et validez les adaptateurs lors de toute modification du SDK, de l’API ou de la configuration. Si le fournisseur modifie une réponse, la couche de normalisation doit pouvoir s’adapter sans que tous les tableaux de bord et toutes les requêtes dépendent des noms de champs externes. Les bonnes pratiques générales d’observabilité peuvent aider à organiser les signaux et les traces ; elles ne remplacent pas la documentation technique primaire pour connaître les champs ou les règles de facturation d’un fournisseur précis.

Poursuivre l’exploration

Corrections et transparence

Si vous repérez une information incorrecte ou obsolète, envoyez-nous la page et la source à vérifier.