Configurer une expérience en ligne sur une application LLM

Une expérience en ligne divise le trafic actif entre une version control et une version treatment d'une application LLM. Un feature flag Datadog assigne chaque subject à une variante, et un score d'évaluation Agent Observability (plus le coût et l'utilisation des tokens) mesure le résultat. Cette compétence parcourt toute la configuration, du flag au démarrage de l'expérience.

Les expériences en ligne pour Agent Observability peuvent nécessiter que la fonctionnalité soit activée pour l'organisation de l'utilisateur. Si une étape signale que la fonctionnalité n'est pas disponible, demandez à l'utilisateur de contacter son représentant Datadog plutôt que de relancer.

Quand utiliser cette compétence

• L'utilisateur veut tester une modification (prompt, modèle, stratégie de retrieval, ensemble d'outils) sur le trafic réel plutôt que sur un ensemble de données fixe.
• L'utilisateur a une modification sur une branche et veut savoir si elle est meilleure, moins chère, ou les deux en production.
• L'utilisateur veut une expérience dont les métriques proviennent des évaluations Agent Observability, des comptages de tokens ou du coût.

Ne l'utilisez pas pour les expériences hors ligne sur un ensemble de données (utilisez les outils d'expérimentation LLM Observability), pour analyser une expérience déjà exécutée (agent-observability-experiment-analyzer ou les outils d'expérimentation Datadog), ou pour promouvoir une expérience hors ligne existante.

Règles de base

• Utilisez un seul point de contrôle d'approbation de configuration. Avant tout écrit, terminez la découverte en lecture seule en Phase 0, faites des recommandations sensées, et présentez la configuration complète proposée dans une seule demande de confirmation. Incluez le flag, les variantes, les définitions de métriques ou les ID de métriques réutilisés, les directions de changement souhaité, l'environnement, le subject, la répartition du trafic, la modification du code, et chaque écriture organisationnelle que vous avez l'intention de faire. Une fois que l'utilisateur approuve cette proposition, ne demandez pas à nouveau avant chaque flag, brouillon, lien, métrique, activation ou écriture d'allocation qui a été clairement énumérée.
• Rendez le risque de production explicite à ce même point de contrôle. Si la proposition active un flag de production ou remplace les allocations de production, dites que le changement prend effet immédiatement. Une approbation claire de cette proposition de production suffit ; n'ajoutez pas une deuxième confirmation qui répète la même information. Ne demandez à nouveau que si la relecture révèle un remplacement matériellement différent ou destructeur qui n'était pas dans la proposition approuvée.
• Le démarrage est séparé sauf s'il est déjà explicite. Démarrez seulement si l'utilisateur a explicitement demandé le démarrage de l'expérience. Si la demande originale comprenait le démarrage, incluez-le dans la proposition de configuration unique ; sinon, terminez avec un brouillon et ne posez pas de question de démarrage jusqu'à ce que l'utilisateur la demande.
• Allez étape par étape et relisez. Après chaque écrit, relisez l'objet et signalez ce que le serveur a réellement stocké, pas ce que vous avez envoyé.
• N'attachez jamais les métriques en parallèle ou aux côtés d'autres modifications de métriques. L'opération d'attachement envoie l'ensemble complet des métriques de l'expérience au serveur, de sorte que les modifications concurrentes peuvent s'écraser mutuellement.
• Signalez les défaillances clairement. Si une étape est refusée (permissions, restrictions de production), dites-le et donnez à l'utilisateur l'alternative manuelle. Ne cherchez pas de contournement.
• Ne devinez pas les identifiants. Les ID d'environnement, les ID de flag, les ID de métrique et les clés de variante proviennent tous du serveur.

Phase 0 — Découvrir, recommander et confirmer une seule fois

N'interrompez pas l'investigation pour demander une entrée à la fois. D'abord effectuez toute la découverte disponible en lecture seule :

• Inspectez la liste des outils actifs et vérifiez que la session possède les capacités llmobs, experiments et feature-flags requises par ce flux de travail : découverte d'environnement ; recherche, création, activation et gestion d'allocation de flags ; recherche, création, liaison et démarrage d'expérience ; et recherche, création et attachement de métrique d'expérience. La configuration du toolset de la compétence contrôle sa visibilité avec une sémantique OR ; elle ne garantit pas que les trois toolsets sont activés. Si des capacités manquent, signalez chaque groupe manquant et le toolset à activer, puis arrêtez avant tout écrit au lieu de relancer des opérations individuelles à plusieurs reprises.
• Inspectez l'application et sa configuration de déploiement. Confirmez qu'elle rapporte à Agent Observability, trouvez où elle soumet les évaluations (si elle le fait), trouvez le chemin de code que la modification treatment change, et déduisez son ml_app, DD_ENV, et l'identifiant stable du subject.
• Énumérez les environnements, recherchez un flag et une expérience existants pour la modification proposée, et recherchez les métriques d'expérience existantes avant de proposer de nouveaux objets.

Puis établissez la proposition complète. Déduisez du contexte et utilisez les valeurs par défaut ci-dessous partout où c'est raisonnable :

Quand la recherche de nom de métrique est nécessaire, essayez d'abord les variantes de nommage avant de conclure qu'aucune métrique n'existe : espaces, tirets, traits de soulignement et une sous-chaîne significative. Inspectez les définitions en double plutôt que de choisir par le nom seul. Préférez une définition déjà utilisée par des expériences actives seulement quand sa source, ses colonnes, ses filtres, son agrégation et sa direction de changement souhaitée correspondent à la proposition. Ne déduisez pas la portée ML-app du nom d'une métrique. Si la métrique existante demandée par l'utilisateur manque un filtre ML-app ou diffère autrement de la définition recommandée, divulguez-le dans la proposition et recommandez s'il faut la réutiliser ou la remplacer.

Présentez une demande de confirmation unique et compacte contenant :

• l'application et le ml_app ;
• le control, le treatment et l'hypothèse ;
• la clé du flag proposée et les variantes booléennes ;
• l'identifiant du subject et le lieu du code où le flag sera évalué ;
• l'environnement cible et la répartition 50/50 ou proposée ;
• la métrique d'évaluation primaire, la définition stockée ou la définition proposée, et la direction de changement souhaitée ;
• les métriques secondaires de token et de coût ;
• si les objets existants seront réutilisés ou de nouveaux créés ;
• la liste complète des écritures, y compris l'activation/allocation de production le cas échéant ;
• si le démarrage est inclus (seulement quand l'utilisateur l'a déjà demandé).

Terminez par une question : Confirmez cette configuration complète, ou dites-moi ce que je dois changer. Utilisez les questions de suivi seulement pour une ambiguïté véritablement bloquante qui ne peut pas être résolue à partir du code, de l'état du serveur ou d'une valeur par défaut sûre.

Phase 1 — Créer le feature flag

Créez un flag booléen avec deux variantes : control = false et treatment = true. Rendez control la variante par défaut.

• Ne pas ajouter d'allocations, de règles de ciblage ou de rollout de pourcentage lors de la création du flag. Le lier à une expérience ne crée pas d'allocation par lui-même : créez ou mettez à jour une allocation FEATURE_GATE liée à l'expérience en Phase 5 après la liaison. Les règles supplémentaires interfèrent avec la répartition.
• Vérifiez d'abord si un flag avec cette clé existe déjà, et réutilisez-le si l'utilisateur dit oui.
• Si l'organisation n'a aucun feature flag du tout, le serveur peut pointer vers un flux d'intégration guidée pour la configuration de première fois. La création directe est fine ici quand l'utilisateur a demandé un flag spécifique ; mentionnez le flux d'intégration seulement si l'utilisateur semble nouveau à Datadog Feature Flags.
• Enregistrez l'ID du flag et les ID de ses deux variantes.

L'énumération des environnements donne les disponibles (généralement Production, Staging, Development). Notez lesquels sont production : certaines actions sur production ne sont pas disponibles via le serveur et doivent être faites dans l'interface Datadog.

Phase 2 — Câbler l'application

L'application doit faire trois choses pour chaque subject : évaluer le flag, exécuter le comportement correspondant, et rapporter le score et les spans sous le même identifiant de subject.

Choisissez l'identifiant du subject. Il doit être stable à travers toute l'interaction mesurée.

• Application avec utilisateurs connectés : un ID utilisateur stable.
• Pas d'utilisateurs, mais sessions : l'ID de session.
• Flux de travail autonomes : générez un UUID au démarrage d'une exécution et réutilisez-le pour toute l'exécution.

Utilisez la même valeur en trois endroits : la targetingKey du contexte d'évaluation du feature flag, la tag subject_identifier sur le score d'évaluation (la clé de jointure que le guide des expériences en ligne Datadog requiert), et la tag subject_identifier sur le span racine de chaque trace, c'est ce que les métriques de coût et tokens lisent. Si ces éléments diffèrent, Datadog ne peut pas joindre l'exposition au résultat et l'expérience affiche des données de métrique manquantes.

Évaluez le flag. Suivez le SDK Feature Flags pour le langage de l'application. Pour Python, cela signifie un ddtrace récent plus le SDK OpenFeature, enregistrant le fournisseur Datadog une seule fois, et évaluant un flag booléen avec targeting_key défini sur l'identifiant du subject. Le SDK a besoin de la clé API Datadog, du site et du DD_ENV définis. Mettez par défaut l'évaluation à false (control) et capturez les défaillances pour qu'une panne de flag dégradée se fasse en control au lieu de casser l'application.

Les conseils de gestion des feature flags peuvent pointer une ressource d'intégration React indépendamment du langage de l'application. Traitez cela comme des conseils d'outils génériques, pas comme une instruction pour ajouter du code React. Suivez le SDK pour le langage réel de l'application et préférez un modèle de fournisseur/évaluation de travail existant dans le repository.

Choisissez où la variante est appliquée. Si le comportement est cuit dans un état qui persiste (par exemple un prompt système stocké dans un objet de conversation), évaluez le flag une seule fois quand cet état est créé, pas à chaque appel, pour qu'un subject ne puisse pas changer de variantes au milieu de l'interaction. Dérivez le treatment du control dans le code où possible pour que les deux ne puissent pas diverger.

Rapportez le score. Soumettez l'évaluation du score avec le SDK Agent Observability et ajoutez subject_identifier à ses tags. Seules les évaluations avec un type de métrique score numérique peuvent être des métriques d'expérience ; les types booléen, catégorique et autres ne peuvent pas.

Taggez les spans et les évaluations. Ajoutez la tag subject_identifier (par exemple subject_identifier:73b2efe1-03e3-40c1-ab6a-bd2a6cfbc865) aux spans Agent Observability et aux scores d'évaluation dans le code de l'application. Datadog convertit la tag en champ @usr.id de l'événement lors de l'ingestion, et c'est ce champ que l'expérience utilise pour se joindre à l'exposition au flag. Définissez la tag, pas @usr.id : le SDK ne définit pas ce champ directement, et la conversion se produit dans le backend de Datadog.

Les métriques de coût et de tokens lisent le rollup de chaque trace racine terminée, donc la tag doit être sur le span racine de la trace : le span de workflow ou d'agent le plus extérieur. Annotez ce span via l'appel d'annotation de span du SDK. Pour un évaluateur géré à portée de span, ajoutez aussi la même tag à chaque span que cet évaluateur score car son résultat dérive le subject des tags du span évalué lui-même. Un évaluateur géré à portée de trace peut propager le subject du span racine à ses résultats. Vérifiez la portée de l'évaluateur avant de réutiliser sa métrique. Tagguer les spans enfants évalués ne double pas le comptage du coût ou des tokens car ces métriques mesurent toujours seulement les traces racines.

Le code doit être déployé pour que l'expérience collecte quoi que ce soit. Dites clairement à l'utilisateur que le flag, l'allocation et l'expérience peuvent exister avant le déploiement mais ne rapportent rien jusqu'à ce que l'application évalue le flag dans l'environnement lié, et que le DD_ENV de l'application doit correspondre à cet environnement.

Phase 3 — Créer l'expérience et lier le flag

1. Créez une expérience brouillon avec un nom clair et l'hypothèse. La métrique primaire peut être attachée après, il est donc fine de créer le brouillon avant que les métriques existent.
2. Liez le flag de Phase 1 à l'expérience.
3. Relisez l'expérience. Un brouillon peut rapporter un ensemble de configuration incomplet jusqu'à ce qu'il soit démarré ; ce seul fait n'est pas une erreur. L'étape de démarrage rapporte des bloquants concrets s'il y en a.
4. Résolvez le type de subject du brouillon et vérifiez que son attribut Product Analytics est @usr.id, correspondant au champ produit à partir de la tag subject_identifier de Phase 2. Le démarrage nécessite un type de subject, mais n'acceptez pas une valeur par défaut sélectionnée arbitrairement par le serveur : les types de subject mappés à un autre champ ne peuvent pas se joindre à ces résultats Agent Observability. Sélectionnez explicitement un type de subject compatible avec @usr.id avant de procéder. Si les capacités disponibles ne peuvent pas inspecter ou configurer le mapping, dirigez l'utilisateur vers l'interface Datadog et arrêtez jusqu'à ce que cela soit confirmé.

Une alternative à la création du flag en premier est une seule opération qui crée le flag avec une allocation liée à l'expérience (l'outil create-experiment-feature-flag). Elle a besoin que l'expérience et l'environnement existent au préalable. Le chemin étape par étape ci-dessus garde chaque écrit petit et facile à relire, c'est pourquoi cette compétence l'utilise.

