Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Observabilnost i OpenTelemetry

Lekcija 14 od 14 Ažurirano 2. studenoga 2026. Napredno
Na ovoj stranici
  1. Zašto promatrati svoje workflove
  2. Imenuj aktivnosti radi čitljivosti
  3. Programski dohvati traceove
  4. Savladaj uzorkovanje (sampling)
  5. Nadzor u proizvodnji
  6. Otkloni pogreške u neuspjelom workflowu
  7. Sažetak tečaja
  8. Ključne točke
  9. Provjeri svoje znanje

Ažurirano 2. studenoga 2026. na temelju SDK-a mistralai verzije 3.7.0: metode za praćenje (trace) nalaze se pod client.workflows.executions; njihove asinkrone verzije imaju sufiks _async (čekanje sinkrone verzije ne uspijeva), execution_id se prosljeđuje kao ključni argument, a odgovori izlažu otel_trace_data, span_tree i events (polja spans, activity_count ili error_count koja je čitala starija verzija više ne postoje); traceparent se prosljeđuje kao parametar izvršenja jer je HTTP zaglavlje zastarjelo. Izvori: Workflow observability · client-python.

Zašto promatrati svoje workflove

Workflow u proizvodnji može povezati desetke aktivnosti, pozvati više vanjskih servisa i trajati od nekoliko sekundi do nekoliko dana. Bez observabilnosti, dijagnosticiranje problema nalikuje traženju igle u plastu sijena: znaš da je izvršenje palo, ali ne znaš u kojem koraku, nakon koliko pokušaja ili je li krivac tvoj kod ili API treće strane. Mistralova platforma Workflows nativno integrira OpenTelemetry kako bi odgovorila na to pitanje: svaka aktivnost, svaka pogreška i svako trajanje bilježe se kao „span“ u distribuiranom praćenju (trace), bez potrebe za ikakvom instrumentacijom s tvoje strane.

Dva koncepta strukturiraju ovaj model. Trace predstavlja cijelo putovanje izvršenja, od početnog okidača do konačnog rezultata. Span je, s druge strane, pojedinačna operacija unutar tog tracea: svaka aktivnost automatski generira jedan, noseći svoje ime, vrijeme početka i završetka, trajanje izvršenja, status (uspjeh ili pogreška) i sve prilagođene atribute. Ti spanovi tvore hijerarhiju – span workflova je roditelj, a spanovi aktivnosti su njegova djeca – što reproducira potpunu strukturu izvršenja.

Imenuj aktivnosti radi čitljivosti

Parametar name dekoratora aktivnosti određuje oznaku koja se pojavljuje u traceovima. To je ulaganje od deset sekundi tijekom pisanja koje će ti uštedjeti mnogo vremena tijekom incidenta.

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

Stavi se u cipele inženjera na dežurstvu koji otvara pregled tracea u 3 ujutro. Između fetch_user_data i „Retrieve user profile“, potonje je odmah razumljivo, čak i nekome tko nikada nije čitao ovaj kod.

Programski dohvati traceove

SDK izlaže tri metode pristupa pod client.workflows.executions; njihove asinkrone verzije imaju sufiks _async. Prva vraća sirove OpenTelemetry podatke – spanove, trajanja, atribute, odnose roditelj-dijete – omogućujući ti da ih ponovno uneseš u svoj vlastiti alat za observabilnost (Jaeger, Grafana Tempo itd.).

from mistralai.client import Mistral

client = Mistral()

# Sirovi OpenTelemetry podaci za izvršenje
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  # Puni trace, za ponovni izvoz u tvoju pozadinu

Kada uglavnom želiš znati je li izvršenje uspjelo i koliko je trajalo, sažetak je dovoljan. Uključuje status, ukupno trajanje i stablo spanova (span tree), koje možeš rekurzivno obilaziti:

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)

Treća metoda vraća kronološki popis događaja izvršenja:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Isključi interne događaje platforme
)

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

Parametar include_internal_events=False filtrira tehničke događaje platforme, zadržavajući samo one iz tvog workflova i aktivnosti. Kod nešto dužeg workflova, razlika u čitljivosti je znatna. Za same zapise (logove) – one prikazane u Studiju – get_workflow_execution_logs ih vraća stranicu po stranicu.

Savladaj uzorkovanje (sampling)

Prema zadanim postavkama, svi se traceovi izvoze: worker uzorkuje sa 100 %. Da bi postavio ID tracea ili kontrolirao uzorkovanje za izvršenje, proslijedi traceparent u W3C formatu u tijelu zahtjeva za izvršenje. Worker koristi uzorkivač temeljen na roditelju: slijedi tvoju odluku, koju nosi posljednje polje (01 za prikupljanje, 00 za neprikupljanje).

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

Mistralovi SDK-ovi to rade automatski: sa svakim izvršenjem prenose traceparent trenutnog spana. Prosljeđivanje traceparent u HTTP zaglavlju još je uvijek prihvaćeno, ali je zastarjelo jer se zaglavlje može prepisati tijekom prijenosa; umjesto toga koristi parametar.

Nadzor u proizvodnji

