Esplora: Cerca e ispeziona le tracce di produzione
In questa pagina
Lezione riscritta il 2 novembre 2026 sulla base delle pagine Send traces e Explore traces di Mistral e dell’SDK
mistralai3.7.0: l’Explorer si concentra sulle tracce OpenTelemetry interrogate tramite un linguaggio di espressione di ricerca; il metodo legacychat_completion_events.searchnon esiste più. Fonti: Send traces · Explore traces.
L’Explorer: la tua finestra sulla produzione
Il Trace Explorer è il luogo in cui cerchi, filtri e ispezioni ogni traccia che fluisce attraverso le tue applicazioni di intelligenza artificiale. Lo trovi in Studio sotto Observability → Traces. Tuttavia, le tracce non appariranno lì a meno che tu non le abiliti prima: la tracciatura è disabilitata per impostazione predefinita.
Invio delle tracce
Con l’SDK Python, installa l’estensione di telemetria (mistralai[telemetry], versione 2.4.13 o successiva), quindi abilitala sul client:
from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry
client = Mistral(api_key="your-api-key")
configure_telemetry(client)
Da quel momento in poi, l’SDK traccia automaticamente le chiamate ai modelli, gli embedding, le operazioni degli agent, i completamenti FIM e l’OCR. Le chiamate ai tuoi strumenti personalizzati non vengono tracciate di default: devi aggiungere i relativi span utilizzando il tracer dell’SDK.
from mistralai.extra.observability import get_telemetry_tracer
tracer = get_telemetry_tracer(client, "agent-support")
with tracer.start_as_current_span("invoke_agent"):
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": "What is the status of order 4521?"}],
)
with tracer.start_as_current_span("execute_tool order_tracking") as span_tool:
span_tool.set_attribute("gen_ai.tool.name", "order_tracking")
span_tool.set_attribute("gen_ai.tool.call.arguments", "4521")
# call your tool here
Altre fonti si comportano in modo diverso: Workflows traccia ogni esecuzione non appena OTEL_ENABLED=true è impostato sul servizio, mentre Vibe Work si attiva tramite un’impostazione amministrativa in Studio. L’SDK TypeScript offre configureTelemetry. Al contrario, Vibe Code (CLI e Web) e lo Studio Playground non inviano tracce. Tutte le fonti oscurano parte dei dati per impostazione predefinita prima dell’esportazione; la pagina Data redaction dettaglia questa politica e come modificarla.
Cosa contiene una traccia
Una traccia è un albero di span, dove ogni span rappresenta un’operazione nella catena:
| Campo | Contenuto |
|---|---|
| Trace ID | Identificatore dell’intera catena di esecuzione |
| Spans | Operazioni: chiamate ai modelli, chiamate a strumenti, passaggi del workflow |
| Durata | Tempo per ogni span e per l’intera traccia |
| Token | Token di input e output per ogni chiamata al modello |
| Stato | Successo o errore, incluso il messaggio di errore |
| Sorgente | Prodotto di origine: SDK, Workflows, Vibe Work |
| Tag | Etichette applicate dall’SDK e metadati automatici, come il modello |
Facendo clic su una traccia si apre il suo albero di span; ogni span si espande per mostrare input, output, latenza e token.
Il linguaggio di ricerca
L’Explorer accetta un linguaggio di espressione: condizioni sui campi delle tracce combinate con AND, OR e NOT.
| Categoria | Operatori | Esempio |
|---|---|---|
| Confronto | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Pattern | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Sottostringa | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Espressione regolare | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Intervallo | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Lista | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Presenza | EXISTS, NOT EXISTS | error_message EXISTS |
I campi disponibili includono service_name, status_code (Ok o Error), duration_ns (in nanosecondi), error_message, start_time, models_used (una lista) e qualsiasi attributo di span utilizzando la sintassi con parentesi quadre: span_attributes['gen_ai.request.model']. Per le liste, has(models_used, 'mistral-medium-latest'), hasany(...) e hasall(...) completano CONTAINS.
# Tutte le tracce fallite da un servizio
service_name = 'agent-support' AND status_code = 'Error'
# Tracce più lunghe di 5 secondi
duration_ns > 5000000000
# Tracce che hanno chiamato un modello specifico
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Se una ricerca non restituisce risultati, rimuovi tutte le condizioni tranne l’intervallo di tempo, quindi riaggiungile una alla volta. Un errore comune è filtrare per status_code = 'Error' quando la maggior parte delle tracce ha successo.
Interrogazione delle tracce tramite SDK
Puoi eseguire le stesse ricerche a livello di codice su un intervallo di tempo:
from datetime import datetime, timedelta, timezone
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
now = datetime.now(timezone.utc)
response = client.beta.observability.traces.search(
from_=now - timedelta(days=1),
to=now,
search_expression="service_name = 'agent-support' AND status_code = 'Error'",
page_size=50,
)
for trace in response.traces.results or []:
print(f"{trace.trace_id} {trace.root_span_name} : {trace.duration_ns / 1e9:.1f} s")
La risposta utilizza la paginazione basata su cursore. Il riferimento API documenta gli endpoint Traces e Spans (ricerca, singola traccia, campi e valori possibili, span di una traccia).
Aggiunta di span a un dataset
L’Explorer funge anche da punto di partenza per i dataset di test. Da una traccia, il menu di uno span offre Add span to dataset; nella vista Spans, puoi selezionarne fino a 500 alla volta e mappare ogni campo dello span su un campo del record. Questa funzione riguarda le valutazioni offline, riservate alle organizzazioni Enterprise (Lezione 15).
Punti chiave
- La tracciatura è disabilitata per impostazione predefinita:
configure_telemetry(client)la abilita per l’SDK Python,OTEL_ENABLED=trueper Workflows - Le chiamate ai modelli vengono tracciate automaticamente; le chiamate agli strumenti richiedono una tracciatura manuale con
get_telemetry_tracer - L’Explorer filtra le tracce utilizzando un linguaggio di espressione (
service_name,status_code,duration_ns,span_attributes['…']) - L’SDK espone la stessa capacità di ricerca:
client.beta.observability.traces.search(search_expression=...) - Gli span interessanti diventano record di dataset con un singolo clic o in batch da 500