Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Opazljivost in OpenTelemetry

Lekcija 14 od 14 Posodobljeno 2. november 2026 Napredni
Na tej strani
  1. Zakaj opazovati svoja delovna tokova
  2. Poimenuj dejavnosti za berljivost
  3. Programsko pridobivanje sledi
  4. Obvladaj vzorčenje
  5. Spremljaj v proizvodnem okolju
  6. Odpravi napako v delovnem toku
  7. Povzetek tečaja
  8. Ključne ugotovitve
  9. Preveri svoje znanje

Posodobljeno 2. novembra 2026 na podlagi SDK mistralai 3.7.0: metode za sledenje se nahajajo pod client.workflows.executions; njihove asinhrone različice imajo pripono _async (čakanje na sinhrono različico ne uspe), execution_id se posreduje kot ključni argument, odgovori pa izpostavljajo otel_trace_data, span_tree in events (polja spans, activity_count ali error_count, ki jih je brala starejša različica, ne obstajajo več); traceparent se posreduje kot parameter izvajanja, saj je HTTP glava zastarela. Viri: Workflow observability · client-python.

Zakaj opazovati svoja delovna tokova

Delovni tok v proizvodnem okolju lahko poveže na desetine dejavnosti, kliče več zunanjih storitev in teče od nekaj sekund do več dni. Brez opazljivosti je diagnosticiranje težave kot iskanje igle v senu: veš, da je izvajanje spodletelo, ne veš pa na katerem koraku, po koliko poskusih ali ali je krivda na tvoji kodi ali zunanjem API-ju tretje strani. Platforma Mistral Workflows je avtohtono integrirana z OpenTelemetry, da odgovori na to vprašanje: vsaka dejavnost, vsaka napaka in vsako trajanje se zabeležita kot razpon (span) v porazdeljeni sledi, brez potrebe po kakršnem koli instrumentiranju s tvoje strani.

Ta model strukturirata dva koncepta. Sled (trace) predstavlja celotno pot izvajanja, od začetnega sprožilca do končnega rezultata. Razpon (span) pa je posamezna operacija znotraj te sledi: vsaka dejavnost samodejno ustvari enega, ki nosi svoje ime, čas začetka in konca, trajanje izvajanja, stanje (uspeh ali napaka) in morebitne prilagojene atribute. Ti razponi tvorijo hierarhijo – razpon delovnega toka je starš, razponi dejavnosti pa so njegovi otroci – kar reproducira popolno strukturo izvajanja.

Poimenuj dejavnosti za berljivost

Parameter name okrasnika (dekoratorja) dejavnosti določa oznako, ki se prikaže v sledeh. To je desetsekundna naložba med pisanjem, ki ti bo med incidentom prihranila veliko časa.

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

Postavi se v čevlje inženirja na dežurstvu, ki ob treh zjutraj odpre pogled sledi. Med fetch_user_data in „Retrieve user profile” je slednje takoj razumljivo, celo nekomu, ki te kode nikoli ni bral.

Programsko pridobivanje sledi

SDK ponuja tri metode dostopa pod client.workflows.executions; njihove asinhrone različice imajo pripono _async. Prva vrne surove podatke OpenTelemetry – razpone, trajanja, atribute, razmerja starš-otrok – kar ti omogoča, da jih ponovno uvoziš v svoje orodje za opazljivost (Jaeger, Grafana Tempo itd.).

from mistralai.client import Mistral

client = Mistral()

# Surovi podatki OpenTelemetry za izvajanje
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  # Polna sled, za ponovni izvoz v tvoje zaledje

Ko te predvsem zanima, ali je izvajanje uspelo in kako dolgo je trajalo, je povzetek dovolj. Vključuje stanje, skupno trajanje in drevo razponov, po katerem lahko rekurzivno prehajaš:

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)

Tretja metoda vrne kronološki seznam dogodkov izvajanja:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Izključi interne dogodke platforme
)

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

Parameter include_internal_events=False filtrira tehnične dogodke platforme in obdrži le tiste iz tvojega delovnega toka in dejavnosti. Pri nekoliko daljšem delovnem toku je razlika v berljivosti precejšnja. Za same dnevnike – tiste, prikazane v Studiu – jih get_workflow_execution_logs vrača stran za stranjo.

Obvladaj vzorčenje

Privzeto so izvožene vse sledi: delavec vzorči s 100-odstotno stopnjo. Če želiš nastaviti ID sledi ali nadzorovati vzorčenje za izvajanje, posreduj traceparent v formatu W3C v telesu zahteve za izvajanje. Delavec uporablja vzorčevalnik, ki temelji na staršu: sledi tvoji odločitvi, ki jo nosi zadnje polje (01 za zbiranje, 00 za nezbiranje).

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

SDK-ji Mistral to počnejo samodejno: z vsakim izvajanjem prenesejo traceparent trenutnega razpona. Posredovanje traceparent v HTTP glavi je še vedno sprejeto, vendar zastarelo, ker se lahko glava med prenosom prepíše; namesto tega uporabi parameter.

Spremljaj v proizvodnem okolju