Pet indikatora dovoljno je da workflow držiš pod kontrolom: stopa uspješnosti, odnosno postotak izvršenja koja završe bez pogreške; prosječno trajanje potpunog izvršenja; trajanja P95 i P99, koja otkrivaju najsporija izvršenja koja prosjek skriva; stopa ponovnih pokušaja po aktivnosti, čiji nagli porast izdaje nestabilan vanjski servis mnogo prije nego što se stopa uspješnosti pogorša; i konačno, identifikacija najsporije aktivnosti, tvog uskog grla.

Budući da traceovi poštuju OpenTelemetry standard, ništa te ne prisiljava da ih konzultiraš putem SDK-a: mogu se izvesti u Datadog putem njegovog OTel kolektora, u Grafanu i Tempo istim mehanizmom, u Jaeger za vizualizaciju distribuiranih traceova ili u New Relic putem njegovog namjenskog izvoznika. Tvoji workflowovi tako ulaze na nadzornu ploču gdje već živi ostatak tvoje infrastrukture.

Otkloni pogreške u neuspjelom workflowu

Suočen s neuspjehom, metodičan postupak izbjegava nagađanje.

  1. Dohvati ID izvršenja iz zapisa (logova) ili odgovora API-ja
  2. Konzultiraj sažetak tracea kako bi znao status i uočio neispravnu aktivnost u stablu spanova
  3. Ispitaj detaljne događaje kako bi razumio slijed koji je doveo do pogreške
  4. Provjeri ponovne pokušaje: je li aktivnost ponovno pokrenuta? Koliko puta?
  5. Analiziraj poruku o pogrešci: istek vremena (timeout), mrežna pogreška, poslovna pogreška?

Prva dva koraka mogu se skriptirati u nekoliko redaka, koristeći funkciju display viđenu gore, dajući ti alat za dijagnostiku koji možeš ponovno koristiti.

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

    # Korak 1: Sažetak i stablo spanova
    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)

    # Korak 2: Događaji iz tvog koda, po 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)

Broj pokušaja zaslužuje posebnu pozornost: aktivnost koja padne pri prvom pokušaju i ona koja padne nakon pet ponovnih pokušaja pričaju različite priče i zahtijevaju različita rješenja.

Sažetak tečaja

Čestitam, završio/la si ovaj tečaj o Mistral Workflowsima. Putovanje te je odvelo od durabilne orkestracije i mehanizma izvora događaja (event sourcing) do instalacije SDK-a (lekcije 1 do 3), zatim do stvaranja aktivnosti, workflova i workera, njihovog pokretanja i testiranja (lekcije 4 do 7). Lekcije 8 do 11 postavile su strukturna ograničenja – determinizam, Pydantic ulazi, vremenska ograničenja, ograničenja – prije otvaranja prema naprednim obrascima paralelizma i nastavka. Posljednje tri pokrivale su politike ponovnih pokušaja, zahtjev za asinkronim I/O-om i observabilnost s OpenTelemetryjem.

Platforma je u javnoj preglednoj verziji (Public Preview): API-ji i značajke mogu se mijenjati. Redovito provjeravaj službenu dokumentaciju na docs.mistral.ai/workflows kako bi pratio/la ažuriranja.

Ključne točke

  • Svaka aktivnost automatski generira OpenTelemetry spanove s imenom, trajanjem i statusom
  • Imenuj svoje aktivnosti parametrom name kako bi olakšao/la otklanjanje pogrešaka
  • Tri metode za pristup traceovima, pod client.workflows.executions: sirovi OTel, sažetak (status, trajanje, stablo spanova) i detaljni događaji
  • Uzorkovanje se kontrolira parametrom traceparent izvršenja (100 % prema zadanim postavkama; HTTP zaglavlje je zastarjelo)
  • U proizvodnji prati stopu uspješnosti, trajanje i stopu ponovnih pokušaja
  • Standardni OTel traceovi mogu se izvesti u Datadog, Grafanu, Jaeger ili New Relic

Provjeri svoje znanje

Durabilni workflowovi: pravila enginea prije proizvodnje.

1. Što garantira platforma Mistral Workflows?

Odgovor: Durabilnost: workflow preživljava kvarove i nastavlja tamo gdje je stao – orkestracija dugog trajanja postaje pouzdana po dizajnu.

2. Aktivnost, workflow, worker: tko što radi?

Odgovor: Aktivnost je jedinica rada (vanjski poziv, izračun), workflow orkestrira aktivnosti, worker izvršava – odvajanje koje omogućuje nastavak i skaliranje.

3. Što nameće pravilo determinizma?

Odgovor: Kod workflova mora biti identično reproducibilan: bez slučajnosti ili izravnog pristupa satu u orkestraciji – nedeterministički efekti žive u aktivnostima.

4. Kako se rješavaju prolazni kvarovi?

Odgovor: Putem politike ponovnih pokušaja aktivnosti (pokušaji, backoff) i vremenskih ograničenja – neuspjeh je normalan slučaj, kojim se upravlja deklarativno, a ne ručno.

5. Što donosi integracija OpenTelemetryja?

Odgovor: Standardna observabilnost: traceovi izvršenja, metrike i korelacija s ostatkom tvog sustava – ključno za rad workflova u proizvodnji.

Durabilnost, determinizam, ponovni pokušaji, observabilnost: četiri pravila koja drže dugačke orkestracije na okupu – engine se brine za ostalo.