Aller au contenu
English

Appels d'outils, erreurs et nouvelles tentatives

  • Leçon 8
  • 35 min
  • Module 3 : Instrumenter le flux de travail

Où nous en sommes

Dans la dernière leçon, nous avons donné un span à chaque appel de modèle, avec ses jetons et le modèle qui a répondu. Mais le modèle ne fait que proposer. Les outils lisent les commandes et enregistrent les remboursements, et ils restent invisibles. Dans cette leçon, nous enregistrons chaque appel d'outil avec la structure de ses arguments, son statut, ses erreurs et ses nouvelles tentatives. Nous enregistrons aussi la clé d'idempotence qui rend un deuxième remboursement visible. Nous commençons par un virement bancaire qui semble bloqué.

Leçon 8 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditAppels d'outils, erreurs et nouvelles tentatives
Aperçu du cours

Ce que vous saurez faire

Donnez à chaque appel d’outil son propre span (intervalle d’exécution). Marquez-le comme une lecture ou une écriture, et enregistrez les noms de ses arguments, son statut et ses erreurs. Pour chaque écriture, enregistrez l’opération et la clé d’idempotence. Un deuxième remboursement devient alors visible dans la trace, avec la clé qui l’a causé.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 35 minutes

Ce que vous devez savoir

  • Les spans chat et votre utilitaire show_spans.py, de la leçon Appels de modèle et jetons.
  • Les outils du flux de travail sont ceux du cours Agents d’IA et orchestration des flux de travail : quatre lectures (get_order, get_customer_orders, get_payments, search_policy) et trois écritures (request_refund, reship_item, create_return_label). Une écriture se produit seulement après l’approbation d’une personne.
  • Le double remboursement de Un remboursement que personne ne peut expliquer : un délai d’attente dépassé, puis la nouvelle tentative naïve de Tomás.

Ce qu’il vous faut sur votre ordinateur

  • Le projet dans l’état laissé par la dernière leçon : 81 tests réussissent, et show_spans.py est dans le dossier du projet.
  • Un terminal dans observable-workflow, avec l’environnement virtuel actif.

Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows et Linux sont écrites, mais n’ont pas été exécutées.

Vous envoyez de l’argent à un ami dans l’application de votre banque. Vous appuyez sur Send (envoyer), et l’application affiche une roue qui tourne longtemps. Puis elle indique « No connection » (aucune connexion). L’argent est-il parti?

Si vous appuyez encore sur Send, votre ami pourrait recevoir l’argent deux fois. Une banque prudente empêche cela. Chaque virement reçoit un numéro de référence au départ. Si la même référence arrive deux fois, la banque paie une fois et répond « already done » (déjà effectué). Avant de réessayer, vous pouvez aussi regarder votre compte : le virement y figure-t-il?

Deux habitudes rendent cela sûr : une référence qui reste identique lors d’une nouvelle tentative, et une vérification avant de réessayer. Vérifier votre solde deux fois est sans danger. Envoyer de l’argent deux fois ne l’est pas. La banque traite donc les lectures et les écritures différemment.

Votre trace de T-80008 contient deux appels de modèle. Entre les deux, le modèle a demandé get_order, et le flux de travail a lu la commande. La trace montre un appel de modèle qui finit à 0,96 seconde et le suivant qui commence à cet instant. La lecture n’y figure pas.

Rejouez maintenant le double remboursement. La première commande propose un remboursement de 9,95, la deuxième l’approuve comme agent, et la troisième liste les changements. L’approbation simule le délai d’attente dépassé du service de paiement après le remboursement, puis la nouvelle tentative naïve de Tomás :