Pet kazalnikov je dovolj, da imaš delovni tok pod nadzorom: stopnja uspešnosti, torej odstotek izvajanj, ki se končajo brez napake; povprečno trajanje celotnega izvajanja; trajanja P95 in P99, ki razkrivajo najpočasnejša izvajanja, ki jih povprečje skrije; stopnja ponovnih poskusov na dejavnost, katere nenaden porast izda nestabilno zunanjo storitev dolgo preden se stopnja uspešnosti poslabša; in nazadnje, identifikacija najpočasnejše dejavnosti, tvoje ozko grlo.

Ker sledi spoštujejo standard OpenTelemetry, te nič ne sili, da bi jih pregledoval iz SDK-ja: izvozijo se lahko v Datadog prek njegovega zbiralnika OTel, v Grafano in Tempo po istem mehanizmu, v Jaeger za vizualizacijo porazdeljenih sledi ali v New Relic prek njegovega namenskega izvoznika. Tvoji delovni tokovi se tako pridružijo nadzorni plošči, kjer že živi preostanek tvoje infrastrukture.

Odpravi napako v delovnem toku

Ob soočenju z napako se izogni ugibanju z metodičnim postopkom.

  1. Pridobi ID izvajanja iz dnevnikov ali odgovora API-ja
  2. Posvetuj povzetek sledi, da ugotoviš stanje in v drevesu razponov opaziš okvarjeno dejavnost
  3. Preuči podrobne dogodke, da razumeš zaporedje, ki je pripeljalo do napake
  4. Preveri ponovne poskuse: ali je bila dejavnost ponovno zagnana? Kolikokrat?
  5. Analiziraj sporočilo o napaki: časovni potek, napaka omrežja, poslovna napaka?

Prva dva koraka lahko skriptiraš v nekaj vrsticah z uporabo zgornje funkcije display, kar ti da orodje za diagnostiko, ki ga lahko ponovno uporabiš.

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

    # 1. korak: Povzetek in drevo razponov
    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)

    # 2. korak: Dogodki iz tvoje kode, po vrstnem redu
    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)

Število poskusov si zasluži posebno pozornost: dejavnost, ki odpove ob prvem poskusu, in tista, ki odpove po petih ponovnih poskusih, pripovedujeta različni zgodbi in zahtevata različne popravke.

Povzetek tečaja

Čestitamo, zaključil si ta tečaj o Mistral Workflows. Pot te je popeljala od trajne orkestracije in mehanizma izvora dogodkov do namestitve SDK (lekcije 1 do 3), nato do ustvarjanja dejavnosti, delovnih tokov in delavcev ter njihovega sprožanja in testiranja (lekcije 4 do 7). Lekcije od 8 do 11 so začrtale strukturne omejitve – determinizem, vnosi Pydantic, časovne omejitve, omejitve – preden so se odprle naprednim vzorcem paralelizma in nadaljevanja. Zadnje tri so pokrile politike ponovnih poskusov, zahtevo za asinhroni V/I in opazljivost z OpenTelemetry.

Platforma je v javni predogledni različici (Public Preview): API-ji in funkcije se lahko spreminjajo. Redno preverjaj uradno dokumentacijo na docs.mistral.ai/workflows, da slediš posodobitvam.

Ključne ugotovitve

  • Vsaka dejavnost samodejno ustvari razpone OpenTelemetry z imenom, trajanjem in stanjem
  • Poimenuj svoje dejavnosti s parametrom name, da olajšaš odpravljanje napak
  • Tri metode za dostop do sledi pod client.workflows.executions: surovi OTel, povzetek (stanje, trajanje, drevo razponov) in podrobni dogodki
  • Vzorčenje nadzoruje parameter traceparent izvajanja (privzeto 100 %; HTTP glava je zastarela)
  • V proizvodnem okolju spremljaj stopnjo uspešnosti, trajanje in stopnjo ponovnih poskusov
  • Standardne sledi OTel se lahko izvozijo v Datadog, Grafano, Jaeger ali New Relic

Preveri svoje znanje

Trajni delovni tokovi: pravila pogona pred proizvodnjo.

1. Kaj zagotavlja platforma Mistral Workflows?

Odgovor: Trajnost: delovni tok preživi okvare in se nadaljuje tam, kjer je zastal – dolgotrajna orkestracija postane zanesljiva po zasnovi.

2. Dejavnost, delovni tok, delavec: kdo kaj dela?

Odgovor: Dejavnost je enota dela (zunanji klic, izračun), delovni tok orkestrira dejavnosti, delavec pa izvaja – ločitev, ki omogoča nadaljevanje in skaliranje.

3. Kaj nalaga pravilo determinizma?

Odgovor: Koda delovnega toka mora biti enako ponovljiva: brez naključnosti ali neposrednega dostopa do ure pri orkestraciji – nedeterministični učinki živijo v dejavnostih.

4. Kako se obravnavajo prehodne napake?

Odgovor: Prek politike ponovnih poskusov dejavnosti (poskusi, odmik) in časovnih omejitev – napaka je normalen primer, ki se obravnava deklaratивно in ne ročno.

5. Kaj prinaša integracija OpenTelemetry?

Odgovor: Standardna opazljivost: sledi izvajanja, metrike in korelacija s preostankom tvojega sistema – bistveno za upravljanje delovnih tokov v proizvodnji.

Trajnost, determinizem, ponovni poskusi, opazljivost: štiri pravila, ki držijo dolge orkestracije skupaj – pogon poskrbi za ostalo.