Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Vaadeldavus ja OpenTelemetry

Õppetund 14 / 14 Värskendatud 2. november 2026 Edasijõudnutele
Sellel lehel
  1. Miks oma workfloowe jälgida
  2. Nimeta tegevused loetavuse huvides
  3. Too jälitused programmiliselt kätte
  4. Valda proovivõttu
  5. Jälgi tootmises
  6. Silu ebaõnnestunud workflowd
  7. Kursuse kokkuvõte
  8. Peamised punktid
  9. Testi oma teadmisi

Uuendatud 2. novembril 2026, lähtudes mistralai SDK versioonist 3.7.0: jälituse meetodid asuvad moodulis client.workflows.executions; nende asünkroonsed versioonid kannavad sufiksit _async (sünkroonse versiooni ootamine ebaõnnestub), execution_id edastatakse võtmesõna argumendina ja vastused sisaldavad välju otel_trace_data, span_tree ning events (vanemas versioonis loetud väljad spans, activity_count või error_count enam ei eksisteeri); traceparent edastatakse täitmise parameetrina, kuna HTTP päis on iganenud. Allikad: Workflowi vaadeldavus · client-python.

Miks oma workfloowe jälgida

Tootmises olev workflow võib aheldada kümneid tegevusi, kutsuda mitmeid välisteenuseid ja kestma mõnest sekundist kuni mitme päevani. Ilma vaadeldavuseta on vea diagnoosimine nagu nõela otsimine heinakuhjast: tead, et täitmine ebaõnnestus, kuid ei tea, millises etapis, mitme katse järel või kas süüdlane on sinu kood või kolmanda osapoole API. Mistrali Workflowsi platvorm integreerib OpenTelemetry’i loomupäraselt, et sellele küsimusele vastata: iga tegevus, iga viga ja iga kestus salvestatakse jaotatud jälituse span-nina, ilma et sa peaksid ise instrumenteerimist teostama.

Seda mudelit struktureerivad kaks mõistet. Jälitus (trace) tähistab täitmise kogu teekonda alates esmasest käivitajast kuni lõpptulemuseni. Span (ulatus) on seevastu individuaalne operatsioon selle jälituse sees: iga tegevus genereerib automaatselt ühe span-i, kandes oma nime, algus- ja lõppaega, täitmise kestust, olekut (edu või viga) ja kõiki kohandatud atribuute. Need span-id moodustavad hierarhia – workflow span on vanem ja tegevuste span-id on selle lapsed –, mis taastoodab täitmise täieliku struktuuri.

Nimeta tegevused loetavuse huvides

Tegevuse dekoratori parameeter name määrab sildi, mis ilmub jälitustes. See on kirjutamise käigus tehtav kümne sekundi investeering, mis säästab intsidenti lahendades palju aega.

import mistralai.workflows as workflows

@workflows.activity(name="Ekstraheri lähtetekst")
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="Mistrali sentimentaalanalüüs")
async def analyser_sentiment(texte: str) -> dict:
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Analüüsi sentimenta."},
            {"role": "user", "content": texte}
        ]
    )
    return {"sentiment": response.choices[0].message.content}

@workflows.activity(name="Saada meiliteavitus")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
    # ...
    return {"status": "sent"}

Pane end valves oleva inseneri kingadesse, kes avab kell 3 öösel jälituse vaate. Valikute fetch_user_data ja „Kasutaja profiili toomine“ vahel on viimane koheselt arusaadav isegi kellegile, kes seda koodi pole kunagi lugenud.

Too jälitused programmiliselt kätte

SDK pakub kolme juurdepääsumeetodit moodulis client.workflows.executions; nende asünkroonsed versioonid kannavad sufiksit _async. Esimene tagastab toore OpenTelemetry andmestiku – span-id, kestused, atribuudid, vanem-laps seosed –, võimaldades sul need uuesti oma vaadeldavuse tööriista (Jaeger, Grafana Tempo jne) importida.

from mistralai.client import Mistral

client = Mistral()

# Toored OpenTelemetry andmed täitmise kohta
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  # Täielik jälitus, eksporditav sinu taustsüsteemi

Kui soovid peamiselt teada, kas täitmine õnnestus ja kui kaua see aega võttis, piisab kokkuvõttest. See sisaldab olekut, kogukestust ja span-puud, mida saad rekursiivselt läbida:

summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
    execution_id="exec_abc123def456"
)

print(f"Workflow: {summary.workflow_name} — olek {summary.status}")
print(f"Kogukestus: {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)} sündmus(t)")
    for child in span.children or []:
        display(child, depth + 1)


if summary.span_tree:
    display(summary.span_tree)

Kolmas meetod tagastab täitmise sündmuste kronoloogilise loendi:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Välista platvormi sisemised sündmused
)

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

Parameeter include_internal_events=False filtreerib välja tehnilised platvormi sündmused, jättes alles ainult need, mis pärinevad sinu workflowst ja tegevustest. Veidi pikema workflow puhul on erinevus loetavuses märkimisväärne. Mis puutub logidesse endisse – need, mida kuvatakse Studios –, siis get_workflow_execution_logs tagastab need lehekülje kaupa.

Valda proovivõttu

Vaikimisi eksporditakse kõik jälitused: worker teostab proovivõttu 100% ulatuses. Jälituse ID määramiseks või täitmise proovivõtu kontrollimiseks edasta W3C formaadis traceparent täitmise päringu kehas. Worker kasutab vanemal põhinevat valijat: see järgib sinu otsust, mida kannab viimane väli (01 kogumiseks, 00 mittekogumiseks).

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

