Observabilität und OpenTelemetry — Mistral Workflows: Dauerhafte Orchestrierung

Aktualisiert am 2. November 2026 basierend auf dem mistralai SDK 3.7.0: Trace-Methoden befinden sich unter client.workflows.executions; ihre asynchronen Versionen tragen den Suffix _async (das Abwarten der synchronen Version schlägt fehl), execution_id wird als Schlüsselwortargument übergeben, und Antworten geben otel_trace_data, span_tree und events aus (die Felder spans, activity_count oder error_count, die die ältere Version las, existieren nicht mehr); traceparent wird als Ausführungsparameter übergeben, da das HTTP-Header deprecated ist. Quellen: Workflow-Observabilität · client-python.

Warum Sie Ihre Workflows beobachten müssen

Ein Workflow in der Produktion kann Dutzende von Aktivitäten verkettend, mehrere externe Dienste aufrufen und von wenigen Sekunden bis zu mehreren Tagen laufen. Ohne Observabilität ist die Diagnose eines Problems wie das Suchen einer Nadel im Heuhaufen: Sie wissen, dass die Ausführung fehlgeschlagen ist, aber nicht an welchem Schritt, nach wie vielen Versuchen oder ob der Übeltäter Ihr Code oder eine Drittanbieter-API ist. Die Mistral Workflows-Plattform integriert OpenTelemetry nativ, um diese Frage zu beantworten: Jede Aktivität, jeder Fehler und jede Dauer wird als Span in einer verteilten Spur aufgezeichnet, ohne dass Sie Instrumentierung vornehmen müssen.

Zwei Konzepte strukturieren dieses Modell. Die Spur (Trace) repräsentiert die gesamte Reise einer Ausführung, vom initialen Auslöser bis zum Endergebnis. Der Span hingegen ist eine einzelne Operation innerhalb dieser Spur: Jede Aktivität generiert automatisch einen, der ihren Namen, Start- und Endzeiten, die Ausführungszeit, den Status (Erfolg oder Fehler) und beliebige benutzerdefinierte Attribute trägt. Diese Späne bilden eine Hierarchie – der Workflow-Span ist der Elternelement, und die Aktivitäts-Späne sind seine Kinder – was die vollständige Struktur der Ausführung reproduziert.

Aktivitäten für Lesbarkeit benennen

Der name-Parameter des Aktivitäts-Decorators bestimmt das Label, das in Spuren erscheint. Es ist eine zehnsекündige Investition beim Schreiben, die Ihnen viel Zeit während eines Vorfalls sparen wird.

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"}

Stellen Sie sich den eingewechselten Ingenieur vor, der um 3 Uhr morgens eine Spuransicht öffnet. Zwischen fetch_user_data und “Retrieve user profile” ist Letzteres sofort verständlich, auch für jemanden, der diesen Code noch nie gelesen hat.

Spuren programmatisch abrufen

Das SDK stellt drei Zugriffsmethoden unter client.workflows.executions bereit; ihre asynchronen Versionen tragen den Suffix _async. Die erste gibt rohe OpenTelemetry-Daten zurück – Späne, Dauern, Attribute, Eltern-Kind-Beziehungen – und ermöglicht es Ihnen, diese in Ihr eigenes Observability-Tool (Jaeger, Grafana Tempo usw.) neu einzulesen.

from mistralai.client import Mistral

client = Mistral()

# Rohe OpenTelemetry-Daten für die Ausführung
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  # Vollständige Spur, zum Neuausfuhren an Ihr Backend

Wenn Sie hauptsächlich wissen wollen, ob die Ausführung erfolgreich war und wie lange sie dauerte, reicht die Zusammenfassung. Sie enthält den Status, die Gesamtdauer und den Span-Baum, den Sie rekursiv durchlaufen können:

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)

Die dritte Methode gibt eine chronologische Liste von Ausführungsevents zurück:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Interne Plattform-Events ausschließen
)

for event in response.events or []:
    print(event)

Der Parameter include_internal_events=False filtert technische Plattform-Events heraus und behält nur die von Ihrem Workflow und Ihren Aktivitäten bei. Bei einem etwas längeren Workflow ist der Unterschied in der Lesbarkeit beträchtlich. Für die Logs selbst – die in Studio angezeigt werden – gibt get_workflow_execution_logs sie Seite für Seite zurück.

Sampling beherrschen

Standardmäßig werden alle Spuren exportiert: Der Worker sampelt zu 100 %. Um die Trace-ID festzulegen oder das Sampling für eine Ausführung zu steuern, geben Sie ein W3C-formatiertes traceparent im Körper der Ausführungsanfrage an. Der Worker verwendet einen Eltern-basierten Sampler: Er folgt Ihrer Entscheidung, die im letzten Feld (01 zum Sammeln, 00 zum Nicht-Sammeln) getragen wird.

execution = await client.workflows.execute_workflow_async(
    workflow_identifier="my_workflow",
    input={"data": "test"},
    traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)

Mistral SDKs tun dies automatisch: Mit jeder Ausführung übermitteln sie das traceparent des aktuellen Spans. Das Übergeben von traceparent in einem HTTP-Header wird zwar noch akzeptiert, ist aber deprecated, da ein Header während der Übertragung umgeschrieben werden kann; verwenden Sie stattdessen den Parameter.

In der Produktion überwachen

Fünf Indikatoren reichen aus, um einen Workflow unter Kontrolle zu halten: die Erfolgsquote, also der Prozentsatz der Ausführungen, die ohne Fehler abgeschlossen werden; die durchschnittliche Dauer einer vollständigen Ausführung; die P95- und P99-Dauern, die die langsamsten Ausführungen enthüllen, die der Durchschnitt verbirgt; die Wiederholungsrate pro Aktivität, deren plötzlicher Anstieg ein instabiles externes Dienst gut vor dem Verschlechterung der Erfolgsrate verrät; und schließlich die Identifizierung der langsamsten Aktivität, Ihres Flaschenhalses.

