Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Pozorovateľnosť a OpenTelemetry

Lekcia 14 z 14 Aktualizované 2. novembra 2026 Pokročilý
Na tejto strane
  1. Prečo pozorovať svoje workflow
  2. Pomenuj aktivity pre čitateľnosť
  3. Programové získavanie stôp
  4. Ovládanie vzorkovania
  5. Monitorovanie v produkcii
  6. Ladienie nefunkčného workflow
  7. Zhrnutie kurzu
  8. Kľúčové poznatky
  9. Otestuj si svoje vedomosti

Aktualizované 2. novembra 2026 na základe SDK mistralai 3.7.0: metódy pre stopy sa nachádzajú pod client.workflows.executions; ich asynchrónne verzie majú príponu _async (čakanie na synchronnú verziu zlyhá), execution_id sa odovzdáva ako kľúčový argument a odpovede poskytujú otel_trace_data, span_tree a events (polia spans, activity_count alebo error_count, ktoré čítala staršia verzia, už neexistujú); traceparent sa odovzdáva ako parameter vykonania, keďže HTTP hlavička je zastaraná. Zdroje: Pozorovateľnosť workflow · client-python.

Prečo pozorovať svoje workflow

Workflow v produkcii môže reťaziť desiatky aktivít, volať viacero externých služieb a bežať od niekoľkých sekúnd až po niekoľko dní. Bez pozorovateľnosti je diagnostika problému ako hľadanie ihly v kope sena: vieš, že vykonanie zlyhalo, ale nevieš na ktorom kroku, po koľkých pokusoch ani či je vinníkom tvoj kód alebo API tretej strany. Platforma Mistral Workflows integruje OpenTelemetry natívne, aby odpovedala na túto otázku: každá aktivita, každá chyba a každé trvanie sa zaznamenáva ako span v distribuovanej stope, a to bez potreby inštrumentácie z tvojej strany.

Tento model štruktúrujú dva pojmy. Stopa (trace) predstavuje celú cestu vykonania, od počiatočného spustenia až po konečný výsledok. Span (rozpätie) je naopak jednotlivá operácia v rámci tejto stopy: každá aktivita automaticky generuje jeden, ktorý nesie jej názov, časy začiatku a konca, trvanie vykonania, stav (úspech alebo chyba) a všetky vlastné atribúty. Tieto span-y tvoria hierarchiu – span workflow je rodič a span-y aktivít sú jeho deťmi – čo reprodukuje kompletnú štruktúru vykonania.

Pomenuj aktivity pre čitateľnosť

Parameter name v dekorátore aktivity určuje štítok, ktorý sa zobrazuje v stopách. Je to investícia desiatich sekúnd pri písaní kódu, ktorá ti ušetrí veľa času počas incidentu.

import mistralai.workflows as workflows

@workflows.activity(name="Extrahovať zdrojový 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="Analýza sentimentu Mistral")
async def analyser_sentiment(texte: str) -> dict:
    client = Mistral()
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Analyzuj sentiment."},
            {"role": "user", "content": texte}
        ]
    )
    return {"sentiment": response.choices[0].message.content}

@workflows.activity(name="Odoslať e-mailové upozornenie")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
    # ...
    return {"status": "sent"}

Vžij sa do kože inžiniera na pohotovosti, ktorý o tretej ráno otvorí zobrazenie stopy. Medzi fetch_user_data a „Získať profil používateľa“ je druhé okamžite zrozumiteľné, dokonca aj pre niekoho, kto tento kód nikdy nečítal.

Programové získavanie stôp

SDK poskytuje tri prístupové metódy pod client.workflows.executions; ich asynchrónne verzie majú príponu _async. Prvá vracia surové dáta OpenTelemetry – span-y, trvania, atribúty, vzťahy rodič-dieťa – čo ti umožňuje znovu ich ingestovať do vlastného nástroja pozorovateľnosti (Jaeger, Grafana Tempo atď.).

