Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Pozorovatelnost a OpenTelemetry

Lekce 14 z 14 Aktualizováno 2. listopadu 2026 Pokročilý
Na této stránce
  1. Proč pozorovat své workflow
  2. Pojmenuj aktivity pro čitelnost
  3. Programové získávání stop
  4. Ovládni vzorkování (sampling)
  5. Monitorování v produkci
  6. Ladění selhaného workflow
  7. Shrnutí kurzu
  8. Klíčové poznatky
  9. Ověř si své znalosti

Aktualizováno 2. listopadu 2026 na základě SDK mistralai verze 3.7.0: metody pro stopy (traces) se nacházejí pod client.workflows.executions; jejich asynchronní verze mají příponu _async (čekání na synchronní verzi selže), execution_id se předává jako klíčový argument a odpovědi poskytují otel_trace_data, span_tree a events (pole spans, activity_count nebo error_count, která četla starší verze, již neexistují); traceparent se předává jako parametr spuštění, protože HTTP hlavička je zastaralá. Zdroje: Workflow observability · client-python.

Proč pozorovat své workflow

Workflow v produkci může řetězit desítky aktivit, volat více externích služeb a běžet od několika sekund až po několik dní. Bez pozorovatelnosti je diagnostika problému jako hledání jehly v kupce sena: víš, že spuštění selhalo, ale nevíš v kterém kroku, po kolika pokusech ani zda je viníkem tvůj kód nebo API třetí strany. Platforma Mistral Workflows integruje OpenTelemetry nativně, aby na tuto otázku odpověděla: každá aktivita, každá chyba a každá doba trvání jsou zaznamenány jako span v distribuované stopě, aniž bys musel provádět jakoukoli instrumentaci.

Tento model strukturuje dva koncepty. Stopa (trace) představuje celou cestu spuštění od počátečního triggeru až po konečný výsledek. Span je naopak jednotlivá operace v rámci této stopy: každá aktivita automaticky generuje jeden span, který nese svůj název, časy začátku a konce, dobu trvání, stav (úspěch nebo chyba) a případné vlastní atributy. Tyto spány tvoří hierarchii – span workflow je rodič a spány aktivit jsou jeho děti – což reprodukuje kompletní strukturu spuštění.

Pojmenuj aktivity pro čitelnost

Parametr name dekorátoru aktivity určuje štítek, který se zobrazuje ve stopách. Je to investice deseti sekund při psaní kódu, která ti ušetří spoustu času během incidentu.

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

Představ si, že jsi inženýr na pohotovosti, který otevírá zobrazení stopy ve tři ráno. Mezi fetch_user_data a „Retrieve user profile“ je druhá možnost okamžitě srozumitelná, dokonce i pro někoho, kdo tento kód nikdy nečetl.

Programové získávání stop

SDK poskytuje tři metody přístupu pod client.workflows.executions; jejich asynchronní verze mají příponu _async. První vrací surová data OpenTelemetry – spány, doby trvání, atributy, vztahy rodič-dítě – což ti umožňuje znovu je ingestovat do tvého vlastního nástroje pro pozorovatelnost (Jaeger, Grafana Tempo atd.).

from mistralai.client import Mistral

client = Mistral()

# Surová data OpenTelemetry pro spuštění
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  # Úplná stopa k opětovnému exportu do tvého backendu

Když tě hlavně zajímá, zda bylo spuštění úspěšné a jak dlouho trvalo, stačí souhrn. Obsahuje stav, celkovou dobu trvání a strom spanů, kterým můžeš procházet rekurzivně:

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)

Třetí metoda vrací chronologický seznam událostí spuštění:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Vyloučit interní události platformy
)

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

Parametr include_internal_events=False filtruje technické události platformy a ponechává pouze ty z tvého workflow a aktivit. U mírně dlouhého workflow je rozdíl v čitelnosti značný. Pro samotné logy – ty zobrazené ve Studiu – je vrací metoda get_workflow_execution_logs stránku po stránce.

Ovládni vzorkování (sampling)

Ve výchozím nastavení jsou exportovány všechny stopy: worker vzorkuje na 100 %. Chcete-li nastavit ID stopy nebo řídit vzorkování pro konkrétní spuštění, předejte traceparent ve formátu W3C v těle žádosti o spuštění. Worker používá vzorkovač založený na rodiči: řídí se vaším rozhodnutím, které nese poslední pole (01 pro sběr, 00 pro nesběr).

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

SDK Mistral to dělají automaticky: při každém spuštění přenášejí traceparent aktuálního spanu. Předání traceparent v HTTP hlavičce je stále přijímáno, ale je zastaralé, protože hlavička může být při přenosu přepsána; místo toho použij parametr.

Monitorování v produkci

