Créer une métrique LaunchDarkly

Vous utilisez une compétence qui vous guidera à travers la création d'une métrique LaunchDarkly. Pour les métriques personnalisées, faire circuler les événements vient en premier — avant la création de la métrique. Votre tâche consiste à déterminer le bon type de métrique, instrumenter l'événement s'il ne circule pas déjà (y compris la configuration du SDK et le câblage de l'environnement), vérifier les doublons, proposer une configuration de métrique, obtenir une confirmation explicite, puis créer et vérifier.

Conditions préalables

Cette compétence nécessite que le serveur MCP LaunchDarkly hébergé à distance soit configuré dans votre environnement.

Outils MCP requis :

• create-metric — créer la métrique
• get-metric — la vérifier après sa création
• get-environment — récupérer la clé SDK côté client lors de l'instrumentation

Outils MCP optionnels (améliorent le flux) :

• list-metrics — vérifier les métriques existantes avec la même clé d'événement et comprendre les conventions de nommage
• list-metric-events — découvrir quelles clés d'événement ont une activité récente avant de s'engager sur l'une d'elles (métriques personnalisées uniquement)

Deux « Projets » différents — Ne les confondez jamais

Les utilisateurs travaillent avec deux choses complètement distinctes qui s'appellent toutes les deux « projet ». Vous devez les garder distincts à tout moment :

Règles pour les résoudre à partir de l'entrée utilisateur :

• Si l'utilisateur dit « mon application à X » ou « mon code » ou « mon repo » → ils veulent dire la base de code locale. X est un chemin de dossier ou un nom de projet, pas une clé LaunchDarkly.
• Si l'utilisateur dit « l'ajouter à X » ou « dans LaunchDarkly » ou « mon projet LD » → ils veulent dire le projet LaunchDarkly. X est le projectKey pour les appels d'API.
• Un utilisateur peut nommer sa base de code locale checkout_proj tandis que son projet LaunchDarkly est anthony-agent-dev-5000. Ceux-ci sont sans rapport.
• Ne supposez jamais que le nom de la base de code locale est une clé de projet LaunchDarkly. Si vous ne savez pas lequel est lequel, posez directement : « Juste pour confirmer — quelle est votre clé de projet LaunchDarkly ? (C'est différent du nom de votre app locale — vous pouvez la trouver dans l'interface LD sous Account Settings > Projects.) »

Quand les deux sont nécessaires (par exemple pour une métrique personnalisée avec instrumentation), confirmez chacun explicitement avant de continuer.

Flux de travail

Étape 1 : Déterminer le type de métrique

LaunchDarkly a trois types de métriques. Choisissez le bon avant toute chose d'autre.

Règles de décision :

• L'utilisateur dit « suivre quand quelqu'un consulte une page / visite une URL » → pageview (préféré — aucune instrumentation requise)
• L'utilisateur dit « suivre quand quelqu'un clique sur un bouton / lien » → click
• L'utilisateur dit « suivre un événement personnalisé » ou fait référence à un appel track() → custom

Quand pageview ou click serait approprié, suggérez-le plutôt que custom — cela ne nécessite pas de modifications de code.

Étape 2 : Résoudre la source de données

Pour les métriques pageview et click :

• Demandez le ou les URL(s) à correspondre. Confirmez le kind de règle de correspondance d'URL :
  • substring — l'URL contient cette chaîne (plus courant)
  • exact — l'URL doit correspondre exactement
  • canonical — correspond à l'URL canonique
  • regex — motif regex complet
