Observability en OpenTelemetry
Op deze pagina
Bijgewerkt op 2 november 2026 op basis van
mistralaiSDK 3.7.0: trace-methoden bevinden zich onderclient.workflows.executions; hun asynchrone versies dragen het_async-achtervoegsel (wachten op de synchrone versie mislukt),execution_idwordt doorgegeven als keyword-argument, en responses gevenotel_trace_data,span_treeeneventsbloot (de veldenspans,activity_countoferror_countdie door de oudere versie werden uitgelezen, bestaan niet meer);traceparentwordt doorgegeven als uitvoeringsparameter, aangezien de HTTP-header verouderd is. Bronnen: Workflow observability · client-python.
Waarom u uw workflows moet observeren
Een workflow in productie kan tientallen activiteiten aan elkaar koppelen, meerdere externe services aanroepen en variëren van enkele seconden tot meerdere dagen. Zonder observability is het diagnosticeren van een probleem als het zoeken naar een speld in een hooiberg: u weet dat de uitvoering is mislukt, maar niet bij welke stap, na hoeveel pogingen, of de boosdoener uw eigen code is of een API van derden. Het Mistral Workflows-platform integreert OpenTelemetry native om dit vraagstuk op te lossen: elke activiteit, elke fout en elke duur wordt vastgelegd als een span in een gedistribueerde trace, zonder dat u instrumentatie hoeft toe te passen.
Twee concepten structureren dit model. De trace vertegenwoordigt de volledige reis van een uitvoering, van de initiële trigger tot het eindresultaat. De span daarentegen is een individuele operatie binnen die trace: elke activiteit genereert er automatisch een, met de naam, start- en eindtijden, uitvoeringsduur, status (succes of fout) en eventuele aangepaste attributen. Deze spans vormen een hiërarchie—de workflow-span is de ouder en de activiteit-spans zijn de kinderen—wat de complete structuur van de uitvoering weergeeft.
Geef activiteiten namen voor leesbaarheid
De parameter name van de activity-decorator bepaalt het label dat in traces verschijnt. Het is een investering van tien seconden tijdens het schrijven die u tijdens een incident veel tijd bespaart.
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"}
Verplaats u in de schoenen van de on-call engineer die om 3 uur ‘s nachts een trace-weergave opent. Tussen fetch_user_data en “Retrieve user profile” is het laatste direct begrijpelijk, zelfs voor iemand die deze code nooit heeft gelezen.
Traces programmatisch ophalen
De SDK biedt drie toegangsmethoden onder client.workflows.executions; hun asynchrone versies dragen het _async-achtervoegsel. De eerste geeft ruwe OpenTelemetry-gegevens terug—spans, duur, attributen, ouder-kind-relaties—waarmee u deze opnieuw kunt importeren in uw eigen observability-tool (Jaeger, Grafana Tempo, enz.).
from mistralai.client import Mistral
client = Mistral()
# Ruwe OpenTelemetry-gegevens voor de uitvoering
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 # Volledige trace, om te herexporteren naar uw backend
Wanneer u voornamelijk wilt weten of de uitvoering is gelukt en hoe lang deze heeft geduurd, volstaat de samenvatting. Deze bevat de status, de totale duur en de span-boom, die u recursief kunt doorlopen:
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"Totale duur: {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)
De derde methode geeft een chronologische lijst van uitvoeringsevents terug:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Sluit interne platform-events uit
)
for event in response.events or []:
print(event)
De parameter include_internal_events=False filtert technische platform-events eruit en houdt alleen die van uw workflow en activiteiten over. Bij een iets langere workflow is het verschil in leesbaarheid aanzienlijk. Voor de logs zelf—die worden weergegeven in Studio—geeft get_workflow_execution_logs ze pagina per pagina terug.
Sampling beheersen
Standaard worden alle traces geëxporteerd: de worker samplet op 100%. Om de trace-ID in te stellen of sampling voor een uitvoering te regelen, geeft u een traceparent in W3C-formaat mee in de body van het uitvoeringsverzoek. De worker gebruikt een op de ouder gebaseerde sampler: deze volgt uw beslissing, overgedragen door het laatste veld (01 om te verzamelen, 00 om niet te verzamelen).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
Mistral SDK’s doen dit automatisch: bij elke uitvoering verzenden ze de traceparent van de huidige span. Het doorgeven van traceparent in een HTTP-header wordt nog steeds geaccepteerd maar is verouderd, omdat een header onderweg kan worden herschreven; gebruik in plaats daarvan de parameter.
Monitoring in productie
Vijf indicatoren volstaan om een workflow onder controle te houden: het slagingspercentage, oftewel het percentage uitvoeringen dat zonder fouten eindigt; de gemiddelde duur van een volledige uitvoering; de P95- en P99-duur, die de langzaamste uitvoeringen onthullen die het gemiddelde verbergt; het retry-percentage per activiteit, waarvan een plotselinge stijging een onstabiele externe service verraadt lang voordat het slagingspercentage verslechtert; en tot slot de identificatie van de langzaamste activiteit, uw bottleneck.
Omdat traces de OpenTelemetry-standaard respecteren, bent u niet verplicht ze via de SDK te raadplegen: ze kunnen worden geëxporteerd naar Datadog via de OTel-collector, naar Grafana en Tempo via hetzelfde mechanisme, naar Jaeger voor visualisatie van gedistribueerde traces, of naar New Relic via de daarvoor bestemde exporter. Uw workflows voegen zich zo bij het dashboard waar de rest van uw infrastructuur al leeft.
Een mislukte workflow debuggen
Bij een fout voorkomt een methodische procedure giswerk.
- Haal de execution-ID op uit logs of de API-response
- Raadpleeg de trace-samenvatting om de status te kennen en de foutieve activiteit in de span-boom te lokaliseren
- Onderzoek gedetailleerde events om de reeks te begrijpen die tot de fout heeft geleid
- Controleer retries: is de activiteit opnieuw gestart? Hoe vaak?
- Analyseer de foutmelding: timeout, netwerkfout, zakelijke fout?
De eerste twee stappen kunnen in een paar regels worden gescript, met behulp van de hierboven geziene display-functie, wat u een herbruikbaar diagnostisch hulpmiddel oplevert.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Stap 1: Samenvatting en span-boom
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)
# Stap 2: Events van uw code, in volgorde
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)
Het aantal pogingen verdient speciale aandacht: een activiteit die bij de eerste poging faalt en een die faalt na vijf retries vertellen een ander verhaal en vragen om verschillende oplossingen.
Samenvatting van de cursus
Gefeliciteerd, u heeft deze cursus over Mistral Workflows voltooid. De reis bracht u van duurzame orkestratie en het event sourcing-mechanisme naar het installeren van de SDK (lessen 1 tot 3), vervolgens naar het maken van activiteiten, workflows en workers, het triggeren en testen ervan (lessen 4 tot 7). Lessen 8 tot 11 legden de structurele beperkingen uit—determinisme, Pydantic-inputs, timeouts, beperkingen—voordat ze openstonden voor geavanceerde patronen van parallelisme en continuïteit. De laatste drie behandelden retry-beleid, de vereiste voor asynchrone I/O en observability met OpenTelemetry.
Het platform bevindt zich in Public Preview: API’s en functies kunnen evolueren. Raadpleeg regelmatig de officiële documentatie op docs.mistral.ai/workflows om updates te volgen.
Belangrijkste punten
- Elke activiteit genereert automatisch OpenTelemetry-spans met naam, duur en status
- Geef uw activiteiten namen met de parameter
nameom debugging te vergemakkelijken - Drie methoden om traces te benaderen, onder
client.workflows.executions: ruwe OTel, samenvatting (status, duur, span-boom) en gedetailleerde events - Sampling wordt geregeld door de parameter
traceparentvan de uitvoering (standaard 100%; de HTTP-header is verouderd) - Monitor in productie het slagingspercentage, de duur en het retry-percentage
- Standaard OTel-traces zijn exporteerbaar naar Datadog, Grafana, Jaeger of New Relic
Test uw kennis
Duurzame workflows: engine-regels vóór productie.
1. Wat garandeert het Mistral Workflows-platform?
Antwoord: Duurzaamheid: een workflow overleeft storingen en hervat daar waar het gebleven was—orkestratie van lange duur wordt betrouwbaar by design.
2. Activiteit, workflow, worker: wie doet wat?
Antwoord: De activiteit is de werkeenheid (externe oproep, berekening), de workflow orkestreert activiteiten, de worker voert uit—de scheiding die hervatting en schaling mogelijk maakt.
3. Wat legt de determinismeregel op?
Antwoord: Workflow-code moet identiek opnieuw afspeelbaar zijn: geen willekeur of directe kloktoegang in orkestratie—niet-deterministische effecten leven in activiteiten.
4. Hoe worden tijdelijke storingen afgehandeld?
Antwoord: Via het retry-beleid van de activiteit (pogingen, backoff) en timeouts—mislukking is een normaal geval, declaratief afgehandeld in plaats van handmatig.
5. Wat brengt de OpenTelemetry-integratie?
Antwoord: Standaard observability: uitvoeringstraces, metrieken en correlatie met de rest van uw systeem—essentieel voor het exploiteren van workflows in productie.
Duurzaamheid, determinisme, retry, observability: vier regels die lange orkestraties bij elkaar houden—de engine regelt de rest.