Rapportez le nom et l'ID de l'expérience. Construisez son URL Product Analytics directe en tant que https://<app-host>/product-analytics/experiments/<experiment-id>, en utilisant l'ID retourné par le serveur et l'hôte applicatif pour le site Datadog de l'organisation. Pour US1 utilisez app.datadoghq.com ; pour EU utilisez app.datadoghq.eu ; les sites régionaux comme us5.datadoghq.com utilisent cet hôte directement ; et datad0g.com utilise dd.datad0g.com. Incluez ce lien dans la remise finale après avoir terminé les instructions de configuration, que l'expérience reste un brouillon ou a été démarrée.

Phase 4 — Créer et attacher les métriques

Réutilisez avant de créer

Énumérez d'abord les métriques d'expérience existantes. Si une métrique mesure déjà le score de l'utilisateur pour cette ML app, réutilisez-la. Si une métrique existante est construite sur les données Agent Observability, lisez sa définition stockée et copiez ses noms de colonnes au lieu de les deviner. La même chose s'applique aux métriques de coût et de tokens.

Métrique primaire : l'évaluation du score

La métrique primaire est le score approuvé en Phase 0. Si l'utilisateur n'en a nommé aucun, énumérez les évaluations qui existent pour la ML app et recommandez le score numérique le plus pertinent dans la proposition de configuration unique. Ne faites pas pause ici pour un autre choix sauf si la relecture contredit la définition approuvée.

