Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Osservabilità e OpenTelemetry

Lezione 14 di 14 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Perché osservare i tuoi workflow
  2. Dai nomi alle attività per la leggibilità
  3. Recupera le tracce a livello programmatico
  4. Padroneggia il campionamento
  5. Monitora in produzione
  6. Debugga un workflow fallito
  7. Riepilogo del corso
  8. Punti chiave
  9. Metti alla prova le tue conoscenze

Aggiornato il 2 novembre 2026 in base all’SDK mistralai 3.7.0: i metodi di traccia si trovano sotto client.workflows.executions; le loro versioni asincrone portano il suffisso _async (attendere la versione sincrona fallisce), execution_id viene passato come argomento per nome (keyword argument) e le risposte espongono otel_trace_data, span_tree ed events (i campi spans, activity_count o error_count letti dalla versione precedente non esistono più); traceparent viene passato come parametro di esecuzione, poiché l’intestazione HTTP è deprecata. Fonti: Workflow observability · client-python.

Perché osservare i tuoi workflow

Un workflow in produzione può concatenare decine di attività, chiamare più servizi esterni ed eseguire da pochi secondi a diversi giorni. Senza osservabilità, diagnosticare un problema è come cercare un ago in un pagliaio: sai che l’esecuzione è fallita, ma non in quale fase, dopo quanti tentativi, o se il colpevole è il tuo codice o un’API di terze parti. La piattaforma Workflows di Mistral integra OpenTelemetry nativamente per rispondere a questa domanda: ogni attività, ogni errore e ogni durata viene registrata come uno span in una traccia distribuita, senza che tu debba strumentare nulla.

Due concetti strutturano questo modello. La traccia rappresenta l’intero viaggio di un’esecuzione, dall’innesco iniziale al risultato finale. Lo span, invece, è un’operazione individuale all’interno di quella traccia: ogni attività ne genera automaticamente uno, portando il suo nome, gli orari di inizio e fine, la durata dell’esecuzione, lo stato (successo o errore) e eventuali attributi personalizzati. Questi span formano una gerarchia: lo span del workflow è il genitore e gli span delle attività sono i suoi figli, riproducendo la struttura completa dell’esecuzione.

Dai nomi alle attività per la leggibilità

Il parametro name del decoratore dell’attività determina l’etichetta che appare nelle tracce. È un investimento di dieci secondi durante la scrittura che ti farà risparmiare molto tempo durante un incidente.

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

Mettiti nei panni dell’ingegnere di guardia che apre una vista di traccia alle 3 del mattino. Tra fetch_user_data e “Retrieve user profile”, quest’ultimo è immediatamente comprensibile, anche per qualcuno che non ha mai letto questo codice.

Recupera le tracce a livello programmatico

L’SDK espone tre metodi di accesso sotto client.workflows.executions; le loro versioni asincrone portano il suffisso _async. Il primo restituisce dati OpenTelemetry grezzi: span, durate, attributi, relazioni genitore-figlio, permettendoti di re-inserirli nel tuo strumento di osservabilità (Jaeger, Grafana Tempo, ecc.).

from mistralai.client import Mistral

client = Mistral()

# Dati OpenTelemetry grezzi per l'esecuzione
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  # Traccia completa, da riesportare al tuo backend

Quando vuoi principalmente sapere se l’esecuzione ha avuto successo e quanto tempo ha impiegato, il riepilogo è sufficiente. Include lo stato, la durata totale e l’albero degli span, che puoi attraversare ricorsivamente:

summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
    execution_id="exec_abc123def456"
)

print(f"Workflow: {summary.workflow_name} — stato {summary.status}")
print(f"Durata totale: {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(i)")
    for child in span.children or []:
        display(child, depth + 1)


if summary.span_tree:
    display(summary.span_tree)

Il terzo metodo restituisce un elenco cronologico degli eventi di esecuzione:

response = await client.workflows.executions.get_workflow_execution_trace_events_async(
    execution_id="exec_abc123def456",
    include_internal_events=False,  # Esclude gli eventi interni della piattaforma
)

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

Il parametro include_internal_events=False filtra gli eventi tecnici della piattaforma, mantenendo solo quelli del tuo workflow e delle tue attività. Su un workflow leggermente lungo, la differenza in termini di leggibilità è considerevole. Per i log stessi, quelli visualizzati in Studio, get_workflow_execution_logs li restituisce pagina per pagina.

Padroneggia il campionamento

Per impostazione predefinita, tutte le tracce vengono esportate: il worker campiona al 100%. Per impostare l’ID traccia o controllare il campionamento per un’esecuzione, passa un traceparent in formato W3C nel corpo della richiesta di esecuzione. Il worker utilizza un campionatore basato sul genitore: segue la tua decisione, portata dall’ultimo campo (01 per raccogliere, 00 per non raccogliere).

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

Gli SDK di Mistral lo fanno automaticamente: con ogni esecuzione, trasmettono il traceparent dello span corrente. Passare traceparent in un’intestazione HTTP è ancora accettato ma deprecato, perché un’intestazione può essere riscritta in transito; usa invece il parametro.

