Megfigyelhetőség és OpenTelemetry
Ezen az oldalon
Frissítve: 2026. november 2. a
mistralaiSDK 3.7.0 verziója alapján: a nyomkövetési metódusok aclient.workflows.executionsalatt találhatók; aszinkron változataik_asyncutótagot viselnek (a szinkron verzió várakoztatása hibát okoz), azexecution_idkulcsszóként kerül átadásra, a válaszok pedig tartalmazzák azotel_trace_data,span_treeéseventsmezőket (a régebbi verzió által olvasottspans,activity_countvagyerror_countmezők már nem léteznek); atraceparentvégrehajtási paraméterként kerül átadásra, mivel a HTTP fejléc használata elavult. Források: Workflow megfigyelhetőség · client-python.
Miért érdemes megfigyelned a workflowaidat?
Egy éles környezetben futó workflow tucatnyi tevékenységet láncolhat össze, több külső szolgáltatást hívhat meg, és futása néhány másodperctől több napig is tarthat. Megfigyelhetőség nélkül a hibakeresés olyan, mint tűt keresni a szénakazalban: tudod, hogy a végrehajtás megbukott, de azt nem, hogy melyik lépésnél, hány próbálkozás után, vagy hogy a hiba a te kódodban, esetleg egy harmadik féltől származó API-ban rejlik. A Mistral Workflows platform natívan integrálja az OpenTelemetryt, hogy választ adjon erre a kérdésre: minden tevékenység, minden hiba és minden időtartam rögzítésre kerül egy elosztott nyomként (distributed trace), anélkül, hogy neked bármit is instrumentálnod kellene.
Két fogalom strukturálja ezt a modellt. A nyom (trace) a végrehajtás teljes útját jelenti, a kezdeti triggerreltől a végeredményig. A span (szakasz) ezzel szemben egy egyedi művelet ezen a nyomvonalon belül: minden tevékenység automatikusan generál egyet, amely tartalmazza a nevét, a kezdő és befejező időpontot, a futási időt, az állapotot (sikeres vagy hiba), valamint minden egyedi attribútumot. Ezek a spanok hierarchiát alkotnak – a workflow span a szülő, a tevékenység spanok pedig a gyermekei –, amely pontosan leképezi a végrehajtás teljes szerkezetét.
Nevezd el a tevékenységeket az olvashatóság érdekében
A tevékenység dekorátor name paramétere határozza meg a nyomokban megjelenő címkét. Ez a kódírás során befektetett tíz másodperc rengeteg időt spórol meg neked egy incidens során.
import mistralai.workflows as workflows
@workflows.activity(name="Forrásszöveg kinyerése")
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 szentiment-elemzés")
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="E-mail értesítés küldése")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
# ...
return {"status": "sent"}
Helyezd magad az ügyeletes mérnök cipőjébe, aki hajnali 3-kor nyit meg egy nyomnézetet. A fetch_user_data és a „Felhasználói profil lekérése“ között az utóbbi azonnal érthető, még annak is, aki sosem olvasta ezt a kódot.
Nyomok programozott lekérése
Az SDK három hozzáférési módszert tesz elérhetővé a client.workflows.executions alatt; aszinkron változataik _async utótagot viselnek. Az első nyers OpenTelemetry adatokat ad vissza – spanokat, időtartamokat, attribútumokat, szülő-gyermek kapcsolatokat –, lehetővé téve, hogy ezeket újra betápláld a saját megfigyelő eszközödbe (Jaeger, Grafana Tempo stb.).
from mistralai.client import Mistral
client = Mistral()
# Nyers OpenTelemetry adatok a végrehajtáshoz
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 # Teljes nyom, exportálható a saját backendedhez
Ha elsősorban arra vagy kíváncsi, hogy a végrehajtás sikeres volt-e és mennyi ideig tartott, az összefoglaló (summary) elég. Ez tartalmazza az állapotot, a teljes időtartamot és a span fát, amelyet rekurzívan bejárhatsz:
summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
execution_id="exec_abc123def456"
)
print(f"Workflow: {summary.workflow_name} — állapot {summary.status}")
print(f"Teljes időtartam: {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)} esemény")
for child in span.children or []:
display(child, depth + 1)
if summary.span_tree:
display(summary.span_tree)
A harmadik módszer a végrehajtási események kronológiai listáját adja vissza:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Belső platform események kizárása
)
for event in response.events or []:
print(event)
Az include_internal_events=False paraméter kiszűri a technikai platform eseményeket, csak a workflowodhoz és a tevékenységeidhez tartozókat megtartva. Egy kicsit hosszabb workflow esetén az olvashatóságbeli különbség jelentős. Magukért a naplókért – amelyek a Stúdióban jelennek meg – a get_workflow_execution_logs lapozva adja vissza azokat.
A mintavételezés maîtrise-a
Alapértelmezetten minden nyom exportálásra kerül: a worker 100%-os mintavételezést végez. A nyom azonosító (trace ID) beállításához vagy egy végrehajtás mintavételezésének szabályozásához adj meg egy W3C formátumú traceparent értéket a végrehajtási kérés törzsében. A worker szülő-alapú mintavételezőt használ: követi a döntésedet, amelyet az utolsó mező hordoz (01 a gyűjtéshez, 00 a gyűjtés mellőzéséhez).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
A Mistral SDK-k ezt automatikusan végrehajtják: minden végrehajtással elküldik az aktuális span traceparent értékét. A traceparent HTTP fejlécben történő átadása még elfogadott, de elavult, mivel egy fejléc átírható átvitel közben; használd helyette a paramétert.
Monitorozás éles környezetben
Öt mutató elég ahhoz, hogy kordában tartsd a workflowodat: a sikerességi ráta, azaz a hibátlanul befejeződő végrehajtások százaléka; egy teljes végrehajtás átlagos időtartama; a P95 és P99 időtartamok, amelyek feltárják az átlag által elrejtett leglassúbb végrehajtásokat; a tevékenységenkénti újrapróbálkozási ráta, amelynek hirtelen emelkedése jóval a sikerességi ráta romlása előtt jelzi egy instabil külső szolgáltatást; és végül a leglassúbb tevékenység azonosítása, ami a szűk keresztmetszeted.
Mivel a nyomok megfelelnek az OpenTelemetry szabványnak, semmi sem kötelez arra, hogy az SDK-ból tekintsd meg őket: exportálhatók Datadogba az OTel kollektorán keresztül, ugyanígy Grafanába és Tempóba, Jaegerbe az elosztott nyomok vizualizálásához, vagy New Relicbe a dedikált exportálóján keresztül. Így a workflowjaid csatlakoznak ahhoz a műszerfalhoz, ahol a többi infrastruktúrád már él.
Egy megbukott workflow debuggolása
Hiba esetén egy módszeres eljárás elkerüli a találgatást.
- Szerezd meg a végrehajtási azonosítót (execution ID) a naplókból vagy az API válaszból
- Konzultáld a nyom összefoglalót az állapot megismeréséhez és a hibás tevékenység felfedezéséhez a span fában
- Vizsgáld meg a részletes eseményeket a hibához vezető szekvencia megértéséhez
- Ellenőrizd az újrapróbálkozásokat: újraindult a tevékenység? Hányszor?
- Elemezd a hibaüzenetet: időtúllépés, hálózati hiba, üzleti hiba?
Az első két lépés néhány sorral scriptelhető a fent látott display függvény használatával, így egy újrahasználható diagnosztikai eszközhöz jutsz.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# 1. lépés: Összefoglaló és span fa
summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
print(f"Állapot: {summary.status}")
if summary.span_tree:
display(summary.span_tree)
# 2. lépés: Események a kódodból, sorrendben
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)
A próbálkozások száma különös figyelmet érdemel: egy tevékenység, amely már az első próbálkozásra elbukik, és egy olyan, amely öt újrapróbálkozás után bukik meg, eltérő történetet mesél el, és eltérő javításokat igényel.
A kurzus összefoglalása
Gratulálunk, befejezted ezt a Mistral Workflowsról szóló kurzust. Az út a tartós orchestrációtól és az eseményforrásozás mechanizmusától az SDK telepítéséig vezetett (1–3. leckék), majd a tevékenységek, workflowk és workerek létrehozásán, indításán és tesztelésén keresztül (4–7. leckék). A 8–11. leckék lefektették a strukturális kényszereket – determinizmus, Pydantic bemenetek, időtúllépések, korlátozások –, mielőtt megnyílt volna az út a párhuzamosítás és folytatás haladó mintázatai felé. Az utolsó három lecke az újrapróbálkozási szabályzatokkal, az aszinkron I/O követelményével és az OpenTelemetryvel végzett megfigyelhetőséggel foglalkozott.
A platform Public Preview állapotban van: az API-k és funkciók változhatnak. Rendszeresen ellenőrizd a hivatalos dokumentációt a docs.mistral.ai/workflows címen, hogy kövesd a frissítéseket.
Főbb megállapítások
- Minden tevékenység automatikusan generál OpenTelemetry spanokat névvel, időtartammal és állapottal
- Nevezd el a tevékenységeidet a
nameparaméterrel a hibakeresés megkönnyítése érdekében - Három módszer a nyomok elérésére a
client.workflows.executionsalatt: nyers OTel, összefoglaló (állapot, időtartam, span fa) és részletes események - A mintavételezést a végrehajtás
traceparentparamétere szabályozza (alapértelmezetten 100%; a HTTP fejléc elavult) - Éles környezetben figyeld a sikerességi rátát, az időtartamot és az újrapróbálkozási rátát
- A szabványos OTel nyomok exportálhatók Datadogba, Grafanába, Jaegerbe vagy New Relicbe
Teszteld a tudásodat
Tartós workflowk: az engine szabályai az éles bevetés előtt.
1. Mit garantál a Mistral Workflows platform?
Válasz: Tartósságot: egy workflow túléli a hibákat, és ott folytatja, ahol abbahagyta – a hosszú ideig tartó orchestráció tervezésből fakadóan megbízhatóvá válik.
2. Tevékenység, workflow, worker: ki mit csinál?
Válasz: A tevékenység a munkavégzés egysége (külső hívás, számítás), a workflow orchestrálja a tevékenységeket, a worker pedig végrehajtja – ez a szétválasztás teszi lehetővé a folytatást és a skálázást.
3. Mit ír elő a determinizmus szabálya?
Válasz: A workflow kódnak azonos módon újrajátszhatónak kell lennie: nincs véletlenszerűség vagy közvetlen óra-hozzáférés az orchestrációban – a nem determinisztikus hatások a tevékenységekben élnek.
4. Hogyan kezeljük az átmeneti hibákat?
Válasz: A tevékenység újrapróbálkozási szabályzatán (kísérletek, backoff) és időtúllépéseken keresztül – a hiba normális eset, amelyet deklaratívan, nem pedig manuálisan kezelünk.
5. Mit hoz az OpenTelemetry integráció?
Válasz: Szabványos megfigyelhetőséget: végrehajtási nyomokat, metrikákat és korrelációt a rendszer többi részével – elengedhetetlen a workflowk éles környezetben történő üzemeltetéséhez.
Tartósság, determinizmus, újrapróbálkozás, megfigyelhetőség: négy szabály, amely összetartja a hosszú orchestrációkat – az engine intézi a többit.