Da Spuren dem OpenTelemetry-Standard entsprechen, besteht keine Notwendigkeit, sie vom SDK aus abzufragen: Sie können über den OTel-Collector an Datadog, über denselben Mechanismus an Grafana und Tempo, an Jaeger zur Visualisierung verteilter Spuren oder an New Relic über dessen dedizierten Exporter exportiert werden. Ihre Workflows schließen sich damit dem Dashboard an, in dem der Rest Ihrer Infrastruktur bereits lebt.

Einen fehlgeschlagenen Workflow debuggen

Angesichts eines Fehlers vermeidet ein methodisches Vorgehen das Raten.

Die Ausführungs-ID aus den Logs oder der API-Antwort abrufen
Die Spur-Zusammenfassung konsultieren, um den Status zu kennen und die fehlerhafte Aktivität im Span-Baum zu lokalisieren
Detaillierte Events untersuchen, um die Sequenz zu verstehen, die zum Fehler geführt hat
Wiederholungen prüfen: Wurde die Aktivität neu gestartet? Wie oft?
Die Fehlermeldung analysieren: Timeout, Netzwerkfehler, Geschäftsfehler?

Die ersten beiden Schritte können in wenigen Zeilen skriptet werden, unter Verwendung der display-Funktion, die oben gesehen wurde, und geben Ihnen ein wiederverwendbares Diagnose-Tool.

async def diagnose_failure(execution_id: str):
    client = Mistral()
    executions = client.workflows.executions

    # Schritt 1: Zusammenfassung und Span-Baum
    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)

    # Schritt 2: Events aus Ihrem Code, in Reihenfolge
    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)

Die Anzahl der Versuche verdient besondere Aufmerksamkeit: Eine Aktivität, die beim ersten Versuch fehlschlägt, und eine, die nach fünf Wiederholungen fehlschlägt, erzählen unterschiedliche Geschichten und erfordern unterschiedliche Lösungen.

Kurszusammenfassung

Glückwunsch, Sie haben diesen Kurs über Mistral Workflows abgeschlossen. Die Reise führte Sie von der dauerhaften Orchestrierung und dem Event-Sourcing-Mechanismus über die Installation des SDKs (Lektionen 1 bis 3) hin zum Erstellen von Aktivitäten, Workflows und Workern, dem Auslösen und Testen (Lektionen 4 bis 7). Lektionen 8 bis 11 legten die strukturbildenden Einschränkungen fest – Determinismus, Pydantic-Eingaben, Timeouts, Einschränkungen – bevor sie zu fortgeschrittenen Mustern der Parallelität und Fortsetzung übergingen. Die letzten drei behandelten Wiederholungsrichtlinien, die Anforderung für asynchronen I/O und Observabilität mit OpenTelemetry.

Die Plattform befindet sich im Public Preview: APIs und Funktionen können sich weiterentwickeln. Prüfen Sie die offizielle Dokumentation regelmäßig unter docs.mistral.ai/workflows, um Updates zu verfolgen.

Wichtige Erkenntnisse

Jede Aktivität generiert automatisch OpenTelemetry-Späne mit Name, Dauer und Status
Benennen Sie Ihre Aktivitäten mit dem name-Parameter, um das Debugging zu erleichtern
Drei Methoden zum Zugriff auf Spuren, unter client.workflows.executions: rohes OTel, Zusammenfassung (Status, Dauer, Span-Baum) und detaillierte Events
Sampling wird durch den traceparent-Parameter der Ausführung gesteuert (100 % standardmäßig; das HTTP-Header ist deprecated)
In der Produktion die Erfolgsquote, Dauer und Wiederholungsrate überwachen
Standard-OTel-Spuren können an Datadog, Grafana, Jaeger oder New Relik exportiert werden

Testen Sie Ihr Wissen

Dauerhafte Workflows: Motorregeln vor der Produktion.

1. Was garantiert die Mistral Workflows-Plattform?

Antwort: Dauerhaftigkeit: Ein Workflow überlebt Ausfälle und setzt dort fort, wo er aufgehört hat – langfristige Orchestrierung wird durch Design zuverlässig.

2. Aktivität, Workflow, Worker: Wer macht was?

Antwort: Die Aktivität ist die Arbeitseinheit (externe Aufrufe, Berechnung), der Workflow orchestriert Aktivitäten, der Worker führt aus – die Trennung, die Wiederaufnahme und Skalierung ermöglicht.

3. Was verlangt die Determinismus-Regel?

Antwort: Workflow-Code muss identisch wiederspielbar sein: Keine Zufälligkeit oder direkter Zugriff auf die Uhrzeit in der Orchestrierung – nicht-deterministische Effekte leben in Aktivitäten.

4. Wie werden vorübergehende Ausfälle behandelt?

Antwort: Über die Aktivitäts-Wiederholungsrichtlinie (Versuche, Backoff) und Timeouts – ein Fehler ist ein normaler Fall, der deklarativ statt manuell behandelt wird.

5. Was bringt die OpenTelemetry-Integration?

Antwort: Standard-Observabilität: Ausführungsspuren, Metriken und Korrelation mit dem Rest Ihres Systems – unerlässlich für den Betrieb von Workflows in der Produktion.

Dauerhaftigkeit, Determinismus, Wiederholung, Observabilität: Vier Regeln, die langfristige Orchestrierungen zusammenhalten – der Motor kümmert sich um den Rest.