Monitora in produzione

Cinque indicatori sono sufficienti per tenere sotto controllo un workflow: il tasso di successo, ovvero la percentuale di esecuzioni che terminano senza errori; la durata media di un’esecuzione completa; le durate P95 e P99, che rivelano le esecuzioni più lente che la media nasconde; il tasso di retry per attività, il cui improvviso aumento tradisce un servizio esterno instabile ben prima che il tasso di successo si degradi; e infine, l’identificazione dell’attività più lenta, il tuo collo di bottiglia.

Poiché le tracce rispettano lo standard OpenTelemetry, nulla ti obbliga a consultarle dall’SDK: possono essere esportate su Datadog tramite il suo collettore OTel, su Grafana e Tempo con lo stesso meccanismo, su Jaeger per la visualizzazione delle tracce distribuite, o su New Relic tramite il suo esportatore dedicato. I tuoi workflow entrano così nella dashboard dove vive già il resto della tua infrastruttura.

Debugga un workflow fallito

Di fronte a un fallimento, una procedura metodica evita di indovinare.

  1. Recupera l’ID di esecuzione dai log o dalla risposta API
  2. Consulta il riepilogo della traccia per conoscere lo stato e individuare l’attività difettosa nell’albero degli span
  3. Esamina gli eventi dettagliati per comprendere la sequenza che ha portato all’errore
  4. Controlla i retry: l’attività è stata riavviata? Quante volte?
  5. Analizza il messaggio di errore: timeout, errore di rete, errore di business?

I primi due passaggi possono essere scriptati in poche righe, utilizzando la funzione display vista sopra, dandoti uno strumento di diagnostica riutilizzabile.

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

    # Passaggio 1: Riepilogo e albero degli span
    summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
    print(f"Stato: {summary.status}")
    if summary.span_tree:
        display(summary.span_tree)

    # Passaggio 2: Eventi dal tuo codice, in ordine
    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)

Il numero di tentativi merita un’attenzione speciale: un’attività che fallisce al primo tentativo e una che fallisce dopo cinque retry raccontano storie diverse e richiedono correzioni diverse.

Riepilogo del corso

Congratulazioni, hai terminato questo corso su Mistral Workflows. Il viaggio ti ha portato dall’orchestrazione durevole e dal meccanismo di event sourcing all’installazione dell’SDK (lezioni da 1 a 3), poi alla creazione di attività, workflow e worker, al loro innesco e testing (lezioni da 4 a 7). Le lezioni da 8 a 11 hanno delineato i vincoli strutturali: determinismo, input Pydantic, timeout, limitazioni, prima di aprirsi a pattern avanzati di parallelismo e continuazione. Le ultime tre hanno coperto le politiche di retry, il requisito per I/O asincroni e l’osservabilità con OpenTelemetry.

La piattaforma è in Public Preview: API e funzionalità possono evolversi. Controlla regolarmente la documentazione ufficiale su docs.mistral.ai/workflows per seguire gli aggiornamenti.

Punti chiave

  • Ogni attività genera automaticamente span OpenTelemetry con nome, durata e stato
  • Dai nomi alle tue attività con il parametro name per facilitare il debug
  • Tre metodi per accedere alle tracce, sotto client.workflows.executions: OTel grezzo, riepilogo (stato, durata, albero degli span) ed eventi dettagliati
  • Il campionamento è controllato dal parametro traceparent dell’esecuzione (100% di default; l’intestazione HTTP è deprecata)
  • In produzione, monitora il tasso di successo, la durata e il tasso di retry
  • Le tracce OTel standard sono esportabili su Datadog, Grafana, Jaeger o New Relic

Metti alla prova le tue conoscenze

Workflow durevoli: regole del motore prima della produzione.

1. Cosa garantisce la piattaforma Mistral Workflows?

Risposta: Durabilità: un workflow sopravvive ai guasti e riprende da dove si era interrotto: l’orchestrazione di lunga durata diventa affidabile per progettazione.

2. Attività, workflow, worker: chi fa cosa?

Risposta: L’attività è l’unità di lavoro (chiamata esterna, calcolo), il workflow orchestra le attività, il worker esegue: la separazione che abilita la ripresa e lo scaling.

3. Cosa impone la regola del determinismo?

Risposta: Il codice del workflow deve essere riproducibile in modo identico: niente casualità o accesso diretto all’orologio nell’orchestrazione: gli effetti non deterministici vivono nelle attività.

4. Come vengono gestiti i guasti transitori?

Risposta: Tramite la politica di retry dell’attività (tentativi, backoff) e i timeout: il fallimento è un caso normale, gestito in modo dichiarativo piuttosto che manuale.

5. Cosa porta l'integrazione OpenTelemetry?

Risposta: Osservabilità standard: tracce di esecuzione, metriche e correlazione con il resto del tuo sistema: essenziale per operare i workflow in produzione.

Durabilità, determinismo, retry, osservabilità: quattro regole che tengono insieme le orchestrazioni di lunga durata: il motore gestisce il resto.