Fenêtre de terminal
python -m resolver run T-90104 --variant agent_structured --model chat-strong
python -m resolver approve T-90104-agent_structured-chat-strong-1 --as agent --name Sam --fault request_refund:timeout_after_write --naive-retry
python -m resolver changes
request_refund LK-793996: done (operation 797fbb5bbb9f8a7e, 2 call(s))
Status: done
Reply sent. Ticket: resolved.
… T-90104 request_refund LK-793996 9.95 RFD-LATE (operation 797fbb5bbb9f8a7e)
… T-90104 request_refund LK-793996 9.95 RFD-LATE (operation 797fbb5bbb9f8a7e-retry1)
2 change(s) in the practice database

Le résumé du flux de travail indique une opération, terminée, en deux appels. La base de données d’exercice contient deux remboursements de 9,95. Vos temps diffèrent. La décision est rejouée : c’est la proposition enregistrée de chat-strong dans le cours Agents d’IA et orchestration des flux de travail. Le délai d’attente dépassé et la nouvelle tentative sont simulés : un incident d’exercice que nous avons causé volontairement.

La première commande a aussi affiché la proposition, qui se termine par la commande approve (approuver) à saisir. Les commandes sont les mêmes dans PowerShell. Rien dans votre télémétrie ne montre les deux appels au service de paiement. Si un client se plaint, la trace dit « deux appels de modèle, une proposition », et rien sur l’argent.

Donnez à chaque appel d’outil son propre span, enfant de l’étape qui l’a effectué. Les conventions GenAI le nomment execute_tool {tool}, par exemple execute_tool get_order, avec le nom d’opération execute_tool et gen_ai.tool.name. Le flux de travail ajoute ses propres attributs, avec le préfixe larkfield. :

Attribut Exemple Pourquoi
larkfield.tool.kind read (lecture) ou write (écriture) Une lecture peut être répétée. Une écriture modifie l’argent ou les stocks.
larkfield.tool.arguments order_id Les noms des arguments, triés. Jamais leurs valeurs.
larkfield.order.id LK-793996 Un identifiant nécessaire à une enquête. C’est un identifiant, pas du texte libre.
larkfield.tool.status ok (réussite), not_found (introuvable), service_timeout (délai d’attente du service dépassé) Le résultat sous forme de code, jamais le résultat lui-même.
error.type service_timeout Le nom stable d’une erreur, avec le statut du span défini à ERROR (erreur).

Pourquoi les noms des arguments plutôt que leurs valeurs? L’outil search_policy prend un argument query, du texte libre provenant du modèle. Il peut contenir les mots du client. Les noms indiquent quel outil a été appelé correctement; les valeurs restent exclues. L’identifiant de commande est l’exception que nous avons choisie. C’est un identifiant, et toute question sur un remboursement commence par lui.

Un span d’écriture enregistre aussi les renseignements nécessaires à l’auditeur sur le changement, sous forme de nombres et de codes. Ce sont le montant, le code de motif (RFD-LATE), le SKU et la quantité. Il enregistre aussi trois éléments qui rendent les nouvelles tentatives visibles :

  • L’identifiant d’opération (larkfield.operation.id) : un identifiant pour « rembourser 9,95 sur LK-793996 dans cette exécution ». Il reste identique pour chaque tentative.
  • La clé d’idempotence (larkfield.idempotency_key) : la référence que le flux de travail envoie au service de paiement avec cet appel. Une opération est idempotente si l’effectuer deux fois produit le même effet que l’effectuer une fois. La clé permet au service de rendre le remboursement idempotent : deux fois la même clé, un seul remboursement.
  • La tentative (larkfield.attempt) : 1 pour la première tentative, 2 pour la suivante.

Un quatrième type de span, reconcile {tool}, enregistre ensuite la vérification avant une nouvelle tentative : « cette opération existe-t-elle déjà? », avec larkfield.reconcile.found.

Exemple détaillé : deux nouvelles tentatives, deux résultats

Section intitulée « Exemple détaillé : deux nouvelles tentatives, deux résultats »

Le service de paiement effectue le remboursement, et sa réponse n’arrive pas dans les 10 secondes. Le flux de travail ne peut pas savoir si le remboursement a eu lieu. Voici les deux façons de continuer :