from mistralai.client import Mistral

client = Mistral()

# Surové dáta OpenTelemetry pre vykonanie
trace = await client.workflows.executions.get_workflow_execution_trace_otel_async(
    execution_id="exec_abc123def456"
)

print(f"OTel Stopa: {trace.otel_trace_id}")
otel_data = trace.otel_trace_data  # Úplná stopa na opätovný export do tvojho backendu

Keď chceš hlavne vedieť, či bolo vykonanie úspešné a ako dlho trvalo, stačí súhrn. Obsahuje stav, celkové trvanie a strom span-ov, ktorým môžeš prechádzať rekurzívne:

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

print(f"Workflow: {summary.workflow_name} — stav {summary.status}")
print(f"Celkové trvanie: {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)} udalosť(í)")
    for child in span.children or []:
        display(child, depth + 1)


if summary.span_tree:
    display(summary.span_tree)

Tretia metóda vracia chronologický zoznam udalostí vykonania:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Vylúčiť interné udalosti platformy
)

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

Parameter include_internal_events=False filtruje technické udalosti platformy a ponecháva len tie z tvojho workflow a aktivít. Pri mierne dlhom workflow je rozdiel v čitateľnosti značný. Pre samotné logy – tie zobrazené v Studio – ich get_workflow_execution_logs vracia stránku po stránke.

Ovládanie vzorkovania

Predvolene sa exportujú všetky stopy: worker vzorkuje na 100 %. Ak chceš nastaviť ID stopy alebo kontrolovať vzorkovanie pre vykonanie, odovzdaj traceparent vo formáte W3C v tele požiadavky na vykonanie. Worker používa vzorkovač založený na rodičovi: riadi sa tvojim rozhodnutím, ktoré nesie posledné pole (01 na zber, 00 na nezber).

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

SDK Mistral to robia automaticky: pri každom vykonaní prenášajú traceparent aktuálneho span-u. Odovzdanie traceparent v HTTP hlavičke je stále akceptované, ale zastarané, pretože hlavička môže byť počas prenosu prepísaná; namiesto toho použij parameter.

Monitorovanie v produkcii

Na udržanie workflow pod kontrolou stačí päť ukazovateľov: miera úspešnosti, teda percento vykonaní, ktoré skončia bez chyby; priemerné trvanie kompletného vykonania; trvania P95 a P99, ktoré odhaľujú najpomalšie vykonania, ktoré priemer skrýva; miera opakovaných pokusov na aktivitu, ktorej náhly nárast prezradí nestabilnú externú službu skôr, než sa zhorší miera úspešnosti; a nakoniec identifikácia najpomalšej aktivity, tvojho úzkeho hrdla.

Keďže stopy rešpektujú štandard OpenTelemetry, nič ťa nenúti konzultovať ich cez SDK: môžu byť exportované do Datadog cez jeho OTel kolektor, do Grafany a Tempo rovnakým mechanizmom, do Jaegeru na vizualizáciu distribuovaných stôp alebo do New Relic cez jeho vyhradený exportér. Tvoje workflow sa tak zaradia do dashboardu, kde už žije zvyšok tvojej infraštruktúry.

Ladienie nefunkčného workflow

Pri zlyhaní sa vyhni hádaniu pomocou metodického postupu.

  1. Získaj ID vykonania z logov alebo odpovede API
  2. Konzultuj súhrn stopy, aby si zistil stav a identifikoval chybnú aktivitu v strome span-ov
  3. Preskúmaj podrobné udalosti, aby si pochopil sekvenciu, ktorá viedla k chybe
  4. Skontroluj opakované pokusy: bola aktivita reštartovaná? Koľkokrát?
  5. Analyzuj chybovú správu: časový limit, chyba siete, business chyba?

