Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Megfigyelhetőség és OpenTelemetry

14. lecke 14 közül Frissítve 2026. november 2. Haladó
Ezen az oldalon
  1. Miért érdemes megfigyelned a workflowaidat?
  2. Nevezd el a tevékenységeket az olvashatóság érdekében
  3. Nyomok programozott lekérése
  4. A mintavételezés maîtrise-a
  5. Monitorozás éles környezetben
  6. Egy megbukott workflow debuggolása
  7. A kurzus összefoglalása
  8. Főbb megállapítások
  9. Teszteld a tudásodat

Frissítve: 2026. november 2. a mistralai SDK 3.7.0 verziója alapján: a nyomkövetési metódusok a client.workflows.executions alatt találhatók; aszinkron változataik _async utótagot viselnek (a szinkron verzió várakoztatása hibát okoz), az execution_id kulcsszóként kerül átadásra, a válaszok pedig tartalmazzák az otel_trace_data, span_tree és events mezőket (a régebbi verzió által olvasott spans, activity_count vagy error_count mezők már nem léteznek); a traceparent vé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.

  1. Szerezd meg a végrehajtási azonosítót (execution ID) a naplókból vagy az API válaszból
  2. 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
  3. Vizsgáld meg a részletes eseményeket a hibához vezető szekvencia megértéséhez
  4. Ellenőrizd az újrapróbálkozásokat: újraindult a tevékenység? Hányszor?
  5. 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 name paraméterrel a hibakeresés megkönnyítése érdekében
  • Három módszer a nyomok elérésére a client.workflows.executions alatt: nyers OTel, összefoglaló (állapot, időtartam, span fa) és részletes események
  • A mintavételezést a végrehajtás traceparent paramé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.