Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Osservabbiltà u OpenTelemetry

Lezzjoni 14 / 14 Aġġornat 2 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. Għaliex tosserva l-workflows tiegħek
  2. Semmi l-attivitajiet għal leġġibbiltà
  3. Irkupra t-traċċi programmatikament
  4. Ikkontrolla t-teħid ta’ kampjuni (Sampling)
  5. Immonitorja fil-produzzjoni
  6. Iddebbuja workflow li falla
  7. Riassunt tal-kors
  8. Punti Ewlenin
  9. Ittestja l-għarfien tiegħek

Aġġornat fit-2 ta’ Novembru 2026 abbażi tal-SDK mistralai 3.7.0: il-metodi tat-traċċar jinsabu taħt client.workflows.executions; il-verżjonijiet asinkroni tagħhom iġorru s-suffiss _async (li tistenna l-verżjoni sinkrona tfalli), execution_id jgħaddi bħala argument keyword, u r-risposti jesponu otel_trace_data, span_tree, u events (il-kampi spans, activity_count, jew error_count moqrija mill-verżjoni antika ma jeżistux aktar); traceparent jgħ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.

  1. Irkupra l-ID tal-eżekuzzjoni mil-logġijiet jew mir-rispons tal-API
  2. Ikkonsulta s-sommarju tat-traċċa biex tkun l-istatus u ssib l-attività difettuża fis-siġra tal-ispan
  3. Eżamina l-avvenimenti dettaljati biex tifhem is-sekwenza li wasslet għall-iżball
  4. Iċċekkja r-retries: l-attività nbdiet mill-ġdid? Kemm-il darba?
  5. 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 name biex 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 traceparent tal-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.