Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Havainnoitavuus ja OpenTelemetry

Oppitunti 14 / 14 Päivitetty 2. marraskuuta 2026 Edistynyt
Tällä sivulla
  1. Miksi workflowjesi havainnoitavuus on tärkeää
  2. Nimeä aktiviteetit luettavuuden vuoksi
  3. Hae tracet ohjelmallisesti
  4. Hallitse otantaa
  5. Valvo tuotannossa
  6. Debuggaa epäonnistunut workflow
  7. Kurssin yhteenveto
  8. Keskeiset asiat
  9. Testaa tietosi

Päivitetty 2. marraskuuta 2026 perustuen mistralai SDK:n versioon 3.7.0: trace-metodit sijaitsevat osoitteessa client.workflows.executions; niiden asynkroniset versiot käyttävät _async-päätettä (synkronisen version odottaminen epäonnistuu), execution_id välitetään avainsana-argumenttina, ja vastaukset paljastavat kentät otel_trace_data, span_tree ja events (vanhemman version lukemat kentät spans, activity_count tai error_count eivät ole enää olemassa); traceparent välitetään suoritusparametrina, sillä HTTP-otsake on vanhentunut. Lähteet: Workflow observability · client-python.

Miksi workflowjesi havainnoitavuus on tärkeää

Tuotannossa oleva workflow voi ketjuttaa kymmeniä aktiviteetteja, kutsua useita ulkoisia palveluita ja kestää muutamasta sekunnista useisiin päiviin. Ilman havainnoitavuutta ongelman diagnosointi on kuin neulan etsimistä heinäsuovasta: tiedät suorituksen epäonnistuneen, mutta et sitä, missä vaiheessa, monennenko yrityksen jälkeen tai onko syyllinen koodissasi vai kolmannen osapuolen rajapinnassa. Mistralin Workflows-alusta integroi OpenTelemetryn natiivisti vastaamaan tähän kysymykseen: jokainen aktiviteetti, virhe ja kesto tallennetaan spanina hajautettuun trace-tietoon ilman, että sinun tarvitsee tehdä mitään instrumentointia.

Kaksi käsitettä jäsentää tätä mallia. Trace edustaa koko suorituksen matkaa alkuperäisestä liipaisimesta lopputulokseen. Span puolestaan on yksittäinen operaatio tuon tracen sisällä: jokainen aktiviteetti generoi automaattisesti oman spaninsa, joka sisältää sen nimen, aloitus- ja lopetusajat, suorituskeston, tilan (onnistuminen tai virhe) sekä mahdolliset mukautetut attribuutit. Nämä spanit muodostavat hierarkian – workflow-span on vanhempi ja aktiviteettispanit sen lapsia – mikä toistaa suorituksen täydellisen rakenteen.

Nimeä aktiviteetit luettavuuden vuoksi

Aktiviteettikoristeen name-parametri määrittää trace-näkymissä näkyvän etiketin. Kymmenen sekunnin sijoitus koodausvaiheessa säästää sinulta paljon aikaa häiriötilanteessa.

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

Asetu niiden kenkiin, jotka ovat päivystyksessä ja avaavat trace-näkymän kello 3 yöllä. Välillä fetch_user_data ja “Retrieve user profile” jälkimmäinen on välittömästi ymmärrettävä, jopa henkilölle, joka ei ole koskaan lukenut tätä koodia.

Hae tracet ohjelmallisesti

SDK tarjoaa kolme käyttötapaa osoitteessa client.workflows.executions; niiden asynkroniset versiot käyttävät _async-päätettä. Ensimmäinen palauttaa raakaa OpenTelemetry-dataa – spanit, kestot, attribuutit, vanhempi-lapsi-suhteet – jolloin voit syöttää sen uudelleen omaan havainnoitavuustyökaluusi (Jaeger, Grafana Tempo jne.).

from mistralai.client import Mistral

client = Mistral()

# Raaka OpenTelemetry-data suoritukselle
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  # Koko trace, vietäväksi omaan taustajärjestelmääsi