Une séquence entre request_refund du flux de travail et le service de paiement. Le flux de travail envoie un remboursement de 9,95 sur LK-793996 avec la clé d'idempotence 797fbb5bbb9f8a7e. Le service effectue le remboursement, mais aucune réponse n'arrive dans les 10 secondes : le délai d'attente est dépassé. Le flux de travail ne peut pas savoir si le remboursement a eu lieu. Premier cas, la nouvelle tentative naïve, le raccourci de Tomás : le flux de travail renvoie le remboursement avec une nouvelle clé, 797fbb5bbb9f8a7e-retry1. Une nouvelle clé signifie un nouveau remboursement : le client est payé deux fois. Deuxième cas, la nouvelle tentative sûre : le flux de travail demande « l'opération 797fbb5bbb9f8a7e existe-t-elle? », et le service répond « trouvée : elle a eu lieu ». Aucune autre écriture n'a lieu.
Un délai d'attente dépassé, deux nouvelles tentatives : une nouvelle clé paie deux fois; une vérification de la même opération paie une fois.
Description textuelle du diagramme

Le flux de travail envoie le remboursement avec sa clé. Le service l’effectue, mais la réponse tarde : le délai d’attente est dépassé. Avec la nouvelle tentative naïve, le flux de travail renvoie le remboursement avec une nouvelle clé qui finit par -retry1. Le service voit un nouveau remboursement : le client est payé deux fois. Avec la nouvelle tentative sûre, le flux de travail demande d’abord au service si l’opération existe. Le service répond oui, donc aucune autre écriture n’a lieu.

Dans les spans, les deux résultats se présentent ainsi :

Nouvelle tentative naïve Nouvelle tentative sûre
Spans d’écriture 2 : tentative 1 timeout (délai d’attente dépassé, ERROR), tentative 2 done (terminée) 1 : tentative 1 timeout (ERROR)
Identifiant d’opération le même dans les deux : 797fbb5bbb9f8a7e 797fbb5bbb9f8a7e
Clé d’idempotence deux clés différentes : …8a7e et …8a7e-retry1 une clé
Span de vérification aucun reconcile request_refund, trouvée : vrai
Remboursements dans la base de données 2 1

La règle de lecture : une opération avec deux clés différentes et deux appels done ou timeout indique une possible double écriture. Une clé ne peut pas payer deux fois, car le service refuse une clé qu’il connaît déjà. Une nouvelle clé représente une nouvelle requête pour le service. Le module 4 transforme cette règle en recherche.

  1. Copiez les fichiers de cette leçon : le chemin de lecture (tools.py), le chemin d’écriture (execute.py), les marqueurs d’injection des données d’exercice et le test de télémétrie de l’instantané.

    Fenêtre de terminal
    S=../nextia-learning-labs/C31/snapshots/end-of-m03
    cp $S/resolver/tools.py $S/resolver/execute.py resolver/
    cp $S/data/injection_markers.json data/
    cp $S/tests/test_telemetry.py tests/
  2. Ouvrez resolver/tools.py et trouvez run_read. La fonction du cours Agents d’IA et orchestration des flux de travail s’appelle maintenant _run_read, sans autre changement. La nouvelle fonction run_read ouvre un span avec observe.tool_span(), appelle cette fonction et enregistre le résultat avec observe.read_result().

  3. Ouvrez resolver/execute.py et trouvez _attempt. Chaque appel d’écriture possède son propre span, avec l’identifiant d’opération, la clé (call_id) et le numéro de tentative. Trouvez naive: dans execute() : la nouvelle tentative naïve crée call_id = f"{op_id}-retry{op.attempts}", une nouvelle clé.

  4. Exécutez les tests : python -m pytest -q. La dernière ligne indique 81 passed, 1 deselected (81 réussis, 1 non sélectionné). Le nouveau fichier de test vérifie que le premier span d’outil est get_order avec les arguments order_id.

  5. Supprimez vos anciennes exécutions pour faciliter la lecture des prochaines sorties : supprimez le dossier work/ (PowerShell : Remove-Item -Recurse work).

  6. Exécutez T-80008 et lisez sa trace :

    Fenêtre de terminal
    python -m resolver run T-80008
    python -m obs trace T-80008
    Trace 1 01e7e7965e75f288a478bfc56e5fed11 … 2.1 s
    0.0 s |========================| 2.14 s invoke_agent support-resolver reply_only rule W1
    0.0 s |=========== | 0.96 s chat chat-small 2169 in / 21 out - tool_calls
    1.0 s | = | 0.00 s execute_tool get_order ok LK-581106
    1.0 s | ==============| 1.18 s chat chat-small 2411 in / 96 out - tool_calls

    La lecture se trouve entre les deux appels : le premier l’a demandée, et le second a utilisé son résultat.