• Source : Métriques d'évaluation Agent Observability, filtrées sur la ML app et le libellé d'évaluation.
• Agrégation : moyenne de la valeur du score.
• Changement souhaité : la direction qui compte comme une amélioration, l'une de METRIC_INCREASES ou METRIC_DECREASES. Ce champ est requis, et une valeur incorrecte inverse la façon dont chaque résultat se lit, donc incluez-le explicitement dans la proposition de Phase 0.

Exemple de définition (les colonnes sont les champs d'événement d'évaluation standard : libellé, valeur de score et ML app) :

data source:        DATADOG
source type/subtype: LLMOBS / LLMOBS_EVAL_METRICS
aggregation:        average of @score_value
source filter:      @ml_app = <ml_app> AND @label = <evaluation label>
desired change:     METRIC_INCREASES (for a score where higher is better)

Métriques secondaires : tokens et coût

Ajoutez deux métriques secondaires pour que l'utilisateur puisse voir ce que le changement coûte. Les deux mesurent les traces racines LLM Observability terminées et sont moyennées par trace :

• Tokens de trace moyens : moyenne de @trace.total_tokens. Changement souhaité : METRIC_DECREASES.
• Coût de trace moyen : moyenne de @trace.estimated_total_cost. Changement souhaité : METRIC_DECREASES.

