Osservabbiltà u OpenTelemetry
F'din il-paġna
Aġġornat fit-2 ta’ Novembru 2026 abbażi tal-SDK
mistralai3.7.0: il-metodi tat-traċċar jinsabu taħtclient.workflows.executions; il-verżjonijiet asinkroni tagħhom iġorru s-suffiss_async(li tistenna l-verżjoni sinkrona tfalli),execution_idjgħaddi bħala argument keyword, u r-risposti jesponuotel_trace_data,span_tree, uevents(il-kampispans,activity_count, jewerror_countmoqrija mill-verżjoni antika ma jeżistux aktar);traceparentjgħaddi bħala parametru ta’ eżekuzzjoni, peress li l-header HTTP huwa deprekat. Sorsi: Osservabbiltà tal-Workflow · client-python.
Għaliex tosserva l-workflows tiegħek
Workflow fil-produzzjoni jista’ jgħaqqad għexieren ta’ attivitajiet, isejjaħ servizzi esterni multipli, u jibqa’ għaddej minn ftit sekondi sa diversi jiem. Mingħajr osservabbiltà, id-dijanjożi ta’ problema hija bħal tfittxija ta’ labra f’għar ta’ tibn: tkun taf li l-eżekuzzjoni falliet, iżda mhux f’liema pass, wara kemm-il tentattiv, jew jekk il-ħati huwiex il-kodiċi tiegħek jew API ta’ parti terza. Il-pjattaforma Workflows ta’ Mistral tintegra OpenTelemetry b’mod nativ biex twieġeb din il-mistoqsija: kull attività, kull żball, u kull tul ta’ żmien jiġi rreġistrat bħala span f’traċċa distribwita, mingħajr ma teħtieġ l-ebda strumentazzjoni min-naħa tiegħek.
Żewġ kunċetti jistrutturaw dan il-mudell. It-traċċa tirrappreżenta l-vjaġġ sħiħ ta’ eżekuzzjoni, mit-trigger inizjali sar-riżultat finali. Is-span, min-naħa l-oħra, hija operazzjoni individwali f’dik it-traċċa: kull attività tiġġenera waħda awtomatikament, li ġġorr l-isem tagħha, il-ħinijiet tal-bidu u t-tmiem, it-tul tal-eżekuzzjoni, l-istatus (suċċess jew żball), u kwalunkwe attribut personalizzat. Dawn l-ispan jiffurmaw ġerarkija—l-ispan tal-workflow huwa l-ġenitur, u l-ispan tal-attività huma t-tfal tiegħu—li tirriproduċi l-istruttura sħiħa tal-eżekuzzjoni.
Semmi l-attivitajiet għal leġġibbiltà
Il-parametru name tad-dekoratur tal-attività jiddetermina t-tikketta li tidher fit-traċċi. Huwa investiment ta’ għaxar sekondi waqt il-kitba li se jiffrankalek ħafna ħin waqt inċident.
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"}
Poġġi ruħek f’żarbun tal-inġinier tal-għassa li jiftaħ veduta tat-traċċa fit-3 ta’ filgħodu. Bejn fetch_user_data u “Retrieve user profile”, din tal-aħħar tinftiehem immedjatament, anke għal xi ħadd li qatt ma qara dan il-kodiċi.
Irkupra t-traċċi programmatikament
L-SDK jesponi tliet metodi ta’ aċċess taħt client.workflows.executions; il-verżjonijiet asinkroni tagħhom iġorru s-suffiss _async. L-ewwel wieħed jirritorna data OpenTelemetry mhux ipproċessata—spans, tulijiet ta’ żmien, attributi, relazzjonijiet bejn ġenitur u wild—li jippermettilek terġa’ ddaħħalha fl-għodda ta’ osservabbiltà tiegħek stess (Jaeger, Grafana Tempo, eċċ.).
from mistralai.client import Mistral
client = Mistral()
# Data OpenTelemetry mhux ipproċessata għall-eżekuzzjoni
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 # Traċċa sħiħa, biex terġa' tesportaha lejn il-backend tiegħek
Meta trid prinċipalment tkun jekk l-eżekuzzjoni rnexxitx u kemm damet, is-sommarju huwa biżżejjed. Dan jinkludi l-istatus, it-tul totali, u s-siġra tal-ispan, li tista’ tgħaddi minnha b’mod rikorsiv:
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)
It-tielet metodu jirritorna lista kronoloġika ta’ avvenimenti ta’ eżekuzzjoni:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Eskludi avvenimenti interni tal-pjattaforma
)
for event in response.events or []:
print(event)
Il-parametru include_internal_events=False jiffiltra barra l-avvenimenti tekniċi tal-pjattaforma, u jżomm biss dawk mill-workflow u l-attivitajiet tiegħek. Fuq workflow ftit twil, id-differenza fil-leġġibbiltà hija konsiderevoli. Għal-logġijiet infushom—dawk murija f’Studio—get_workflow_execution_logs jirritornahom paġna b’paġna.
Ikkontrolla t-teħid ta’ kampjuni (Sampling)
B’mod predefinit, it-traċċi kollha jiġu esportati: il-ħaddiem jieħu kampjuni b’100%. Biex tissettja l-ID tat-traċċa jew tikkontrolla t-teħid ta’ kampjuni għal eżekuzzjoni, għaddi traceparent fil-format W3C fil-korp tat-talba tal-eżekuzzjoni. Il-ħaddiem juża sampler ibbażat fuq il-ġenitur: isegwi d-deċiżjoni tiegħek, imġarrba mill-aħħar kamp (01 biex tiġbor, 00 biex ma tiġborx).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
L-SDKs ta’ Mistral jagħmlu dan awtomatikament: ma’ kull eżekuzzjoni, jittrażmettu t-traceparent tal-ispan kurrenti. Li tgħaddi traceparent f’header HTTP għadu aċċettat iżda deprekat, għax header jista’ jiġi miktub mill-ġdid waqt it-tranżitu; uża l-parametru minflok.
Immonitorja fil-produzzjoni
Ħames indikaturi huma biżżejjed biex iżommu workflow taħt kontroll: ir-rata ta’ suċċess, jiġifieri l-perċentwal ta’ eżekuzzjonijiet li jispiċċaw mingħajr żball; it-tul medju ta’ eżekuzzjoni sħiħa; it-tulijiet P95 u P99, li jiżvelaw l-eżekuzzjonijiet l-aktar bil-mod li l-medja taħbi; ir-rata ta’ retry għal kull attività, li t-tlugħ f’daqqa tagħha tradixxi servizz estern instabbli sew qabel ma r-rata ta’ suċċess tiddeterjora; u finalment, l-identifikazzjoni tal-attività l-aktar bil-mod, il-bottleneck tiegħek.
Peress li t-traċċi jirrispettaw l-istandard OpenTelemetry, xejn ma jfurzalek tikkonsultahom mill-SDK: jistgħu jiġu esportati lejn Datadog permezz tal-kollektur OTel tiegħu, lejn Grafana u Tempo bl-istess mekkaniżmu, lejn Jaeger għall-viżwalizzazzjoni tat-traċċi distribwiti, jew lejn New Relic permezz tal-esportatur dedikat tiegħu. Il-workflows tiegħek b’hekk jingħaqdu mad-dashboard fejn diġà tgħix il-bqija tal-infrastruttura tiegħek.
Iddebbuja workflow li falla
Quddiem falliment, proċedura metodika tevita l-ispekulazzjoni.
- Irkupra l-ID tal-eżekuzzjoni mil-logġijiet jew mir-rispons tal-API
- Ikkonsulta s-sommarju tat-traċċa biex tkun l-istatus u ssib l-attività difettuża fis-siġra tal-ispan
- Eżamina l-avvenimenti dettaljati biex tifhem is-sekwenza li wasslet għall-iżball
- Iċċekkja r-retries: l-attività nbdiet mill-ġdid? Kemm-il darba?
- Analizza l-messaġġ ta’ żball: timeout, żball fin-netwerk, żball tan-negozju?
L-ewwel żewġ passi jistgħu jiġu skriptati f’ftit linji, bl-użu tal-funzjoni display li rajna hawn fuq, u jagħtuk għodla dijanjostika riutilizzabbli.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Pass 1: Sommarju u siġra tal-ispan
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)
# Pass 2: Avvenimenti mill-kodiċi tiegħek, fl-ordni
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)
In-numru ta’ tentattivi jixraqlu attenzjoni speċjali: attività li tfalli fl-ewwel tentattiv u waħda li tfalli wara ħames retries jirrakkontaw stejjer differenti u jsejħu għal soluzzjonijiet differenti.
Riassunt tal-kors
Awguri, lestajt dan il-kors dwar Mistral Workflows. Il-vjaġġ ħadek mill-orkestrazzjoni durabbli u l-mekkaniżmu ta’ event sourcing għall-installazzjoni tal-SDK (lezzjonijiet 1 sa 3), imbagħad għall-ħolqien ta’ attivitajiet, workflows, u ħaddiema, u t-triggering u t-testjar tagħhom (lezzjonijiet 4 sa 7). Il-lezzjonijiet 8 sa 11 stabbilew il-vincoli strutturali—determiniżmu, inputs Pydantic, timeouts, limitazzjonijiet—qabel ma nfetħu għal mudelli avvanzati ta’ parallelizmu u kontinwazzjoni. L-aħħar tlieta koprew il-politiki ta’ retry, ir-rekwiżit għal I/O asinkronu, u l-osservabbiltà b’OpenTelemetry.
Il-pjattaforma tinsab f’Public Preview: l-APIs u l-karatteristiċi jistgħu jevolvu. Iċċekkja d-dokumentazzjoni uffiċjali regolarment fuq docs.mistral.ai/workflows biex issegwi l-aġġornamenti.
Punti Ewlenin
- Kull attività tiġġenera awtomatikament spans OpenTelemetry b’isem, tul ta’ żmien, u status
- Semmi l-attivitajiet tiegħek bil-parametru
namebiex tiffaċilita d-debbuġġar - Tliet metodi biex taċċessa t-traċċi, taħt
client.workflows.executions: OTel mhux ipproċessat, sommarju (status, tul, siġra tal-ispan), u avvenimenti dettaljati - It-teħid ta’ kampjuni huwa kkontrollat mill-parametru
traceparenttal-eżekuzzjoni (100% b’mod predefinit; l-header HTTP huwa deprekat) - Fil-produzzjoni, immonitorja r-rata ta’ suċċess, it-tul ta’ żmien, u r-rata ta’ retry
- Traċċi OTel standard huma esportabbli lejn Datadog, Grafana, Jaeger, jew New Relic
Ittestja l-għarfien tiegħek
Workflows durabbli: regoli tal-magna qabel il-produzzjoni.
1. X' jiggarantixxi l-pjattaforma Mistral Workflows?
Tweġiba: Durabbiltà: workflow jibqa’ ħaj wara fallimenti u jkompli minn fejn waqaf—l-orkestrazzjoni fit-tul issir affidabbli bid-disinn.
2. Attività, workflow, ħaddiem: min jagħmel x'?
Tweġiba: L-attività hija l-unità tax-xogħol (sejħa esterna, kalkolu), il-workflow jorkestra l-attivitajiet, il-ħaddiem jesegwixxi—is-separazzjoni li tippermetti r-ripristinar u s-skalar.
3. X'timponi r-regola tad-determiniżmu?
Tweġiba: Il-kodiċi tal-workflow irid ikun jista’ jiġi rrepetut bl-istess mod: l-ebda każwalità jew aċċess dirett għall-arloġġ fl-orkestrazzjoni—l-effetti mhux deterministiċi jgħixu fl-attivitajiet.
4. Kif jiġu ttrattati l-fallimenti tranżitorji?
Tweġiba: Permezz tal-politika ta’ retry tal-attività (tentattivi, backoff) u timeouts—il-falliment huwa każ normali, immaniġġjat b’mod dikjarattiv aktar milli manwalment.
5. X'tiġib l-integrazzjoni ta' OpenTelemetry?
Tweġiba: Osservabbiltà standard: traċċi ta’ eżekuzzjoni, metriċi, u korrelazzjoni mal-bqija tas-sistema tiegħek—essenzjali biex topera workflows fil-produzzjoni.
Durabbiltà, determiniżmu, retry, osservabbiltà: erba’ regoli li jżommu flimkien orkestrazzjonijiet twal—il-magna tittratta l-bqija.