Observabilnost i OpenTelemetry
Na ovoj stranici
Ažurirano 2. studenoga 2026. na temelju SDK-a
mistralaiverzije 3.7.0: metode za praćenje (trace) nalaze se podclient.workflows.executions; njihove asinkrone verzije imaju sufiks_async(čekanje sinkrone verzije ne uspijeva),execution_idse prosljeđuje kao ključni argument, a odgovori izlažuotel_trace_data,span_treeievents(poljaspans,activity_countilierror_countkoja je čitala starija verzija više ne postoje);traceparentse 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.
- Dohvati ID izvršenja iz zapisa (logova) ili odgovora API-ja
- Konzultiraj sažetak tracea kako bi znao status i uočio neispravnu aktivnost u stablu spanova
- Ispitaj detaljne događaje kako bi razumio slijed koji je doveo do pogreške
- Provjeri ponovne pokušaje: je li aktivnost ponovno pokrenuta? Koliko puta?
- 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
namekako 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
traceparentizvrš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.