Kun haluat pääasiassa tietää, onnistuiko suoritus ja kuinka kauan se kesti, yhteenveto riittää. Se sisältää tilan, kokonaiskeston ja span-puun, jonka voit traversoida rekursiivisesti:

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)

Kolmas metodi palauttaa kronologisen luettelon suorituksen tapahtumista:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Sulje pois alustan sisäiset tapahtumat
)

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

Parametri include_internal_events=False suodattaa pois tekniset alustatapahtumat, jolloin jäljelle jäävät vain workflowsi ja aktiviteettiesi tapahtumat. Hieman pitkässä workflowssa ero luettavuudessa on huomattava. Itse lokien osalta – ne, jotka näkyvät Studiossa – get_workflow_execution_logs palauttaa ne sivu kerrallaan.

Hallitse otantaa

Oletusarvoisesti kaikki tracet viedään: worker ottaa näytteet 100-prosenttisesti. Asettaaksesi trace-tunnisteen tai hallitaksesi otantaa suoritukselle, välitä W3C-muotoinen traceparent suorituspyynnön rungossa. Worker käyttää vanhempiin perustuvaa otantaa: se noudattaa päätöstäsi, jota viimeinen kenttä kuljettaa (01 keräämiseksi, 00 ei keräämiseksi).

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

Mistral SDK:t tekevät tämän automaattisesti: jokaisella suorituksella ne lähettävät nykyisen spanin traceparent-tiedon. traceparent-arvon välittäminen HTTP-otsakkeessa on edelleen hyväksyttyä, mutta vanhentunutta, koska otsake voidaan kirjoittaa uudelleen siirron aikana; käytä sen sijaan parametria.

Valvo tuotannossa

Viisi indikaattoria riittää pitämään workflowsi kurissa: onnistumisprosentti, eli niiden suoritusten osuus, jotka päättyvät ilman virhettä; yhden täydellisen suorituksen keskimääräinen kesto; P95- ja P99-kestot, jotka paljastavat hitaimmat suoritukset, joita keskiarvo peittää; uudelleenyritysten määrä aktiviteettia kohden, jonka äkillinen nousu paljastaa epävakaa ulkoinen palvelu kauan ennen kuin onnistumisprosentti heikkenee; ja lopuksi hitaimman aktiviteetin tunnistaminen, eli pullonkaulasi.

Koska tracet noudattavat OpenTelemetry-standardia, mikään ei pakota sinua tarkastelemaan niitä SDK:n kautta: ne voidaan viedä Datadogiin sen OTel-keräimen kautta, Grafanaan ja Tempoon samalla mekanismilla, Jaegeriin hajautettujen tracejen visualisointia varten tai New Reliciin sen omien vientityökalujen kautta. Workflowsi liittyvät näin siihen kojelautaan, jossa muukin infrastruktuurisi jo elää.

Debuggaa epäonnistunut workflow

Epäonnistumisen edessä metodinen menettely välttää arvailun.

  1. Hae suorituksen tunnus (execution ID) lokeista tai API-vastauksesta
  2. Tarkastele trace-yhteenvetoa saadaksesi selville tilan ja löytääksesi viallisen aktiviteetin span-puusta
  3. Tutki yksityiskohtaisia tapahtumia ymmärtääksesi virheeseen johtaneen sekvenssin
  4. Tarkista uudelleenyritykset: käynnistettiinkö aktiviteetti uudelleen? Kuinka monta kertaa?
  5. Analysoi virheilmoitus: aikakatkaisu, verkkovirhe, liiketoimintavirhe?

Kaksi ensimmäistä vaihetta voidaan skriptata muutamalla rivillä käyttämällä edellä nähtyä display-funktiota, mikä antaa sinulle uudelleenkäytettävän diagnostiikkatyökalun.

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

    # Vaihe 1: Yhteenveto ja span-puu
    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)

    # Vaihe 2: Koodisi tapahtumat järjestyksessä
    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)

