Guide de démarrage : envoyer votre première trace

Ce guide de démarrage instrumente un script Python avec le SDK Mistral, envoie une requête tracée et vous montre la trace dans le Trace Explorer de Studio. Une trace est un arbre de spans : chaque span correspond à une étape de la requête, avec son entrée, sa sortie, sa latence et le nombre de tokens.

Vous avez besoin de Python 3.10 ou version ultérieure, de uv et d'une clé API Mistral.

Créez un projet et ajoutez le SDK Mistral avec son extra telemetry :

uv init first-trace && cd first-trace
uv add "mistralai[telemetry]"
export MISTRAL_API_KEY="your-api-key"

uv init first-trace && cd first-trace
uv add "mistralai[telemetry]"
export MISTRAL_API_KEY="your-api-key"

Remplacez le contenu de main.py par ce script. configure_telemetry active le tracing pour le client. Le script encapsule ensuite une requête de chat et un appel d'outil simulé dans un span parent, de sorte que la trace comporte plusieurs étapes :

import os

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

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
configure_telemetry(client)
tracer = get_telemetry_tracer(client, "first-trace")

with tracer.start_as_current_span("invoke_agent"):
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "Explain distributed tracing in one sentence."}],
    )
    print(response.choices[0].message.content)

    with tracer.start_as_current_span("execute_tool web_search") as tool_span:
        tool_span.set_attribute("gen_ai.tool.name", "web_search")
        tool_span.set_attribute("gen_ai.tool.call.arguments", "distributed tracing")

import os

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

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
configure_telemetry(client)
tracer = get_telemetry_tracer(client, "first-trace")

with tracer.start_as_current_span("invoke_agent"):
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "Explain distributed tracing in one sentence."}],
    )
    print(response.choices[0].message.content)

    with tracer.start_as_current_span("execute_tool web_search") as tool_span:
        tool_span.set_attribute("gen_ai.tool.name", "web_search")
        tool_span.set_attribute("gen_ai.tool.call.arguments", "distributed tracing")

Exécutez-le :

uv run main.py

uv run main.py

Le script affiche la réponse du modèle. Le SDK trace la requête de chat automatiquement. Les appels d'outils ne sont pas tracés automatiquement, c'est pourquoi le script ajoute lui-même le span execute_tool.

Ouvrez le Trace Explorer dans Studio. La trace apparaît en quelques secondes. Cliquez dessus pour ouvrir l'arbre des spans :

• invoke_agent, le span parent que vous avez créé.
• En dessous, la requête de chat, avec le prompt, la réponse, le modèle, la latence et le nombre de tokens en entrée et en sortie.
• Le span execute_tool web_search, avec le nom de l'outil et les arguments que vous avez définis.

Les spans font l'objet d'un masquage côté client avant l'exportation : par défaut, le SDK masque les secrets et données personnelles reconnus, comme les clés API et les adresses e-mail, et conserve le reste du contenu. Voir Masquage des données.

Si aucune trace n'apparaît, vérifiez que :

1. Vous avez appelé configure_telemetry(client) avant la première requête.
2. Votre clé API appartient à un espace de travail Entreprise avec Observabilité activée.
3. Votre rôle dans l'espace de travail est Org Admin, Workspace Admin ou Observability Viewer.

Les traces sont conservées pendant 30 jours.