Utilisez la source de span Agent Observability (LLMOBS / LLMOBS_SPANS) avec l'opération average et le type de colonne int. Filtrez sur @ml_app = <ml_app> via les filtres d'événement ordinaires pour que les traces d'autres applications utilisées par le même subject ne puissent pas entrer dans le résultat. N'ajoutez pas de filtres pour l'achèvement de trace ou l'état du span racine : la plateforme applique elle-même ces règles d'éligibilité et une définition de métrique ne peut pas les surcharger. Ne pas sommer tous les spans, ce qui compte les spans enfants et les traces inachevées. Si l'organisation a déjà une métrique de span LLM Observability, copiez ses noms de colonnes et son type de sa définition stockée au lieu de vous fier aux noms ici, mais réutilisez-la seulement si son filtre stocké la scops déjà sur ce @ml_app. Les rollups de trace sont censés être des entiers. Si la métrique n'affiche pas de données, vérifiez d'abord le type de colonne, car le type stocké doit correspondre à ce que la plateforme expose.

Attachez les métriques

Attachez une à la fois, jamais en parallèle :

1. Attachez la métrique de score comme primaire.
2. Attachez les tokens comme métrique secondaire.
3. Attachez le coût comme métrique secondaire.

Relisez l'expérience et confirmez que la métrique primaire est définie. Certaines lectures d'expérience omettent les métriques secondaires ; dans ce cas, utilisez la réponse d'attachement réussie avec l'ensemble complet de métriques comme confirmation et dites clairement que la lecture générale de l'expérience ne les expose pas.

