Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Esplora: Cerca e ispeziona le tracce di produzione

Lezione 12 di 16 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. L’Explorer: la tua finestra sulla produzione
  2. Invio delle tracce
  3. Cosa contiene una traccia
  4. Il linguaggio di ricerca
  5. Interrogazione delle tracce tramite SDK
  6. Aggiunta di span a un dataset
  7. Punti chiave

Lezione riscritta il 2 novembre 2026 sulla base delle pagine Send traces e Explore traces di Mistral e dell’SDK mistralai 3.7.0: l’Explorer si concentra sulle tracce OpenTelemetry interrogate tramite un linguaggio di espressione di ricerca; il metodo legacy chat_completion_events.search non 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:

CampoContenuto
Trace IDIdentificatore dell’intera catena di esecuzione
SpansOperazioni: chiamate ai modelli, chiamate a strumenti, passaggi del workflow
DurataTempo per ogni span e per l’intera traccia
TokenToken di input e output per ogni chiamata al modello
StatoSuccesso o errore, incluso il messaggio di errore
SorgenteProdotto di origine: SDK, Workflows, Vibe Work
TagEtichette 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.

CategoriaOperatoriEsempio
Confronto=, !=, <, <=, >, >=duration_ns > 5000000000
PatternLIKE, ILIKE, NOT LIKEservice_name LIKE '%agent%'
SottostringaCONTAINS, NOT CONTAINSservice_name CONTAINS 'sdk'
Espressione regolareREGEXP, NOT REGEXPservice_name REGEXP '^my-'
IntervalloBETWEEN ... AND ...duration_ns BETWEEN 1000000 AND 5000000000
ListaIN (...), NOT IN (...)status_code IN ('Error', 'Ok')
PresenzaEXISTS, NOT EXISTSerror_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=true per 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