Exercice guidé : le double remboursement dans la trace

Section intitulée « Exercice guidé : le double remboursement dans la trace »
  1. Exécutez de nouveau le double remboursement avec les deux commandes du problème ci-dessus : run, puis approve … --naive-retry.

  2. Lisez la trace : python -m obs trace T-90104.

    Run T-90104-agent_structured-chat-strong-1 | ticket T-90104 | chat-strong (agent_structured) | release 2.0.0 | language en
    2 model call(s), 1 read(s), 0 write call(s), 4586 tokens in, 265 out, US$0.00000
    Trace 1 e7b26f791153ccc4f5f9d6ba36cb140a … 6.6 s
    0.0 s |========================| 6.56 s invoke_agent support-resolver resolve rule W2
    0.0 s |========= | 2.39 s chat chat-strong 2160 in / 47 out - stop
    2.4 s | = | 0.00 s execute_tool get_order ok LK-793996
    2.4 s | ================| 4.17 s chat chat-strong 2426 in / 218 out - stop
    Outcome: waiting_approval

    Lisez la deuxième ligne : 0 write call(s) (0 appel d’écriture). Le résultat reste waiting_approval (en attente d’approbation), même si le remboursement a été payé deux fois.

  3. Trouvez les spans d’écriture dans le fichier : python show_spans.py request_refund.

    execute_tool request_refund trace 7162b31d span fcd69358 parent none
    gen_ai.operation.name = execute_tool
    gen_ai.tool.name = request_refund
    gen_ai.tool.type = function
    larkfield.tool.kind = write
    larkfield.tool.arguments = amount,order_id,reason_code,tool
    larkfield.order.id = LK-793996
    larkfield.operation.id = 797fbb5bbb9f8a7e
    larkfield.idempotency_key = 797fbb5bbb9f8a7e
    larkfield.attempt = 1
    larkfield.refund.amount = 9.95
    larkfield.refund.reason = RFD-LATE
    larkfield.write.outcome = timeout
    error.type = timeout
    execute_tool request_refund trace f23daaac span 81210460 parent none
    …
    larkfield.operation.id = 797fbb5bbb9f8a7e
    larkfield.idempotency_key = 797fbb5bbb9f8a7e-retry1
    larkfield.attempt = 2
    larkfield.refund.amount = 9.95
    larkfield.refund.reason = RFD-LATE
    larkfield.write.outcome = done

    Le … représente les sept mêmes premières lignes. Vos identifiants de trace et de span diffèrent.

  4. Appliquez la règle de l’exemple détaillé. Une opération, 797fbb5bbb9f8a7e. Deux clés. La tentative 1 a dépassé le délai d’attente, la tentative 2 est terminée. C’est le double remboursement, et les clés désignent l’appel qui l’a causé : la nouvelle tentative.

  5. Lisez maintenant la première ligne de chaque span : parent none (aucun parent), et deux traces différentes.

