Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Observabilité et OpenTelemetry

Lektion 14 af 14 Opdateret 2. november 2026 Avanceret
På denne side
  1. Pourquoi observer tes workflows
  2. Nomme tes activités pour la lisibilité
  3. Récupérer les traces par programme
  4. Maîtriser l’échantillonnage
  5. Surveiller en production
  6. Déboguer un workflow en échec
  7. Résumé du cours
  8. Vigtige pointer
  9. Teste tes connaissances

Mis à jour le 2 novembre 2026 sur la base du SDK mistralai 3.7.0 : les méthodes de trace se trouvent sous client.workflows.executions ; leurs versions asynchrones portent le suffixe _async (attendre la version synchrone échoue), execution_id est passé comme argument nommé, et les réponses exposent otel_trace_data, span_tree et events (les champs spans, activity_count ou error_count lus par l’ancienne version n’existent plus) ; traceparent est 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 par programme

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.

  1. Récupère l’ID d’exécution depuis les journaux ou la réponse de l’API
  2. Consulte le résumé de la trace pour connaître le statut et repérer l’activité défaillante dans l’arborescence des spans
  3. Examine les événements détaillés pour comprendre la séquence ayant mené à l’erreur
  4. Vérifie les retries : l’activité a-t-elle été redémarrée ? Combien de fois ?
  5. 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ésumé 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 modèles avancés de parallélisme et de continuation. Les trois dernières ont couvert les politiques de retry, l’exigence d’I/O asynchrones 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.

Vigtige pointer

  • Chaque activité génère automatiquement des spans OpenTelemetry avec nom, durée et statut
  • Nomme tes activités avec le paramètre name pour 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 traceparent de 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.