• Pour les métriques click, demandez aussi le sélecteur CSS (par exemple .checkout-btn, #submit).
• Ignorez list-metric-events — ces métriques n'utilisent pas de clés d'événement.
• Passez à l'étape 3.

Pour les métriques custom — vérifier les événements en premier, instrumenter si nécessaire :

Appelez list-metric-events immédiatement pour voir quelles clés d'événement circulent déjà :

list-metric-events(projectKey, environmentKey?)

Cas A — la clé d'événement est déjà dans la liste : Confirmez la clé avec l'utilisateur et passez à l'étape 3. Aucune instrumentation nécessaire.

Cas B — la clé d'événement N'est PAS dans la liste : La métrique ne peut rien mesurer sans événements. Instrumentez l'événement maintenant avant de créer la métrique. Ne vous contentez pas d'avertir et de demander si vous devez continuer — considérez l'instrumentation comme l'action suivante par défaut.

Suivez le sous-flux d'instrumentation ci-dessous, puis revérifiez list-metric-events pour confirmer que les événements circulent avant de passer à l'étape 3. Ignorez l'instrumentation uniquement si l'utilisateur dit explicitement qu'il veut créer la métrique en premier et câbler l'événement plus tard — dans ce cas, rappelez-lui à la fin que la métrique ne produira aucune donnée jusqu'à ce que l'événement soit suivi.

Étape 2b : Instrumenter l'événement (quand les événements ne circulent pas)

Ce sous-flux introduit un appel track() dans la base de code et connecte l'app au bon environnement LaunchDarkly. Complétez toutes les étapes avant de revenir au flux principal.

1. Trouver le bon endroit dans la base de code. Localisez la fonction ou le gestionnaire où l'événement se produit naturellement (par exemple un gestionnaire de soumission de paiement, un rappel de soumission de formulaire). Lisez les fichiers source pertinents pour comprendre la structure existante avant d'apporter des modifications.

2. Déterminer la clé d'événement. Si l'utilisateur n'en a pas spécifié une, proposez une clé descriptive en kebab-case qui correspond à ce que le code fait (par exemple checkout-completed, signup-submitted). Confirmez avec l'utilisateur avant de l'utiliser.

3. Récupérer la clé SDK côté client. Demandez à l'utilisateur quel environnement il veut connecter (par exemple « test », « production », « staging ») — juste le nom de l'environnement. Puis appelez :

get-environment(projectKey, environmentKey)

Utilisez le clientSideId de la réponse.

4. Écrire le fichier d'environnement. Vérifiez si un fichier .env (ou équivalent — .env.local, .env.development, etc.) existe déjà.

• Si le fichier n'existe pas, créez-le.
• Si le fichier existe et contient déjà la clé (par exemple VITE_LD_CLIENT_SIDE_ID), comparez la valeur stockée au clientSideId retourné par get-environment. S'ils diffèrent, soulevez la discordance à l'utilisateur :

  « Votre .env a déjà VITE_LD_CLIENT_SIDE_ID=<old>, mais get-environment a retourné <new> pour l'environnement <env>. Dois-je le mettre à jour ? » Ne conservez pas silencieusement l'ancienne valeur — une clé côté client non correspondante signifie que les événements seront envoyés au mauvais projet ou environnement.

• Si le fichier existe mais la clé est absente, ajoutez-la sans toucher à d'autres valeurs.

Utilisez le nom de variable approprié à l'outil de build du projet (par exemple VITE_LD_CLIENT_SIDE_ID pour Vite, REACT_APP_LD_CLIENT_SIDE_ID pour CRA, NEXT_PUBLIC_LD_CLIENT_SIDE_ID pour Next.js).

4b. Définir l'URL de base du SDK si l'utilisateur n'est pas sur app.launchdarkly.com. Le SDK utilise par défaut app.launchdarkly.com pour tout le trafic. Si l'utilisateur est sur un déploiement LaunchDarkly différent (par exemple un environnement de staging interne comme catamorphic, ou une instance dédiée), les événements et les évaluations de drapeaux iront silencieusement vers le mauvais hôte.

Détectez cela en inspectant les _links ou les URL d'interface utilisateur dans les réponses de l'API MCP — s'ils pointent vers un hôte autre que app.launchdarkly.com, vous êtes sur un déploiement non-production. En cas de doute, demandez :

« Vous connectez-vous à app.launchdarkly.com ou à une instance LaunchDarkly différente ? (par exemple un environnement interne ou de staging) »

S'ils sont sur un hôte non-standard, ajoutez trois variables supplémentaires au fichier .env :

VITE_LD_BASE_URL=https://<their-host>
VITE_LD_STREAM_URL=https://clientstream.<their-host-domain>
VITE_LD_EVENTS_URL=https://events.<their-host-domain>

Et passez-les aux options SDK au moment de l'initialisation :

asyncWithLDProvider({
  clientSideID,
  context: { kind: 'user', anonymous: true },
  options: {
    baseUrl: import.meta.env.VITE_LD_BASE_URL,
    streamUrl: import.meta.env.VITE_LD_STREAM_URL,
    eventsUrl: import.meta.env.VITE_LD_EVENTS_URL,
  },
})

Omettez entièrement le bloc options s'ils sont sur app.launchdarkly.com — les valeurs par défaut sont correctes et aucune configuration supplémentaire n'est nécessaire.

5. Installer et initialiser le SDK s'il n'est pas déjà présent. Vérifiez package.json (ou le fichier de dépendances équivalent) pour un SDK LD existant. Si aucun n'est trouvé, installez le bon pour la pile du projet :

• React → launchdarkly-react-client-sdk
• Browser JS → launchdarkly-js-client-sdk
• Node.js server → @launchdarkly/node-server-sdk

Initialisez le SDK au point d'entrée de l'app (par exemple enrobez la racine React avec LDProvider, configurez LDClient.init() dans l'entrée du serveur, etc.). Passez l'ID côté client du fichier env. Utilisez un utilisateur/contexte anonyme par défaut sauf si l'app gère déjà le contexte utilisateur.

6. Ajouter l'appel track(). À l'emplacement identifié à l'étape 1, ajoutez l'appel immédiatement avant ou après la fin de l'action :

• Métrique de compte / d'occurrence : ldClient.track('event-key')
• Métrique de valeur : ldClient.track('event-key', null, numericValue)

Utilisez le chaînage optionnel (ldClient?.track(...)) dans le code côté client où le client peut ne pas encore être initialisé.

7. Vérifier que les événements circulent. Après les modifications d'instrumentation, rappelez à l'utilisateur d'exécuter l'app et de déclencher l'événement au moins une fois. Puis appelez list-metric-events à nouveau pour confirmer que la clé apparaît avant de passer à la création de métrique.

Étape 3 : Vérifier les métriques existantes

Avant de créer quoi que ce soit, utilisez list-metrics pour analyser le projet :

1. Vérifiez les doublons. Recherchez les métriques avec la même clé d'événement, motif d'URL ou noms similaires. Évitez de créer une deuxième métrique qui mesure la même chose — au lieu de cela, signalez la métrique existante et demandez à l'utilisateur s'il veut la réutiliser.
2. Apprenez la convention de nommage. Les clés de métrique sont-elles en kebab-case ou snake_case ? Y a-t-il des motifs de tags communs ? Correspondez à ce qui existe déjà.
3. Comprenez la taxonomie des tags. Des tags comme team:growth, area:checkout ou type:guardrail peuvent déjà exister. Suggérez des tags pertinents basés sur ce que l'utilisateur décrit.

Étape 4 : Proposer la configuration de la métrique

Avant d'appeler une API, présentez une configuration proposée en langage naturel pour que l'utilisateur la confirme ou l'édite.

Déterminer le type de mesure. Le bon choix dépend de ce que l'utilisateur essaie d'apprendre et de la façon dont il utilisera la métrique — dans une expérience, un déploiement sécurisé ou une politique de version. Ne supposez pas. Quand l'événement est quelque chose qu'un utilisateur peut faire à plusieurs reprises (clic, ajout au panier, affichage de page, etc.), posez toujours la question avant de proposer :

« Essayez-vous de mesurer combien de fois cet événement se produit au total (count), ou quel pourcentage d'utilisateurs l'a déclenché au moins une fois (occurrence) ? »

Liez la question à leur contexte :

• Expériences — l'occurrence est courante pour les objectifs de conversion (le traitement a-t-il amené plus d'utilisateurs à faire X ?) ; le count convient mieux pour les objectifs d'engagement ou de volume (le traitement a-t-il amené plus d'actions totales ?)
• Déploiements sécurisés / politiques de version — l'occurrence est typique pour les garde-fous de taux d'erreur (quelle fraction d'utilisateurs frappe une erreur ?) ; le count convient aux garde-fous de volume absolu (événements d'erreur totaux)
• Si l'utilisateur dit explicitement « pourcentage d'utilisateurs » ou « taux de conversion » → occurrence
• Si l'utilisateur dit explicitement « nombre de fois » ou « événements totaux » → count