Les spans contiennent tous les faits. Mais ils ne sont pas à leur place :

Trois diagrammes en cascade sur une échelle de 0 à 10 secondes. Trace 1, l'exécution : invoke_agent support-resolver pendant 6,6 secondes, avec chat chat-strong (2160 en entrée, 47 en sortie, stop), execute_tool get_order (ok) et chat chat-strong (2426 en entrée, 218 en sortie, stop). Trace 2, une écriture isolée, sans span parent, sans identifiant d'exécution et sans personne : execute_tool request_refund, ERROR timeout, clé finissant par 5bbb9f8a7e, durée de 10 secondes. Trace 3, également une écriture isolée : execute_tool request_refund, done, clé finissant par a7e-retry1.
Le double remboursement après le changement de cette leçon : chaque écriture a sa propre trace, sans parent, sans identifiant d'exécution et sans personne ayant approuvé.
Description textuelle du diagramme

La trace 1 est l’exécution, avec ses deux appels de modèle et sa lecture. Les deux appels de remboursement forment deux autres traces, chacune avec un span et sans parent. Ils contiennent l’identifiant d’opération et les clés, mais aucun identifiant d’exécution ni aucune personne ayant approuvé. obs trace regroupe les spans par exécution, donc il ne peut pas les afficher. Rien n’indique quelle personne les a autorisés.

Pourquoi? Les écritures se produisent dans python -m resolver approve, une deuxième commande, peut-être des heures plus tard. Aucun span de l’exécution n’est ouvert dans ce processus. Chaque span d’écriture commence donc une nouvelle trace. La prochaine leçon corrige cela.

Une lecture peut aussi échouer, et le modèle décide alors quoi faire de l’erreur. Supprimez encore work/ pour que obs trace trouve seulement cette exécution. Provoquez ensuite un dépassement du délai d’attente du service de commandes, une seule fois :

Fenêtre de terminal
python -m resolver run T-80008 --fault get_order:timeout
python -m obs trace T-80008
Note: Your request at step 2 differs from the recorded one (evidence 931a981a here, 783b17ea when recorded). The recorded decision is replayed and checked against your state.
…
0.0 s |========================| 12.14 s invoke_agent support-resolver reply_only rule W1
0.0 s |== | 0.96 s chat chat-small 2169 in / 21 out - tool_calls
1.0 s | ===================== | 10.00 s execute_tool get_order ERROR service_timeout LK-581106
11.0 s | ===| 1.18 s chat chat-small 2411 in / 96 out - tool_calls
Outcome: resolved

Le span de lecture indique une erreur, service_timeout. Il ajoute les 10 secondes d’attente simulées. L’exécution se termine tout de même avec resolved (résolu), et une réponse sur les dates de la commande. Lisez la note au-dessus. La deuxième requête n’était pas celle enregistrée, car le modèle a vu une erreur plutôt que la commande. La relecture a donc utilisé la décision enregistrée, qui avait été prise avec la commande. Le span de conversation l’indique : larkfield.replay = inexact (vérifiez avec python show_spans.py chat).

Cette exécution ne prouve donc pas ce qu’un modèle fait quand un délai d’attente est dépassé. Mais elle montre le cas que le module 4 appelle une erreur d’outil cachée : un span d’erreur, puis une réponse assurée. La trace la rend visible; la réponse seule ne le ferait jamais.

Changez une condition : le même délai d’attente dépassé après l’écriture, sans --naive-retry. Avant l’exécution, faites vos prédictions :

  • Combien de spans execute_tool request_refund, et avec quelles clés?
  • Quel autre span apparaît?
  • Combien de remboursements python -m resolver changes liste-t-il?

Supprimez ensuite work/ et lancez l’exécution :

