Explorer les traces
L’Explorateur de traces permet de rechercher, filtrer et inspecter chaque trace traversant vos applications IA. Il est disponible dans Studio sous Observabilité → Traces.
Avant de pouvoir explorer les traces, votre application doit être instrumentée. Consultez Envoyer des traces pour les instructions de configuration.
Contenu des traces
Chaque trace est un arbre de spans. Chaque span représente une opération dans la chaîne d’exécution.
| Champ | Description |
|---|---|
| ID de trace | Identifiant unique pour la chaîne d’exécution complète |
| Spans | Opérations individuelles : appels au modèle, appels d’outils, étapes de workflow |
| Durée | Temps écoulé pour chaque span et pour l’intégralité de la trace |
| Nombre de tokens | Tokens d’entrée et de sortie par appel de modèle |
| Statut | Succès ou erreur, avec les messages d’erreur le cas échéant |
| Source | Produit ayant généré la trace (SDK, Workflows, Vibe Work, Managed Agents) |
| Tags | Tags personnalisés depuis l’utilisation du SDK, ainsi que des métadonnées automatiques comme le nom du modèle |
Cliquez sur une trace dans la liste pour ouvrir l’arbre des spans. Développez les spans individuels pour inspecter les entrées, les sorties, la latence et l’utilisation des tokens à chaque étape.
Recherche et filtrage
L’Explorateur accepte un langage d’expression de recherche : écrivez des conditions sur les champs de trace et combinez-les avec AND, OR et NOT.
Opérateurs
| Catégorie | Opérateurs | Exemple |
|---|---|---|
| Comparaison | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Correspondance de motif | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Sous-chaîne | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Expression rationnelle | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Plage | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Liste | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Vérification de nullité | EXISTS, NOT EXISTS | error_message EXISTS |
| Booléen | AND, OR, NOT, () | status_code = 'Error' AND duration_ns > 1000000 |
Champs disponibles
| Champ | Type | Description |
|---|---|---|
service_name | chaîne de caractères | Nom du service ayant Produit la trace |
status_code | chaîne de caractères | Statut de la trace : Ok ou Error |
duration_ns | nombre | Durée totale de la trace en nanosecondes |
error_message | chaîne de caractères | Message d’erreur si la trace a échoué |
start_time | horodatage | Moment où la trace a commencé (ISO 8601) |
models_used | tableau | Modèles appelés dans la trace |
span_attributes['key'] | valeur de mappage | Tout attribut de span, en utilisant la syntaxe entre crochets |
Requêtes sur les attributs de span
Utilisez la syntaxe entre crochets pour filtrer sur n’importe quel attribut de span OpenTelemetry :
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
span_attributes['gen_ai.operation.name'] = 'chat'
span_attributes['custom.tag'] EXISTSChamps de type tableau
Pour les champs de type tableau comme models_used :
| Fonction | Exemple |
|---|---|
CONTAINS | models_used CONTAINS 'mistral-medium-latest' |
has(field, value) | has(models_used, 'mistral-medium-latest') |
hasany(field, [values]) | hasany(models_used, ['mistral-large-latest', 'mistral-small-latest']) |
hasall(field, [values]) | hasall(models_used, ['mistral-large-latest', 'mistral-small-latest']) |
Exemples courants
# All failed traces from a specific service
service_name = 'my-agent' AND status_code = 'Error'
# Traces slower than 5 seconds
duration_ns > 5000000000
# Traces using a specific model
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'Traces des Managed Agents
Chaque tour d’une session Managed Agents correspond à une trace. Le span racine est invoke_agent <nom de l’agent>, avec en dessous les appels au modèle (chat) et les appels d’outils (execute_tool) du tour. Les appels d’outils effectués par un programme run_typescript sont imbriqués sous le span de ce programme.
Un sous-agent ne crée pas sa propre trace. Son tour apparaît dans la trace du parent, sous le span d’outil agents.spawn ou agents.send_message qui l’a lancé :
invoke_agent support-bot
├── chat
├── execute_tool agents.spawn
│ └── invoke_agent researcher
│ ├── chat
│ └── execute_tool web_search
└── chatCes attributs relient les spans à la session à laquelle ils appartiennent :
| Attribut | Description |
|---|---|
gen_ai.conversation.id | ID de la session. Les spans d’un sous-agent portent l’ID de session propre au sous-agent. |
mistral.turn.id | ID du tour dans la session. Les ID de tour ne sont uniques qu’au sein d’une session. |
mistral.conversation.parent.id | Sur les spans d’un sous-agent, ID de la session parente. |
gen_ai.agent.name, gen_ai.agent.id | Agent qui a exécuté le tour, sur le span invoke_agent. |
Pour ouvrir la session à laquelle appartient une trace, sélectionnez le span racine invoke_agent et choisissez Aller à la session de l'agent dans le menu d’actions du span.
Pour trouver la trace d’un tour, filtrez à la fois sur l’ID de session et sur l’ID de tour :
span_attributes['gen_ai.conversation.id'] = '<session_id>' AND span_attributes['mistral.turn.id'] = '<turn_id>'Requêter les traces par programmation
Toutes les données de trace sont accessibles via l’API REST. Les endpoints sont documentés dans la référence de l’API :
- Traces : recherche de traces, récupération d’une seule trace, liste des champs et des options de champ.
- Spans : liste des spans pour une trace, requête d’évaluations de span.
Accès
La lecture des traces nécessite une organisation Enterprise et l’un des rôles suivants :
| Rôle | Accès |
|---|---|
| Admin Org | Toutes les traces sur tous les espaces de travail |
| Workspace Admin | Toutes les traces dans son espace de travail |
| Observability Viewer | Toutes les traces dans son espace de travail (lecture seule) |
Un Workspace Admin ou un Admin Org peut attribuer le rôle Observability Viewer pour accorder un accès en lecture seule sans privilèges d’administrateur.