Labels & annotations
Deux mécanismes pour enrichir vos traces, aux rôles bien distincts. Les confondre est l'erreur d'intégration la plus fréquente.
Courts, stables, indexés. Préfixe x. pour le custom.
- filtrer
- router · déclencher des juges
- indexer · regrouper
{ "env": "prod", "x.crm.segment": "vip" }JSON libre, descriptif. Non utilisé pour sélectionner.
- notes métier · explication
- détails de config
- colonne custom dans Explore
{ "user.email": "ana@acme.io", "llm.temperature": 0.7 }- Labels = pour sélectionner : filtrer, router, déclencher des juges, indexer, regrouper.
Courts, stables. Les clés custom doivent commencer par
x.. - Annotations = pour décrire : notes métier, config, contexte. JSON libre, non utilisé pour la sélection système.
Ajouter labels & annotations
Aux trois niveaux : flow, step, event. Chaque paramètre est optionnel et s'ajoute sur n'importe quelle primitive.
# niveau flow — hérité par tous les steps et eventsflow = start_flow(client, flow_definition_id="support_bot", name="support_bot_main", labels={"env": "prod", "team": "support", "x.crm.segment": "vip"}, annotations={"user.email": "ana@acme.io", "user.locale": "fr-FR"})# niveau stepstep = start_step(flow, asset=asset, flow=Flow(name="support_bot_main"), annotations={"llm.temperature": 0.7, "retrieval.top_k": 10})# niveau event (ponctuel)payload(step, "input", data, content, annotations={"request.intent": "refund"})Propagation & merge
Les labels et annotations sont hérités et fusionnés de haut en bas : un record final cumule les clés du flow, du step et de l'event. En cas de conflit, le plus spécifique gagne (event > step > flow).
Conséquence pratique
Posez le contexte stable (utilisateur, locale, environnement) au niveau du flow : il apparaîtra sur tous les records sans le répéter.
Conventions de nommage
| Règle | Exemples | |
|---|---|---|
| Labels réservés | Clés système | env, tenant, product, team, flow.phase, flow.step, asset.role, lang, batch.id |
| Labels custom | Préfixe x. obligatoire, minuscules, . / _ | x.crm.segment, x.ui.screen, x.feature.variant |
| Annotations | Texte libre, dot-notation conseillée | user.email, request.intent, llm.temperature |
| À ne jamais mettre en label | IDs, prompts, gros JSON | trace_id, span_id, prompt complet |
Le but : ce que ça débloque dans Explore
C'est ici que l'enrichissement paie. Une annotation peut devenir une colonne custom dans Explore : affichable, triable, filtrable, et cherchable en plein-texte (Typesense).
payload(step, "input", data, content,
annotations={
"user.email": "ana@acme.io",
"request.intent": "refund",
})colonne custom · filtre · recherche plein-texte
Dans le cockpit : Explore → colonnes → ajoutez une colonne pointant un chemin JSON, par exemple
annotations.user_email. Elle apparaît dans la table, devient triable, et alimente les filtres et
la recherche. Vous retrouvez ainsi « toutes les traces de tel utilisateur » ou
« toutes les requêtes d'intention refund ».
Ce n'est qu'un début : colonnes custom, filtres typés, recherche, onglet Metadata d'une session, ciblage des juges par label… tout est réuni côté plateforme dans Exploiter les metadata.