Yritysten määrä ansaitsee erityistä huomiota: aktiviteetti, joka epäonnistuu ensimmäisellä yrityksellä, ja sellainen, joka epäonnistuu viiden uudelleenyrityksen jälkeen, kertovat erilaisia tarinoita ja vaativat erilaisia korjauksia.

Kurssin yhteenveto

Onnittelut, olet suorittanut tämän Mistral Workflows -kurssin. Matka vei sinut kestävän orkestroinnin ja tapahtumalähteistyksen mekanismien kautta SDK:n asentamiseen (opetuskerrat 1–3), sitten aktiviteettien, workflowjen ja workerien luomiseen, niiden käynnistämiseen ja testaamiseen (opetuskerrat 4–7). Opetuskerrat 8–11 hahmottelivat rakenteelliset rajoitteet – determinismi, Pydantic-syötteet, aikakatkaisut, rajoitukset – ennen kuin avautuivat rinnakkaisuuden ja jatkuvuuden edistyneisiin malleihin. Kolme viimeistä käsittelivät uudelleenyrityskäytäntöjä, asynkronisen I/O:n vaatimusta ja havainnoitavuutta OpenTelemetryn avulla.

Alusta on Public Preview -vaiheessa: APIt ja ominaisuudet voivat kehittyä. Tarkista virallinen dokumentaatio säännöllisesti osoitteesta docs.mistral.ai/workflows seurataksesi päivityksiä.

Keskeiset asiat

  • Jokainen aktiviteetti generoi automaattisesti OpenTelemetry-spaneja, joissa on nimi, kesto ja tila
  • Nimeä aktiviteettisi name-parametrilla helpottaaksesi vianetsintää
  • Kolme tapaa käyttää traceja osoitteessa client.workflows.executions: raaka OTel, yhteenveto (tila, kesto, span-puu) ja yksityiskohtaiset tapahtumat
  • Otantaa hallitaan suorituksen traceparent-parametrilla (oletus 100 %; HTTP-otsake on vanhentunut)
  • Tuotannossa valvo onnistumisprosenttia, kestoa ja uudelleenyritysten määrää
  • Standardit OTel-tracet ovat vietävissä Datadogiin, Grafanaan, Jaegeriin tai New Reliciin

Testaa tietosi

Kestävät workflowt: moottorin säännöt ennen tuotantoa.

1. Mitä Mistral Workflows -alusta takaa?

Vastaus: Kestävyyden: workflow selviää vioista ja jatkaa siitä, mihin jäi – pitkän keston orkestroinnista tulee luotettavaa suunnittelunsa ansiosta.

2. Aktiviteetti, workflow, worker: kuka tekee mitä?

Vastaus: Aktiviteetti on työyksikkö (ulkoinen kutsu, laskenta), workflow orkestroi aktiviteetit, worker suorittaa – erottelu, joka mahdollistaa jatkamisen ja skaalautuvuuden.

3. Mitä determinismisääntö vaatii?

Vastaus: Workflow-koodin on oltava toistettavissa identtisesti: ei satunnaisuutta eikä suoraa kellon käyttöä orkestroinnissa – ei-deterministiset vaikutukset kuuluvat aktiviteetteihin.

4. Miten ohimenevät viat käsitellään?

Vastaus: Aktiviteetin uudelleenyrityskäytännön (yritykset, backoff) ja aikakatkaisujen kautta – vika on normaali tapaus, jota käsitellään deklaratiivisesti eikä manuaalisesti.

5. Mitä OpenTelemetry-integraatio tuo mukanaan?

Vastaus: Standardin havainnoitavuuden: suoritusjäljet, mittarit ja korrelaation muun järjestelmäsi kanssa – välttämätöntä workflowjen operoinnille tuotannossa.

Kestävyys, determinismi, uudelleenyritys, havainnoitavuus: neljä sääntöä, jotka pitävät pitkät orkestroinnit koossa – moottori hoitaa loput.