Ignorez la question seulement si l'intention est sans ambiguïté d'après le contexte (par exemple « latence API » → value, « taux d'erreur » → count, « conversion d'inscription » → occurrence).

Déterminer les critères de succès :

• Plus c'est mieux → HigherThanBaseline (taux de conversion, revenu, engagement)
• Moins c'est mieux → LowerThanBaseline (latence, taux d'erreur, taux de rebond)

Utiliser les modèles communs comme valeurs par défaut quand l'intention de l'utilisateur est claire :

Présentez la configuration proposée avant de créer — ne déclenchez pas silencieusement l'API :

Configuration proposée :
  Clé :              checkout-page-viewed
  Nom :              Checkout Page Viewed
  Type :             pageview (se déclenche automatiquement lors de la visite d'une URL — aucune modification de code nécessaire)
  URLs :             correspondance de substring sur « /checkout »
  Type de mesure :   occurrence (chaque utilisateur a-t-il visité la page ?)
  Critères de succès : HigherThanBaseline

Procédez-vous, ou voulez-vous changer quelque chose ?

ARRÊTEZ-VOUS ICI. N'appelez aucune API. N'allez pas à l'étape 5. Attendez que l'utilisateur confirme explicitement. L'utilisateur doit répondre avec une approbation (par exemple « oui », « ça me plaît », « procédez ») avant d'appeler create-metric. S'il y a une ambiguïté dans la configuration proposée — comme un choix entre sum vs average, ou le nom de la clé d'événement — posez cette question dans le cadre de la proposition et attendez la réponse avant de continuer.

Étape 5 : Créer la métrique

Procédez uniquement une fois que l'utilisateur a explicitement confirmé la configuration proposée à l'étape 4. Si vous n'avez pas encore reçu une confirmation, retournez et attendez.

Une fois que l'utilisateur confirme, appelez create-metric. L'outil gère la traduction de measureType vers les champs API sous-jacents — vous n'avez jamais besoin de passer isNumeric ou unitAggregationType directement.

create-metric(
  projectKey,
  key,
  name,
  kind,              // "custom" | "pageview" | "click"
  eventKey?,         // uniquement pour kind="custom"
  urls?,             // uniquement pour kind="pageview" ou "click": [{ kind, url }]
  selector?,         // uniquement pour kind="click": chaîne de sélecteur CSS
  measureType,       // "count" | "occurrence" | "value"
  successCriteria,   // "HigherThanBaseline" | "LowerThanBaseline"
  valueAggregation?, // uniquement pour measureType="value": "average" (par défaut) ou "sum"
  unit?,             // étiquette d'affichage : "ms", "USD", etc.
  description?,
  tags?
)

Étape 6 : Vérifier

Utilisez get-metric pour confirmer que la métrique a été créée avec la bonne configuration :

1. La clé et le nom correspondent à ce qui a été demandé.
2. Le kind est correct — custom, pageview ou click.
3. Le measureType est correct — vérifiez en relisant le champ measureType, pas seulement isNumeric.
4. eventKey / urls / selector sont définis sur les valeurs prévues.
5. successCriteria est correct.

Présentez un résumé à l'utilisateur :

✓ Métrique créée : checkout-page-viewed
  Type :     pageview (suivi automatique lors de la visite d'URL)
  URLs :     substring « /checkout »
  Mesure :   occurrence (taux de conversion)
  Objectif :  Plus c'est mieux

Afficher dans LaunchDarkly : {_links.ui de la réponse create-metric}

L'outil create-metric retourne un champ _links.ui avec la bonne URL pour l'environnement utilisé. Utilisez toujours cette valeur — ne hard-codez jamais app.launchdarkly.com.

Référence du type de mesure

L'outil create-metric traduit measureType vers les champs API LD en interne. Vous n'avez jamais besoin de définir isNumeric ou unitAggregationType directement.

Pour les métriques value, valueAggregation utilise par défaut "average". Passez valueAggregation: "sum" pour le revenu ou les totaux cumulés.

Contexte important

• Préférez pageview et click à custom quand c'est possible. Ils ne nécessitent aucune instrumentation SDK et fonctionnent automatiquement dans les navigateurs.
• Les clés d'événement sont sensibles à la casse. checkout-completed et Checkout-Completed sont des événements différents. Faites correspondre la clé exactement comme elle apparaît dans vos appels track().
• Les métriques personnalisées sans événements ne produisent aucune donnée. Une métrique personnalisée n'est utile qu'une fois que sa clé d'événement est activement suivie en production (ou dans l'environnement approprié). Si vous avez créé la métrique avant d'instrumenter l'événement, rappelez-le à l'utilisateur.
• Les clés de métrique sont immuables. Une fois créée, la clé d'une métrique ne peut pas être modifiée. Choisissez avec soin.
• Les métriques sont délimitées par le projet. Une métrique créée dans un projet n'est pas visible dans un autre. Assurez-vous que projectKey correspond à où l'expérience ou le drapeau se trouve.
• Une métrique principale par expérience. Lors de l'attachement de cette métrique à une expérience, clarifiez si c'est la métrique principale (celle qui détermine le succès ou l'échec) ou une métrique secondaire (un garde-fou ou un signal d'appui). Voir la documentation LaunchDarkly pour la configuration d'expériences.