Fenêtre de terminal
python -m resolver run T-90104 --variant agent_structured --model chat-strong
python -m resolver approve T-90104-agent_structured-chat-strong-1 --as agent --fault request_refund:timeout_after_write
python -m resolver changes
python show_spans.py request_refund
Le résultat de l’équipe du cours
request_refund LK-793996: done (operation 797fbb5bbb9f8a7e, 1 call(s))
Status: done
Reply sent. Ticket: resolved.
… T-90104 request_refund LK-793996 9.95 RFD-LATE (operation 797fbb5bbb9f8a7e)
1 change(s) in the practice database
execute_tool request_refund trace 8e052077 span 272c5858 parent none
…
larkfield.operation.id = 797fbb5bbb9f8a7e
larkfield.idempotency_key = 797fbb5bbb9f8a7e
larkfield.attempt = 1
larkfield.write.outcome = timeout
error.type = timeout
reconcile request_refund trace bb7ef0fc span 09aa3f15 parent none
larkfield.operation.id = 797fbb5bbb9f8a7e
larkfield.order.id = LK-793996
larkfield.reconcile.found = True

Un span d’écriture avec le délai d’attente dépassé, puis un span reconcile (vérification). Le flux de travail a interrogé le service sur l’opération 797fbb5bbb9f8a7e, et elle existait. Un seul remboursement. Le span de vérification est lui aussi seul dans sa propre trace, pour la même raison que les écritures.

Erreur courante

Deux clés, mais un seul changement

Symptôme : Tomás applique la règle de cette leçon à la semaine rejouée. L’exécution R-1014-024 (billet de soutien T-90604) montre une opération avec deux clés : une étiquette de retour, timeout puis done. Il signale une deuxième double écriture. Mais la base de données d’exercice de cette exécution contient une étiquette, pas deux.

Cause : la trace enregistre ce que le flux de travail a envoyé, pas ce que l’autre service a fait. Un délai d’attente dépassé avant ou après l’écriture donne le même span : write.outcome = timeout, car le flux de travail n’a jamais reçu de réponse. Dans R-1014-024, le premier appel a dépassé le délai d’attente avant l’écriture. Seule la nouvelle tentative a donc créé une étiquette.

Diagnostic : deux clés pour une opération signifient « peut-être deux fois ». Seul le système qui a effectué le changement le sait. Interrogez-le : le span reconcile de la nouvelle tentative sûre enregistre sa réponse, et python -m resolver changes liste les changements dans votre base de données d’exercice.

Rétablissement : gardez la clé sur chaque span d’écriture, car elle désigne l’appel. Mais décidez à partir du système de référence, par une vérification ou la piste d’audit du module 6. Une trace qui indique « possible double écriture » justifie une vérification, mais ne constitue pas une preuve.

Quand enregistrer les appels d’outils, et à quel coût

Section intitulée « Quand enregistrer les appels d’outils, et à quel coût »

Enregistrez chaque appel d’outil : lectures et écritures, réussites et erreurs. Un span d’outil est petit. Selon la mesure du cours, toute la télémétrie d’une exécution occupait 9,3 Ko, et son instrumentation coûtait 1,9 milliseconde. Les erreurs justifient de tous les garder : une trace échantillonnée qui omet la lecture échouée perd la preuve.

Enregistrez toujours la clé d’idempotence et l’identifiant d’opération sur chaque écriture. Ils coûtent deux courtes chaînes de caractères. Ils sont le seul moyen de relier un paiement dans un autre système à un appel d’une exécution. Enregistrez les noms des arguments, pas leurs valeurs, sauf si la valeur est un identifiant que vous avez choisi de garder. C’est le cas de l’identifiant de commande ici. Ajouter un identifiant à un span est une décision : notez pourquoi.

Le flux de travail marque aussi une lecture dont le résultat contient une instruction injectée (larkfield.input.injection). Les données d’exercice connaissent ces résultats, contrairement aux systèmes réels. Le module 4 utilise ce marqueur pour trouver les exécutions qui ont suivi une instruction injectée.

Vérifiez votre compréhension