Phase 5 — Environnements et répartition du trafic

Une expérience est liée à exactement un environnement via une allocation.

1. Activez le flag dans le(s) environnement(s) que l'utilisateur a demandé. L'activation d'un flag peut être refusée pour un environnement de production via le serveur, qui dirige l'utilisateur vers l'interface. Si cela se produit, donnez à l'utilisateur le lien d'interface du flag et demandez-lui de l'y activer. Changer les allocations (étape 3) est une opération séparée et peut toujours être disponible pour la production.

2. Énumérez l'ensemble complet d'allocation du flag dans l'environnement cible et dans tout autre environnement déjà lié à cette expérience. Le réglage des allocations est un remplacement complet, conservez donc chaque allocation non liée et tous ses paramètres dans chaque demande de remplacement.

3. Ajoutez ou mettez à jour exactement une allocation feature-gate liée à l'expérience, tout en conservant les allocations non liées dans la liste de remplacement complète. Ses poids de variante sont des pourcentages totalisant exactement 100 (par exemple 50 control et 50 treatment). Incluez un calendrier d'exposition dans le même appel, sinon l'expérience ne démarre pas (voir le prochain paragraphe). Le réglage de l'allocation sans calendrier réussit, et l'étape de démarrage le rejette plus tard comme non prêt. L'allocation a besoin d'un calendrier d'exposition avec tous ces champs, sinon l'étape de démarrage le rapporte comme non prêt. Ceci est vrai bien que le schéma d'allocation générique dise d'omettre le calendrier pour les gates de fonctionnalité : ce conseil s'adresse aux gates qui ne sont pas liés à une expérience.

   • une stratégie de rollout d'intervalles uniformes, avec un selection_interval_ms (requis par cette stratégie) ;
   • un démarrage de none, pour que le calendrier ne commence pas par lui-même et que le démarrage de l'expérience elle-même contrôle le timing ;
   • une seule étape de rollout avec exposure_ratio 1,0 (un ratio 0-1, pas 100), is_pause_record false, et grouped_step_index 0, pour que les pourcentages dans les poids de variante s'appliquent à tout le trafic ;
   • la control_variant_key du calendrier, nommant la variante control (l'allocation peut être enregistrée sans elle, mais l'étape de démarrage rapporte alors des poids d'allocation invalides).

   N'utilisez pas une rampe de rollout partielle ici. La répartition 50/50 est déjà exprimée par les poids.

4. Si l'expérience est déjà liée à une allocation dans un autre environnement, lisez l'ensemble complet d'allocation de cet environnement et supprimez seulement l'allocation liée à cette expérience, en conservant chaque autre allocation et ses paramètres, avant de créer la nouvelle allocation. Ne remplacez pas un environnement par une liste vide sauf si la configuration approuvée supprime explicitement toutes ses allocations. Si une clé d'allocation existe déjà, identifiez l'allocation conflictuelle : réutilisez-la seulement quand elle appartient à la configuration approuvée ; sinon, choisissez une nouvelle clé unique. Demandez à nouveau si cette récupération diffère matériellement de la proposition approuvée.

5. Relisez les allocations et confirmez l'environnement, les poids et le lien d'expérience.

Les changements d'allocation de production prennent effet immédiatement. Si l'environnement nécessite une approbation pour les changements de flag, le changement peut attendre cette approbation au lieu d'être appliqué. La proposition approuvée de Phase 0 est l'environnement et la confirmation de production ; ne demandez à nouveau que si l'ensemble d'allocation existant diffère matériellement de ce que cette proposition a dit serait remplacé.

Phase 6 — Démarrer l'expérience

Démarrez seulement quand l'utilisateur le demande explicitement. Immédiatement avant de démarrer, vérifiez indépendamment plutôt que de vous fier seulement à la vérification de disponibilité de l'opération de démarrage :

• Le flag est activé dans l'environnement lié.
• L'allocation 50/50 (ou choisie) est en place et liée.
• La métrique primaire est attachée.
• La modification de l'application est déployée ou l'utilisateur accepte explicitement de démarrer l'horloge avant le déploiement.

N'invoquez pas le démarrage tant que l'environnement lié est connu comme désactivé. La vérification de disponibilité du démarrage peut valider la structure d'allocation sans forcer l'activation du flag ou le déploiement, donc un démarrage réussi ne prouve pas que le trafic peut circuler.

Puis démarrez l'expérience (l'outil start-experiment). Il exécute sa propre vérification de disponibilité et retourne les bloquants structurels qu'il peut détecter, chacun avec une action. Appliquez toutes les actions, puis relancez une seule fois. Attendez-vous à avoir besoin de plus d'une passe : il rapporte les bloquants qu'il peut actuellement détecter, et fixer un peut révéler le suivant (par exemple un calendrier d'exposition manquant en premier, puis une variante control invalide sur ce calendrier). Réparer une allocation remplace l'ensemble d'allocation du flag, donc lisez d'abord les allocations ; ne demandez à nouveau que si le remplacement requis diffère de celui approuvé en Phase 0. S'il retourne une erreur de permissions, rapportez que le compte manque de permission pour démarrer les expériences, arrêtez, et proposez le flux d'aperçu-et-démarrage de l'interface. Ne bouclez pas sur les relances.

