Exploiter les metadata

Vous attachez des labels et des annotations (données JSON libres) côté SDK (voir Labels & annotations). Cette page explique comment les exploiter dans la plateforme : colonnes Explore, filtres, recherche, onglet Metadata d'une session, sélection des juges et triage. C'est la question la plus fréquente une fois l'instrumentation en place : « j'envoie des metadata, maintenant j'en fais quoi ? ».

payload(step, "input", data, content,
  annotations={
    "user.email": "ana@acme.io",
    "request.intent": "refund",
  })

Rappel : deux mécanismes, deux usages

De l'annotation à la colonne Explore

Toute annotation peut devenir une colonne personnalisée dans Explore (affichable, triable et filtrable) en pointant son chemin JSON.

1. 1

   Ouvrir le sélecteur de colonnes

   Dans Explore, ouvrez Colonnes (le sélecteur en haut de la table). Trois familles y cohabitent : colonnes standard, métriques découvertes, et champs custom.

2. 2

   Choisir un champ custom

   Parcourez les chemins d'annotation découverts sur vos events (regroupés par racine, ex. flow › branch › group) ou saisissez le chemin directement, par exemple annotations.user.email.

3. 3

   Exploiter la colonne

   La colonne apparaît dans la table, avec un libellé humanisé (user_email → « User Email »). Elle devient triable, alimente les filtres et la recherche. Réordonnez par glisser-déposer ; retirez-la d'un clic.

Filtrer, trier, chercher

Le panneau Filtres (à côté de la recherche) adapte son contrôle au type de la colonne :

• Recherche plein-texte : par id, contenu, ou valeur d'annotation (indexée par Typesense). Tapez refund pour retrouver toutes les traces dont une annotation vaut « refund ».
• Les filtres suivent vos colonnes : seules les colonnes actives sont filtrables. Ajoutez la colonne d'abord, puis filtrez dessus.

L'onglet Metadata d'une session

Ouvrez une session (Explore → Sessions), puis l'onglet Metadata. Il répond à « quelle est la metadata de cette conversation, et qu'est-ce qui change d'un tour à l'autre ? ».

• Les trois ensembles, Annotations, Context et Labels, reflètent exactement ce que votre SDK a envoyé, après propagation flow → step → event.
• Chaque carte de tour est cliquable : le bouton « aller au tour » bascule sur l'onglet Conversation et met le tour en surbrillance. Inversement, depuis la Conversation, un tour renvoie vers sa metadata (saut conversation → metadata).
• L'onglet Models voisin fait la même lecture pour les modèles appelés par tour (fournisseur, tokens, coût, latence, paramètres d'échantillonnage).

Router la sélection par label

Les labels ne servent pas qu'à filtrer l'affichage : ils pilotent la sélection système.

• Ciblage des juges : une liaison de juge se scope à un SIA, un asset et un déclencheur, et peut cibler des labels (ex. n'évaluer que les events x.crm.segment = vip). Voir Juges.
• Regroupement & indexation : les labels réservés (env, team, flow.phase, asset.role…) structurent l'agrégation des KPIs et l'indexation ; vos labels x. s'y ajoutent.

Metadata au moment du triage

Les alertes se déclenchent sur des métriques et des verdicts de juge, pas sur des annotations arbitraires. Mais quand une alerte ou un score faible vous amène sur une trace, ce sont vos annotations et votre contexte qui donnent le sens métier : quel utilisateur, quel segment, quelle intention. C'est ce qui transforme « une latence a dépassé le seuil » en « le parcours refund des clients vip ralentit ». Enrichissez pour trier vite. Voir Alerting.

Patterns courants

Dépannage