Opazljivost in OpenTelemetry
Na tej strani
Posodobljeno 2. novembra 2026 na podlagi SDK
mistralai3.7.0: metode za sledenje se nahajajo podclient.workflows.executions; njihove asinhrone različice imajo pripono_async(čakanje na sinhrono različico ne uspe),execution_idse posreduje kot ključni argument, odgovori pa izpostavljajootel_trace_data,span_treeinevents(poljaspans,activity_countalierror_count, ki jih je brala starejša različica, ne obstajajo več);traceparentse 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.
- Pridobi ID izvajanja iz dnevnikov ali odgovora API-ja
- Posvetuj povzetek sledi, da ugotoviš stanje in v drevesu razponov opaziš okvarjeno dejavnost
- Preuči podrobne dogodke, da razumeš zaporedje, ki je pripeljalo do napake
- Preveri ponovne poskuse: ali je bila dejavnost ponovno zagnana? Kolikokrat?
- 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
traceparentizvajanja (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.