Observabilité et OpenTelemetry
Šiame puslapyje
Mis à jour le 2 novembre 2026 sur la base du SDK
mistralai3.7.0 : les méthodes de trace se trouvent sousclient.workflows.executions; leurs versions asynchrones portent le suffixe_async(attendre la version synchrone échoue),execution_idest passé comme argument nommé, et les réponses exposentotel_trace_data,span_treeetevents(les champsspans,activity_countouerror_countlus par l’ancienne version n’existent plus) ;traceparentest passé comme paramètre d’exécution, car l’en-tête HTTP est déprécié. Sources : Observabilité des workflows · client-python.
Pourquoi observer tes workflows
Un workflow en production peut enchaîner des dizaines d’activités, appeler plusieurs services externes et s’exécuter de quelques secondes à plusieurs jours. Sans observabilité, diagnostiquer un problème revient à chercher une aiguille dans une botte de foin : tu sais que l’exécution a échoué, mais pas à quelle étape, après combien de tentatives, ni si le coupable est ton code ou une API tierce. La plateforme Workflows de Mistral intègre nativement OpenTelemetry pour répondre à cette question : chaque activité, chaque erreur et chaque durée est enregistrée sous forme de span dans une trace distribuée, sans aucune instrumentation de ta part.
Deux concepts structurent ce modèle. La trace représente le parcours complet d’une exécution, du déclencheur initial au résultat final. Le span, quant à lui, est une opération individuelle au sein de cette trace : chaque activité en génère automatiquement un, portant son nom, ses heures de début et de fin, sa durée d’exécution, son statut (succès ou erreur) et tous attributs personnalisés. Ces spans forment une hiérarchie — le span du workflow est le parent, et les spans des activités sont ses enfants — qui reproduit la structure complète de l’exécution.
Nomme tes activités pour la lisibilité
Le paramètre name du décorateur d’activité détermine l’étiquette qui apparaît dans les traces. C’est un investissement de dix secondes lors de l’écriture qui te fera gagner beaucoup de temps lors d’un incident.
import mistralai.workflows as workflows
@workflows.activity(name="Extract source text")
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text}
@workflows.activity(name="Mistral sentiment analysis")
async def analyser_sentiment(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Analyze the sentiment."},
{"role": "user", "content": texte}
]
)
return {"sentiment": response.choices[0].message.content}
@workflows.activity(name="Send email notification")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
# ...
return {"status": "sent"}
Mets-toi à la place de l’ingénieur de garde qui ouvre une vue de trace à 3 heures du matin. Entre fetch_user_data et « Retrieve user profile », ce dernier est immédiatement compréhensible, même pour quelqu’un qui n’a jamais lu ce code.
Récupérer les traces programmatiquement
Le SDK expose trois méthodes d’accès sous client.workflows.executions ; leurs versions asynchrones portent le suffixe _async. La première renvoie des données OpenTelemetry brutes — spans, durées, attributs, relations parent-enfant — te permettant de les réingérer dans ton propre outil d’observabilité (Jaeger, Grafana Tempo, etc.).
from mistralai.client import Mistral
client = Mistral()
# Données OpenTelemetry brutes pour l'exécution
trace = await client.workflows.executions.get_workflow_execution_trace_otel_async(
execution_id="exec_abc123def456"
)
print(f"OTel Trace: {trace.otel_trace_id}")
otel_data = trace.otel_trace_data # Trace complète, à réexporter vers ton backend
Lorsque tu veux principalement savoir si l’exécution a réussi et combien de temps elle a pris, le résumé suffit. Il inclut le statut, la durée totale et l’arborescence des spans, que tu peux parcourir récursivement :
summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
execution_id="exec_abc123def456"
)
print(f"Workflow: {summary.workflow_name} — status {summary.status}")
print(f"Total duration: {summary.total_duration_ms} ms")
def display(span, depth=0):
end = span.end_time_unix_nano or span.start_time_unix_nano
duration_ms = (end - span.start_time_unix_nano) / 1e6
print(f"{' ' * depth}{span.name}: {duration_ms:.0f} ms, {len(span.events)} event(s)")
for child in span.children or []:
display(child, depth + 1)
if summary.span_tree:
display(summary.span_tree)
La troisième méthode renvoie une liste chronologique des événements d’exécution :
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Exclure les événements internes de la plateforme
)
for event in response.events or []:
print(event)
Le paramètre include_internal_events=False filtre les événements techniques de la plateforme, ne conservant que ceux de ton workflow et de tes activités. Sur un workflow légèrement long, la différence de lisibilité est considérable. Pour les journaux eux-mêmes — ceux affichés dans Studio — get_workflow_execution_logs les renvoie page par page.
Maîtriser l’échantillonnage
Par défaut, toutes les traces sont exportées : le worker échantillonne à 100 %. Pour définir l’ID de trace ou contrôler l’échantillonnage d’une exécution, passe un traceparent au format W3C dans le corps de la requête d’exécution. Le worker utilise un échantillonneur basé sur le parent : il suit ta décision, portée par le dernier champ (01 pour collecter, 00 pour ne pas collecter).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
Les SDK Mistral font cela automatiquement : à chaque exécution, ils transmettent le traceparent du span actuel. Passer traceparent dans un en-tête HTTP est toujours accepté mais déprécié, car un en-tête peut être réécrit en transit ; utilise plutôt le paramètre.
Surveiller en production
Cinq indicateurs suffisent pour garder un workflow sous contrôle : le taux de réussite, c’est-à-dire le pourcentage d’exécutions se terminant sans erreur ; la durée moyenne d’une exécution complète ; les durées P95 et P99, qui révèlent les exécutions les plus lentes que la moyenne masque ; le taux de retry par activité, dont la hausse soudaine trahit un service externe instable bien avant que le taux de réussite ne se dégrade ; et enfin, l’identification de l’activité la plus lente, ton goulot d’étranglement.
Puisque les traces respectent la norme OpenTelemetry, rien ne t’oblige à les consulter depuis le SDK : elles peuvent être exportées vers Datadog via son collecteur OTel, vers Grafana et Tempo par le même mécanisme, vers Jaeger pour la visualisation de traces distribuées, ou vers New Relic via son exporteur dédié. Tes workflows rejoignent ainsi le tableau de bord où vit déjà le reste de ton infrastructure.
Déboguer un workflow en échec
Face à un échec, une procédure méthodique évite les conjectures.
- Récupère l’ID d’exécution depuis les journaux ou la réponse de l’API
- Consulte le résumé de la trace pour connaître le statut et repérer l’activité défaillante dans l’arborescence des spans
- Examine les événements détaillés pour comprendre la séquence ayant mené à l’erreur
- Vérifie les retries : l’activité a-t-elle été redémarrée ? Combien de fois ?
- Analyse le message d’erreur : timeout, erreur réseau, erreur métier ?
Les deux premières étapes peuvent être scriptées en quelques lignes, en utilisant la fonction display vue plus haut, te donnant un outil de diagnostic réutilisable.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Étape 1 : Résumé et arborescence des spans
summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
print(f"Status: {summary.status}")
if summary.span_tree:
display(summary.span_tree)
# Étape 2 : Événements de ton code, dans l'ordre
response = await executions.get_workflow_execution_trace_events_async(
execution_id=execution_id,
include_internal_events=False,
)
for event in response.events or []:
print(event)
Le nombre de tentatives mérite une attention particulière : une activité qui échoue dès la première tentative et une autre qui échoue après cinq retries racontent des histoires différentes et appellent des correctifs distincts.
Récapitulatif du cours
Félicitations, tu as terminé ce cours sur Mistral Workflows. Le parcours t’a mené de l’orchestration durable et du mécanisme d’event sourcing à l’installation du SDK (leçons 1 à 3), puis à la création d’activités, de workflows et de workers, leur déclenchement et leurs tests (leçons 4 à 7). Les leçons 8 à 11 ont exposé les contraintes de structuration — déterminisme, entrées Pydantic, timeouts, limitations — avant d’ouvrir sur des motifs avancés de parallélisme et de continuation. Les trois dernières ont couvert les politiques de retry, l’exigence d’I/O asynchrone et l’observabilité avec OpenTelemetry.
La plateforme est en Public Preview : les API et fonctionnalités peuvent évoluer. Consulte régulièrement la documentation officielle sur docs.mistral.ai/workflows pour suivre les mises à jour.
Svarbiausi punktai
- Chaque activité génère automatiquement des spans OpenTelemetry avec nom, durée et statut
- Nomme tes activités avec le paramètre
namepour faciliter le débogage - Trois méthodes pour accéder aux traces, sous
client.workflows.executions: OTel brut, résumé (statut, durée, arborescence des spans) et événements détaillés - L’échantillonnage est contrôlé par le paramètre
traceparentde l’exécution (100 % par défaut ; l’en-tête HTTP est déprécié) - En production, surveille le taux de réussite, la durée et le taux de retry
- Les traces OTel standard sont exportables vers Datadog, Grafana, Jaeger ou New Relic
Teste tes connaissances
Workflows durables : règles du moteur avant la production.
1. Que garantit la plateforme Mistral Workflows ?
Réponse : La durabilité : un workflow survit aux pannes et reprend là où il s’est arrêté — l’orchestration de longue durée devient fiable par conception.
2. Activité, workflow, worker : qui fait quoi ?
Réponse : L’activité est l’unité de travail (appel externe, calcul), le workflow orchestre les activités, le worker exécute — la séparation qui permet la reprise et la mise à l’échelle.
3. Qu'impose la règle de déterminisme ?
Réponse : Le code du workflow doit être rejouable à l’identique : pas d’aléatoire ni d’accès direct à l’horloge dans l’orchestration — les effets non déterministes vivent dans les activités.
4. Comment les échecs transitoires sont-ils gérés ?
Réponse : Via la politique de retry des activités (tentatives, backoff) et les timeouts — l’échec est un cas normal, géré de manière déclarative plutôt que manuelle.
5. Qu'apporte l'intégration OpenTelemetry ?
Réponse : Une observabilité standard : traces d’exécution, métriques et corrélation avec le reste de ton système — essentiel pour exploiter des workflows en production.
Durabilité, déterminisme, retry, observabilité : quatre règles qui maintiennent les orchestrations de longue durée — le moteur gère le reste.