Deux spans d'écriture d'une même exécution ont tous deux larkfield.operation.id = 797fbb5bbb9f8a7e. L'un a la clé 797fbb5bbb9f8a7e et le résultat timeout; l'autre a la clé 797fbb5bbb9f8a7e-retry1 et le résultat done. Que s'est-il passé, que ne pouvez-vous pas savoir à partir des spans, et comment le découvrir?

Afficher la réponse

Le flux de travail a tenté le même remboursement deux fois. Le premier appel a dépassé le délai, sans que le flux de travail sache si le remboursement avait eu lieu. La nouvelle tentative utilisait une nouvelle clé. Le service de paiement l’a donc traitée comme un nouveau remboursement et l’a effectué. Les spans seuls ne permettent pas de savoir si le premier appel a effectué un remboursement. Un dépassement du délai avant l’écriture et un dépassement après l’écriture semblent identiques. Consultez le système de référence : une réconciliation de l’opération, les changements dans la base de données d’exercice ou, plus tard, la piste d’audit. Pour T-90104, avec le dépassement du délai après l’écriture, la base de données indique deux remboursements.

Vérifiez votre compréhension

Pourquoi le span search_policy enregistre-t-il larkfield.tool.arguments = query plutôt que la requête elle-même, alors que le span get_order conserve l'identifiant de commande?

Afficher la réponse

La requête est du texte libre rédigé par le modèle. Elle peut contenir les mots du client ou des données personnelles. Le nom de l’argument suffit pour voir que l’outil a été appelé correctement. Larkfield a choisi de conserver l’identifiant de commande. Il ne contient aucun texte personnel, et toute question sur un remboursement commence par la commande. Il faut décider, pour chaque attribut, si sa valeur doit être conservée dans un span.

Vérifiez votre compréhension

Vérification pratique : dans votre télémétrie de la nouvelle tentative naïve, montrez les deux spans d'écriture. Dites lequel a effectué le deuxième remboursement et pourquoi il n'a pas été refusé.

Afficher la réponse

Exécutez python show_spans.py request_refund après l’approbation de la nouvelle tentative naïve. Le span avec larkfield.attempt = 2, larkfield.idempotency_key = 797fbb5bbb9f8a7e-retry1 et larkfield.write.outcome = done a effectué le deuxième remboursement. Le premier appel (tentative 1, clé 797fbb5bbb9f8a7e) avait déjà effectué le remboursement, et le dépassement du délai est survenu après l’écriture. Le service n’a pas refusé la nouvelle tentative, car une nouvelle clé représente une nouvelle requête pour lui. Il reconnaît une répétition seulement quand la même clé est utilisée deux fois.

Récapitulatif

  • Un span execute_tool {tool} par appel d’outil, marqué read (lecture) ou write (écriture), avec les noms des arguments, un code d’état et error.type en cas d’erreur.
  • Pour chaque écriture : l’identifiant d’opération (le même pour chaque tentative), la clé d’idempotence (la référence envoyée avec cet appel) et la tentative. Une opération avec deux clés peut indiquer une double écriture.
  • Un span reconcile (réconciliation) enregistre la vérification avant une nouvelle tentative, ainsi que sa réponse.
  • Une trace enregistre ce que le flux de travail a envoyé, pas ce que l’autre système a fait. Un dépassement du délai avant l’écriture et un dépassement après l’écriture semblent identiques.

Votre projet maintenant : les fichiers de la dernière leçon, plus tools.py, execute.py, data/injection_markers.json et tests/test_telemetry.py de l’instantané, avec 81 tests qui réussissent. Chaque appel d’outil a un span. Mais chaque écriture a sa propre trace, sans identifiant d’exécution ni personne associée. Rien n’indique qui l’a approuvée, ni combien de temps l’exécution a attendu. Ensuite, vous relierez l’approbation et les écritures à l’exécution.

Leçon suivante : Approbations, personnes et temps d'attente