Observabilitate și OpenTelemetry
Pe această pagină
Actualizat pe 2 noiembrie 2026 pe baza SDK-ului
mistralai3.7.0: metodele de trasare se află subclient.workflows.executions; versiunile lor asincrone poartă sufixul_async(așteptarea versiunii sincrone eșuează),execution_ideste transmis ca argument keyword, iar răspunsurile expunotel_trace_data,span_treeșievents(câmpurilespans,activity_countsauerror_countcitite de versiunea anterioară nu mai există);traceparenteste transmis ca parametru de execuție, deoarece header-ul HTTP este depreciat. Surse: Observabilitatea workflow-urilor · client-python.
De ce să vă observați workflow-urile
Un workflow în producție poate înlănțui zeci de activități, poate apela multiple servicii externe și poate rula de la câteva secunde până la câteva zile. Fără observabilitate, diagnosticarea unei probleme seamănă cu căutarea acului în carul cu fân: știți că execuția a eșuat, dar nu știți la ce pas, după câte încercări sau dacă vinovatul este codul dumneavoastră sau un API terț. Platforma Mistral Workflows integrează nativ OpenTelemetry pentru a răspunde la această întrebare: fiecare activitate, fiecare eroare și fiecare durată sunt înregistrate ca un span într-o urmă distribuită, fără a fi necesară nicio instrumentare din partea dumneavoastră.
Două concepte structurează acest model. Urmarea (trace) reprezintă întreaga călătorie a unei execuții, de la declanșatorul inițial până la rezultatul final. Span-ul, pe de altă parte, este o operație individuală în cadrul acelei urme: fiecare activitate generează automat unul, purtând numele său, orele de start și de sfârșit, durata execuției, starea (succes sau eroare) și orice atribute personalizate. Aceste span-uri formează o ierarhie – span-ul workflow-ului este părintele, iar span-urile activităților sunt copiii săi – care reproduce structura completă a execuției.
Denumiți activitățile pentru lizibilitate
Parametrul name al decoratorului de activitate determină eticheta care apare în urme. Este o investiție de zece secunde în timpul scrierii, care vă va economisi mult timp în timpul unui 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"}
Puneți-vă în locul inginerului de gardă care deschide o vizualizare a urmelor la ora 3 dimineața. Între fetch_user_data și „Retrieve user profile“, acesta din urmă este imediat inteligibil, chiar și pentru cineva care nu a citit niciodată acest cod.
Recuperați urmele programatic
SDK-ul expune trei metode de acces sub client.workflows.executions; versiunile lor asincrone poartă sufixul _async. Prima returnează date brute OpenTelemetry – span-uri, durate, atribute, relații părinte-copil – permițându-vă să le reingerați în propriul instrument de observabilitate (Jaeger, Grafana Tempo etc.).
from mistralai.client import Mistral
client = Mistral()
# Date brute OpenTelemetry pentru execuție
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 # Urmă completă, de reexportat către backend-ul dumneavoastră
Când doriți în principal să știți dacă execuția a reușit și cât a durat, rezumatul este suficient. Acesta include starea, durata totală și arborele de span-uri, pe care îl puteți parcurge recursiv:
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)
A treia metodă returnează o listă cronologică a evenimentelor de execuție:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Exclude evenimentele interne ale platformei
)
for event in response.events or []:
print(event)
Parametrul include_internal_events=False filtrează evenimentele tehnice ale platformei, păstrându-le doar pe cele din workflow-ul și activitățile dumneavoastră. La un workflow ușor lung, diferența de lizibilitate este considerabilă. Pentru jurnalele propriu-zise – cele afișate în Studio – get_workflow_execution_logs le returnează pagină cu pagină.
Stăpâniți eșantionarea
Implicit, toate urmele sunt exportate: worker-ul eșantionează la 100%. Pentru a seta ID-ul de urmă sau a controla eșantionarea pentru o execuție, transmiteți un traceparent în format W3C în corpul cererii de execuție. Worker-ul utilizează un eșantionor bazat pe părinte: acesta urmează decizia dumneavoastră, purtată de ultimul câmp (01 pentru colectare, 00 pentru non-colectare).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
SDK-urile Mistral fac acest lucru automat: la fiecare execuție, ele transmit traceparent al span-ului curent. Transmiterea traceparent într-un header HTTP este încă acceptată, dar depreciată, deoarece un header poate fi rescris în tranzit; utilizați în schimb parametrul.
Monitorizați în producție
Cinci indicatori sunt suficienți pentru a menține un workflow sub control: rata de succes, adică procentul de execuții care se termină fără eroare; durata medie a unei execuții complete; duratele P95 și P99, care relevă execuțiile cele mai lente pe care media le ascunde; rata de reîncercare per activitate, a cărei creștere bruscă trădează un serviciu extern instabil cu mult înainte ca rata de succes să se degradeze; și, în final, identificarea activității celei mai lente, gâtul de sticlă al dumneavoastră.
Deoarece urmele respectă standardul OpenTelemetry, nimic nu vă obligă să le consultați din SDK: ele pot fi exportate către Datadog prin colectorul său OTel, către Grafana și Tempo prin același mecanism, către Jaeger pentru vizualizarea urmelor distribuite sau către New Relic prin exportatorul său dedicat. Workflow-urile dumneavoastră se alătură astfel tabloului de bord în care trăiește deja restul infrastructurii dumneavoastră.
Depanarea unui workflow eșuat
În fața unui eșec, o procedură metodică evită ghicitorile.
- Recuperați ID-ul execuției din jurnale sau din răspunsul API
- Consultați rezumatul urmei pentru a cunoaște starea și a identifica activitatea defectuoasă în arborele de span-uri
- Examinați evenimentele detaliate pentru a înțelege secvența care a dus la eroare
- Verificați reîncercările: a fost activitatea repornită? De câte ori?
- Analizați mesajul de eroare: timeout, eroare de rețea, eroare de business?
Primii doi pași pot fi scriptați în câteva linii, folosind funcția display văzută mai sus, oferindu-vă un instrument de diagnostic reutilizabil.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Pasul 1: Rezumat și arbore de span-uri
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)
# Pasul 2: Evenimente din codul dumneavoastră, în ordine
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)
Numărul de încercări merită o atenție specială: o activitate care eșuează la prima încercare și una care eșuează după cinci reîncercări spun povești diferite și necesită remedieri diferite.
Recapitularea cursului
Felicitări, ați terminat acest curs despre Mistral Workflows. Călătoria v-a dus de la orchestrarea durabilă și mecanismul de event sourcing la instalarea SDK-ului (lecțiile 1 până la 3), apoi la crearea de activități, workflow-uri și workeri, declanșarea și testarea lor (lecțiile 4 până la 7). Lecțiile 8 până la 11 au expus constrângerile de structurare – determinism, intrări Pydantic, timeout-uri, limitări – înainte de a se deschide către modele avansate de paralelism și continuare. Ultimele trei au acoperit politicile de reîncercare, necesitatea I/O asincron și observabilitatea cu OpenTelemetry.
Platforma se află în Public Preview: API-urile și funcționalitățile pot evolua. Verificați regulat documentația oficială la docs.mistral.ai/workflows pentru a urmări actualizările.
Puncte cheie
- Fiecare activitate generează automat span-uri OpenTelemetry cu nume, durată și stare
- Denumiți-vă activitățile cu parametrul
namepentru a facilita depanarea - Trei metode de acces la urme, sub
client.workflows.executions: OTel brut, rezumat (stare, durată, arbore de span-uri) și evenimente detaliate - Eșantionarea este controlată de parametrul
traceparental execuției (100% implicit; header-ul HTTP este depreciat) - În producție, monitorizați rata de succes, durata și rata de reîncercare
- Urmele OTel standard sunt exportabile către Datadog, Grafana, Jaeger sau New Relic
Testați-vă cunoștințele
Workflow-uri durabile: regulile motorului înainte de producție.
1. Ce garantează platforma Mistral Workflows?
Răspuns: Durabilitate: un workflow supraviețuiește defecțiunilor și reia execuția de unde a rămas – orchestrarea de lungă durată devine fiabilă prin design.
2. Activitate, workflow, worker: cine face ce?
Răspuns: Activitatea este unitatea de lucru (apel extern, calcul), workflow-ul orchestrează activitățile, worker-ul execută – separarea care permite reluarea și scalarea.
3. Ce impune regula determinismului?
Răspuns: Codul workflow-ului trebuie să fie rejucabil identic: fără aleatoriu sau acces direct la ceas în orchestrare – efectele non-deterministe trăiesc în activități.
4. Cum sunt gestionate defecțiunile tranzitorii?
Răspuns: Prin politica de reîncercare a activității (încercări, backoff) și timeout-uri – eșecul este un caz normal, gestionat declarativ și nu manual.
5. Ce aduce integrarea OpenTelemetry?
Răspuns: Observabilitate standard: urme de execuție, metrici și corelare cu restul sistemului dumneavoastră – esențial pentru operarea workflow-urilor în producție.
Durabilitate, determinism, reîncercare, observabilitate: patru reguli care mențin orchestrările de lungă durată unite – motorul se ocupă de restul.