Prvé dva kroky môžeš naprogramovať v niekoľkých riadkoch pomocou funkcie display uvedenej vyššie, čím získaš opakovane použiteľný diagnostický nástroj.

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

    # Krok 1: Súhrn a strom span-ov
    summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
    print(f"Stav: {summary.status}")
    if summary.span_tree:
        display(summary.span_tree)

    # Krok 2: Udalosti z tvojho kódu v poradí
    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)

Počet pokusov si zasluhuje osobitnú pozornosť: aktivita, ktorá zlyhá pri prvom pokuse, a tá, ktorá zlyhá po piatich opakovaných pokusoch, rozprávajú rôzne príbehy a vyžadujú si odlišné opravy.

Zhrnutie kurzu

Gratulujeme, dokončil si tento kurz o Mistral Workflows. Cesta ťa zaviedla od odolnej orchestrácie a mechanizmu event sourcingu cez inštaláciu SDK (lekcie 1 až 3) až po vytváranie aktivít, workflow a workerov, ich spúšťanie a testovanie (lekcie 4 až 7). Lekcie 8 až 11 načrtli štrukturálne obmedzenia – determinizmus, vstupy Pydantic, časové limity, obmedzenia – predtým, než sa otvorili pokročilé vzory paralelizmu a pokračovania. Posledné tri pokryli politiky opakovaných pokusov, požiadavku na asynchrónny I/O a pozorovateľnosť s OpenTelemetry.

Platforma je vo fáze Public Preview: API a funkcie sa môžu vyvíjať. Pravidelne kontroluj oficiálnu dokumentáciu na docs.mistral.ai/workflows, aby si sledoval aktualizácie.

Kľúčové poznatky

  • Každá aktivita automaticky generuje span-y OpenTelemetry s názvom, trvaním a stavom
  • Pomenuj svoje aktivity pomocou parametra name pre uľahčenie ladenia
  • Tri metódy prístupu k stopám pod client.workflows.executions: surové OTel, súhrn (stav, trvanie, strom span-ov) a podrobné udalosti
  • Vzorkovanie je riadené parametrom traceparent vykonania (predvolene 100 %; HTTP hlavička je zastaraná)
  • V produkcii monitoruj mieru úspešnosti, trvanie a mieru opakovaných pokusov
  • Štandardné stopy OTel sú exportovateľné do Datadog, Grafany, Jaegeru alebo New Relic

Otestuj si svoje vedomosti

Odolné workflow: pravidlá enginu pred nasadením do produkcie.

1. Čo garantuje platforma Mistral Workflows?

Odpoveď: Odolnosť: workflow prežije zlyhania a obnoví sa tam, kde skončilo – dlhotrvajúca orchestrácia sa stáva spoľahlivou už svojou konštrukciou.

2. Aktivita, workflow, worker: kto čo robí?

Odpoveď: Aktivita je jednotka práce (externé volanie, výpočet), workflow orchestrácie aktivity, worker vykonáva – toto oddelenie umožňuje obnovu a škálovanie.

3. Čo ukladá pravidlo determinizmu?

Odpoveď: Kód workflow musí byť identicky replayovateľný: žiadna náhodnosť ani priamy prístup k hodinám v orchestrácii – nedeterministické efekty žijú v aktivitách.

4. Ako sa riešia prechodné zlyhania?

Odpoveď: Prostredníctvom politiky opakovaných pokusov aktivity (pokusy, backoff) a časových limitov – zlyhanie je bežný prípad, ktorý sa rieši deklaratívne, nie manuálne.

5. Čo prináša integrácia OpenTelemetry?

Odpoveď: Štandardnú pozorovateľnosť: stopy vykonania, metriky a koreláciu so zvyškom tvojho systému – nevyhnutné pre prevádzkovanie workflow v produkcii.

Odolnosť, determinizmus, opakovanie, pozorovateľnosť: štyri pravidlá, ktoré držia pohromade dlhé orchestrácie – engine sa postará o zvyšok.