K udržení workflow pod kontrolou stačí pět ukazatelů: míra úspěšnosti, tedy procento spuštění, která skončí bez chyby; průměrná doba trvání celého spuštění; durations P95 a P99, které odhalují nejpomalejší spuštění, jež průměr skrývá; míra opakování (retry) na aktivitu, jejíž náhlý nárůst prozradí nestabilní externí službu dlouho předtím, než se zhorší míra úspěšnosti; a nakonec identifikace nejpomalejší aktivity, což je tvé úzké hrdlo.

Protože stopy respektují standard OpenTelemetry, nic tě nenutí konzultovat je přes SDK: mohou být exportovány do Datadog prostřednictvím jeho OTel kolektoru, do Grafany a Tempo stejným mechanismem, do Jaegeru pro vizualizaci distribuovaných stop nebo do New Relic prostřednictvím jeho vyhrazeného exportéru. Tvá workflow se tak zapojí do dashboardu, kde již žije zbytek tvé infrastruktury.

Ladění selhaného workflow

Tváří v tvář selhání se vyhni hádání pomocí metodického postupu.

  1. Získej ID spuštění z logů nebo odpovědi API
  2. Konzultuj souhrn stopy, abys zjistil stav a identifikoval chybnou aktivitu ve stromu spanů
  3. Prozkoumej podrobné události, abys pochopil sekvenci, která vedla k chybě
  4. Zkontroluj opakování: byla aktivita restartována? Kolikrát?
  5. Analyzuj chybovou zprávu: timeout, chyba sítě, business chyba?

První dva kroky lze naskriptovat na pár řádcích pomocí výše uvedené funkce display, čímž získáš znovu použitelný diagnostický nástroj.

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

    # Krok 1: Souhrn a strom spanů
    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)

    # Krok 2: Události z tvého kódu v pořadí
    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 pokusů si zaslouží zvláštní pozornost: aktivita, která selže při prvním pokusu, a ta, která selže po pěti opakováních, vyprávějí různé příběhy a vyžadují různé opravy.

Shrnutí kurzu

Gratulujeme, dokončil jsi tento kurz o Mistral Workflows. Cesta tě zavedla od odolné orchestrace a mechanismu event sourcingu přes instalaci SDK (lekce 1 až 3) až k vytváření aktivit, workflow a workerů, jejich spouštění a testování (lekce 4 až 7). Lekce 8 až 11 nastínily strukturální omezení – determinismus, vstupy Pydantic, časové limity, omezení – než se otevřely pokročilým vzorům paralelismu a pokračování. Poslední tři pokryly zásady opakování, požadavek na async I/O a pozorovatelnost s OpenTelemetry.

Platforma je ve fázi Public Preview: API a funkce se mohou vyvíjet. Pravidelně kontroluj oficiální dokumentaci na docs.mistral.ai/workflows, abys sledoval aktualizace.

Klíčové poznatky

  • Každá aktivita automaticky generuje spány OpenTelemetry s názvem, dobou trvání a stavem
  • Pojmenuj své aktivity pomocí parametru name, abys usnadnil ladění
  • Tři metody přístupu ke stopám pod client.workflows.executions: surová OTel, souhrn (stav, doba trvání, strom spanů) a podrobné události
  • Vzorkování je řízeno parametrem traceparent spuštění (ve výchozím nastavení 100 %; HTTP hlavička je zastaralá)
  • V produkci sleduj míru úspěšnosti, dobu trvání a míru opakování
  • Standardní stopy OTel lze exportovat do Datadog, Grafany, Jaegeru nebo New Relic

Ověř si své znalosti

Odolná workflow: pravidla engine před nasazením do produkce.

1. Co garantuje platforma Mistral Workflows?

Odpověď: Odolnost: workflow přežije selhání a obnoví se tam, kde skončilo – dlouhotrvající orchestrace se stává spolehlivou díky designu.

2. Aktivita, workflow, worker: kdo co dělá?

Odpověď: Aktivita je jednotka práce (externí volání, výpočet), workflow orchestrace aktivity, worker je executes – toto oddělení umožňuje obnovení a škálování.

3. Co ukládá pravidlo determinismu?

Odpověď: Kód workflow musí být identicky přehratelný: žádná náhodnost ani přímý přístup k hodinám v orchestraci – nedeterministické efekty žijí v aktivitách.

4. Jak se řeší přechodná selhání?

Odpověď: Prostřednictvím zásad opakování aktivit (pokusy, backoff) a časových limitů – selhání je normální případ, řešený deklarativně, nikoliv manuálně.

5. Co přináší integrace OpenTelemetry?

Odpověď: Standardní pozorovatelnost: stopy spuštění, metriky a korelace se zbytkem tvého systému – nezbytné pro provoz workflow v produkci.

Odolnost, determinismus, opakování, pozorovatelnost: čtyři pravidla, která drží dlouhé orchestrace pohromadě – engine se postará o zbytek.