Mistrali SDK-d teevad seda automaatselt: iga täitmisega edastavad nad praeguse span-i traceparent-i. traceparent-i edastamine HTTP päises on endiselt aktsepteeritud, kuid iganenud, kuna päist saab transiidi käigus ümber kirjutada; kasuta selle asemel parameetrit.

Jälgi tootmises

Workflow kontrolli all hoidmiseks piisab viiest näitajast: edumäär, st täitmiste protsent, mis lõpevad veata; ühe täieliku täitmise keskmine kestus; P95 ja P99 kestused, mis paljastavad aeglased täitmised, mida keskmine varjab; iga tegevuse korduskatsete määr, mille järsk tõus reedeb ebastabiilset välisteenust ammu enne, kui edumäär halveneb; ja lõpuks aeglaseima tegevuse tuvastamine, mis on sinu pudelikael.

Kuna jälitused järgivad OpenTelemetry standardit, ei sunni miski sind neid SDK kaudu vaatama: neid saab eksportida Datadogi selle OTel kollektori kaudu, Grafanasse ja Temposse sama mehhanismi abil, Jaegerisse jaotatud jälituste visualiseerimiseks või New Relici selle spetsiaalse eksportija kaudu. Sinu workflowd liituvad seeläbi armatuurlauaga, kus asub juba ülejäänud taristu.

Silu ebaõnnestunud workflowd

Tõrke korral väldib meetodiline protseduur arvamisest lähtumist.

  1. Too kätte täitmise ID logidest või API vastusest
  2. Konsulteeri jälituse kokkuvõtet, et teada saada olek ja tuvastada span-puus vigane tegevus
  3. Uuri üksikasjalikke sündmusi, et mõista jada, mis viis veani
  4. Kontrolli korduskatseid: kas tegevust taaskäivitati? Mitu korda?
  5. Analüüsi veateadet: aegumine, võrguviga, äriloogika viga?

Esimesi kahte sammu saab skriptida mõne reaga, kasutades eespool nähtud funktsiooni display, mis annab sulle taaskasutatava diagnostikavahendi.

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

    # 1. samm: Kokkuvõte ja span-puu
    summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
    print(f"Olek: {summary.status}")
    if summary.span_tree:
        display(summary.span_tree)

    # 2. samm: Sinu koodi sündmused järjekorras
    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)

Katsete arv väärib erilist tähelepanu: tegevus, mis ebaõnnestub esimesel katsel, ja tegevus, mis ebaõnnestub pärast viit korduskatset, räägivad erinevaid lugusid ja nõuavad erinevaid parandusi.

Kursuse kokkuvõte

Õnnitlused, oled lõpetanud selle Mistral Workflowsi kursuse. Teekond viis sind vastupidavast orkestreerimisest ja sündmustele tuginevast mehhanismist SDK installimiseni (tunnid 1–3), seejärel tegevuste, workflowde ja workerite loomiseni, nende käivitamiseni ja testimiseni (tunnid 4–7). Tunnid 8–11 kirjeldasid struktureerivaid piiranguid – determinism, Pydantic sisendid, ajalõpid, limiidid – enne avanemist paralleelsuse ja jätkamise täiustatud mustritele. Viimased kolm käsitlesid korduskatsete poliitikaid, asünkroonse I/O nõuet ja vaadeldavust OpenTelemetry abil.

Platvorm on avalikus eelvaates: API-d ja funktsioonid võivad muutuda. Kontrolli ametlikku dokumentatsiooni regulaarselt aadressil docs.mistral.ai/workflows, et olla kursis uuendustega.

Peamised punktid

  • Iga tegevus genereerib automaatselt OpenTelemetry span-id nime, kestuse ja olekuga
  • Nimeta oma tegevused parameetri name abil, et hõlbustada silumist
  • Kolm meetodit jälitustele juurdepääsuks moodulis client.workflows.executions: toore OTel, kokkuvõte (olek, kestus, span-puu) ja üksikasjalikud sündmused
  • Proovivõttu juhitakse täitmise parameetri traceparent kaudu (vaikimisi 100%; HTTP päis on iganenud)
  • Tootmises jälgi edumäära, kestust ja korduskatsete määra
  • Standardseid OTel jälitusi saab eksportida Datadogi, Grafanasse, Jaegerisse või New Relici

Testi oma teadmisi

Vastupidavad workflowd: mootori reeglid enne tootmist.

1. Mida garanteerib Mistral Workflowsi platvorm?

Vastus: Vastupidavus: workflow jääb ellu pärast tõrkeid ja jätkab sealt, kus pooleli jäi – pika kestusega orkestreerimine muutub disaini poolest usaldusväärseks.

2. Tegevus, workflow, worker: kes mida teeb?

Vastus: Tegevus on tööühik (väline väljakutse, arvutus), workflow orkestreerib tegevusi, worker täidab – eraldatus, mis võimaldab jätkamist ja skaleerimist.

3. Mida nõuab determinismi reegel?

Vastus: Workflow kood peab olema identselt taasesitatav: orkestreerimises puudub juhuslikkus või otsene kellaaja kasutamine – mittedeterministlikud efektid asuvad tegevustes.

4. Kuidas käsitletakse mööduvaid tõrkeid?

Vastus: Tegevuse korduskatsete poliitika (katsed, tagasipöördumine) ja ajalõppude kaudu – tõrge on normaalne juhtum, mida käsitletakse deklaratiiivselt, mitte käsitsi.

5. Mida toob kaasa OpenTelemetry integratsioon?

Vastus: Standardne vaadeldavus: täitmise jälitused, mõõdikud ja korrelatsioon ülejäänud süsteemiga – hädavajalik workflowde käitamiseks tootmises.

Vastupidavus, determinism, korduskatsed, vaadeldavus: neli reeglit, mis hoiavad koos pika orkestreerimise – mootor hoolitseb ülejäänu eest.