Explorer : rechercher et inspecter les traces de production

Leçon réécrite le 2 novembre 2026 d’après les pages Send traces et Explore traces de Mistral et le SDK mistralai 3.7.0 : l’Explorer porte sur des traces OpenTelemetry, interrogées par un langage d’expressions de recherche ; l’ancienne méthode chat_completion_events.search n’existe plus. Sources : Send traces · Explore traces.

L’Explorer : votre fenêtre sur la production

L’Explorer de traces est l’endroit où l’on cherche, filtre et inspecte chaque trace qui traverse vos applications d’IA. Il se trouve dans Studio, sous Observability → Traces. Encore faut-il que des traces y arrivent : le traçage est désactivé par défaut.

Envoyer des traces

Avec le SDK Python, installez l’extension de télémétrie (mistralai[telemetry], version 2.4.13 au moins), puis activez-la sur le client :

from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry

client = Mistral(api_key="votre-cle-api")
configure_telemetry(client)

À partir de là, le SDK trace automatiquement les appels aux modèles, les embeddings, les opérations d’agents, les complétions FIM et l’OCR. Les appels à vos propres outils, eux, ne sont pas tracés d’office : ajoutez leurs spans avec le traceur du SDK.

from mistralai.extra.observability import get_telemetry_tracer

tracer = get_telemetry_tracer(client, "agent-support")

with tracer.start_as_current_span("invoke_agent"):
    reponse = client.chat.complete(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "Où en est ma commande 4521 ?"}],
    )
    with tracer.start_as_current_span("execute_tool suivi_commande") as span_outil:
        span_outil.set_attribute("gen_ai.tool.name", "suivi_commande")
        span_outil.set_attribute("gen_ai.tool.call.arguments", "4521")
        # appel à votre outil ici

Les autres sources : les Workflows tracent chaque exécution dès que OTEL_ENABLED=true est positionné sur le service, et Vibe Work s’active par un réglage d’administration dans Studio. Le SDK TypeScript propose configureTelemetry. En revanche, Vibe Code (CLI et Web) et le Playground de Studio n’envoient pas de traces. Toutes les sources masquent par défaut une partie des données avant export ; la page Data redaction décrit cette politique et comment l’ajuster.

Ce que contient une trace

Une trace est un arbre de spans, chaque span représentant une opération de la chaîne :

Un clic sur une trace ouvre son arbre de spans ; chaque span se déplie pour montrer entrée, sortie, latence et tokens.

Le langage de recherche

L’Explorer accepte un langage d’expressions : des conditions sur les champs des traces, combinées par AND, OR et NOT.

Les champs disponibles sont service_name, status_code (Ok ou Error), duration_ns (en nanosecondes), error_message, start_time, models_used (une liste) et n’importe quel attribut de span, en syntaxe à crochets : span_attributes['gen_ai.request.model']. Pour les listes, has(models_used, 'mistral-medium-latest'), hasany(...) et hasall(...) complètent CONTAINS.

# Toutes les traces en échec d'un service
service_name = 'agent-support' AND status_code = 'Error'

# Les traces de plus de 5 secondes
duration_ns > 5000000000

# Les traces qui ont appelé un modèle donné
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'

Quand une recherche ne renvoie rien, retirez toutes les conditions sauf la plage de temps, puis remettez-les une à une : l’erreur classique est de filtrer sur status_code = 'Error' alors que la plupart des traces réussissent.

Interroger les traces par le SDK

Les mêmes recherches se font par programme, sur une plage de temps :

from datetime import datetime, timedelta, timezone

from mistralai.client import Mistral

client = Mistral(api_key="votre-cle-api")
maintenant = datetime.now(timezone.utc)

reponse = client.beta.observability.traces.search(
    from_=maintenant - timedelta(days=1),
    to=maintenant,
    search_expression="service_name = 'agent-support' AND status_code = 'Error'",
    page_size=50,
)

for trace in reponse.traces.results or []:
    print(f"{trace.trace_id} {trace.root_span_name} : {trace.duration_ns / 1e9:.1f} s")

La réponse est paginée par curseur. Les endpoints Traces et Spans de l’API (recherche, trace unique, champs et valeurs possibles, spans d’une trace) sont documentés dans la référence de l’API.

Ajouter des spans à un dataset

L’Explorer sert aussi de point de départ aux jeux de test. Depuis une trace, le menu d’un span propose Add span to dataset ; en vue Spans, vous pouvez en sélectionner jusqu’à 500 à la fois et associer chaque champ de span à un champ d’enregistrement. Cette fonction relève des évaluations hors ligne, réservées aux organisations Enterprise (leçon 15).

Points clés à retenir

• Le traçage est désactivé par défaut : configure_telemetry(client) l’active pour le SDK Python, OTEL_ENABLED=true pour les Workflows
• Les appels aux modèles sont tracés automatiquement, les appels d’outils se tracent à la main avec get_telemetry_tracer
• L’Explorer filtre les traces par un langage d’expressions (service_name, status_code, duration_ns, span_attributes['…'])
• Le SDK expose la même recherche : client.beta.observability.traces.search(search_expression=...)
• Les spans intéressants deviennent des enregistrements de dataset, en un clic ou par lots de 500