Après le démarrage, relisez l'expérience et rapportez son statut.

Phase 7 — Vérifier une fois que le trafic circule

Une fois l'application déployée et recevant du trafic :

• Exécutez les diagnostiques d'expérience. Ils vérifient l'équilibre d'exposition et le flag des métriques sans données, des métriques non fiables et l'absence de rapport de ratio d'échantillon.
• Si une métrique n'a pas de données, vérifiez dans cet ordre : le flag est évalué pour le subject (la recherche de localisation de code de l'expérience montre où le flag est utilisé dans la source) ; l'évaluation a un score numérique ; le subject_identifier correspond exactement à la targetingKey ; le span racine porte la tag ; les traces sont complètes ; les noms et types de colonnes de la métrique sont corrects.
• Fixez une définition de métrique incorrecte en mettant à jour la métrique plutôt que de créer un doublon.

Pour lire les résultats une fois qu'assez de données sont arrivées, utilisez agent-observability-experiment-analyzer ou les outils d'expérimentation Datadog disponibles dans le serveur MCP actif.

Checklist des pièges

• Décalage d'identifiant de subject entre le flag, l'évaluation et les spans.
• Tag de subject manquante du span racine, donc les métriques de coût et tokens ne peuvent pas se joindre aux expositions.
• Type de subject mappé à un attribut autre que @usr.id.
• Évaluation gérée à portée de span manquant la tag de subject sur le span qu'elle score.
• Métriques de coût ou tokens définies comme une somme sur tous les spans, ou sur des attributs de span autres que les rollups de trace.
• Métrique de coût ou tokens manquant son filtre @ml_app.
• Flag activé dans un environnement mais l'application s'exécutant dans un autre.
• Expérience liée à l'allocation du mauvais environnement (elle ne peut en lier qu'une).
• Remplacement d'allocation qui supprime les allocations non liées ou leurs calendriers d'exposition.
• Les poids d'allocation ne totalisent pas 100.
• Ensemble d'allocation sans calendrier d'exposition, ou avec un calendrier qui n'a pas control_variant_key, ce qui bloque l'étape de démarrage.
• L'évaluation est booléenne ou catégorique, pas un score.
• Métrique desired change définie dans le mauvais sens.
• Attachement de métriques en parallèle.
• Démarrage avant que l'utilisateur n'ait demandé, ou avant que le flag ne soit activé là où l'application s'exécute.