Instrumentation RUM du navigateur Datadog

Instrumentez uniquement l'application navigateur dans le périmètre. N'ajoutez pas APM Datadog, tracing, LLM Observability, Logs, source-map upload, identification utilisateur, métadonnées Vercel, Shopify, Salesforce, ou produits Datadog non liés.

Utilisez l'inspection de fichiers, l'édition et les outils de commande normaux pour chaque étape, sauf création optionnelle d'application RUM. Utilisez uniquement CreateRumApplication pour cette opération, comme décrit dans references/common-credentials.md ; n'inventez jamais de noms d'outils Datadog.

Règles fondamentales

• Inspectez avant d'éditer. Basez chaque décision de framework, version, entrypoint, commande et configuration sur les fichiers du projet.
• Copiez les noms de paquets, chemins d'import, symboles exportés et clés d'options init exactement depuis les références applicables. Ne substituez pas d'alias de paquets et ne recréez pas les APIs SDK de mémoire.
• Publiez une courte checklist avant d'apporter des modifications et mettez-la à jour au fur et à mesure.
• Initialisez RUM exactement une fois et aussi tôt que possible dans le cycle de vie du navigateur. Ne mettez jamais init() dans un render de composant, hook de cycle de vie, gestionnaire de route ou callback répété.
• Préservez une configuration d'init valide existante. Ajoutez le câblage des plugins de framework manquants compatibles à cet init ; ne créez jamais un init concurrent.
• Guardrail de crédentials d'init existant : quand un init RUM valide existe déjà, traitez son applicationId, clientToken, site, service tags, sampling, privacy, tracking et toutes les autres options existantes comme immuables. Les crédentials fournis par la tâche sont pour un nouvel init uniquement ; ce ne sont pas un remplacement d'un init existant valide. Dans cette branche, ne réécrivez pas les lignes de crédentials en ajoutant le câblage des plugins.
• Arrêtez sans éditer quand les crédentials requis ne peuvent pas être résolus, site n'est pas valide, les prérequis du framework/plugin ne sont pas satisfaits, les permissions empêchent le travail, ou plusieurs appels init conflictuels ne peuvent pas être consolidés de façon sûre.
• Installez uniquement les paquets requis pour Browser RUM. Gardez @datadog/browser-rum et tout paquet d'intégration @datadog/browser-rum-* exactement sur la même version du SDK.
• Persistez les dépendances dans le manifest et lockfile utilisés par la vraie build. Ne vous fiez pas aux paquets qui existent par hasard dans node_modules.
• Préservez le comportement de l'application, la gestion d'erreurs personnalisée existante, les conventions de formatage et le code non lié.
• Appliquez les éditions avec l'outil d'édition de fichier disponible. Si une correspondance de texte attendue échoue, relisez le fichier et adaptez-vous à son contenu actuel au lieu de réessayer la même édition.
• N'écrivez pas les chemins de projet, détails du framework, crédentials, tokens client ou IDs d'application RUM dans la mémoire persistante.
• Exécutez une build de terminaison avant de signaler le succès. Ne réclamez jamais que la télémétrie a été reçue à moins qu'elle n'ait été réellement observée.

Phase 1 : analyser la cible

Localisez l'application navigateur

Identifiez la racine du projet qui produit du code navigateur. Dans un monorepo, inspectez la configuration de l'espace de travail, les scripts, les Dockerfiles et la configuration CI/déploiement pour trouver le manifest du frontend utilisé par la vraie build plutôt que d'éditer la racine du repository par supposition. Enregistrez ce chemin de manifest et son gestionnaire de paquets avant d'éditer. Si plusieurs applications navigateur indépendantes sont plausibles et l'utilisateur n'en a pas sélectionné une, demandez quelle application instrumenter.

Rejetez les applications non-navigateur comme les CLIs Ink et les projets sans cible de build HTML/navigateur.

Détectez le framework et la forme du runtime

Inspectez les dépendances et la disposition des sources dans cet ordre pour que les meta-frameworks l'emportent sur leur bibliothèque UI sous-jacente :

1. nuxt -> Nuxt
2. next -> Next.js ; distinguez App Router de Pages Router par la disposition des sources
3. @angular/core -> Angular ; distinguez le bootstrap autonome du NgModule
4. vue -> Vue
5. svelte ou @sveltejs/kit -> Svelte ou SvelteKit
6. react -> React
7. Entrypoint navigateur sans les précédents -> application navigateur générique/vanilla

Détectez aussi :

• Framework exact, React Router, TanStack Router, Vue Router et versions de Node.
• TypeScript quand un tsconfig.json ou une dépendance TypeScript est présente ; sinon préservez JavaScript.
• Gestionnaire de paquets du champ packageManager du manifest déployé d'abord, puis de son fichier adjacent : bun.lock ou bun.lockb, pnpm-lock.yaml, yarn.lock, ou package-lock.json. Utilisez npm uniquement quand aucun signal de projet plus fort n'existe, et ne mélangez jamais les gestionnaires.
• Bundler depuis la configuration et les dépendances : Vite, Webpack, Rollup, esbuild, Rspack, ou Create React App (react-scripts). Traitez le HTML non géré comme CDN uniquement quand aucun build de paquet/bundler ne le possède.
• Entrypoint navigateur depuis la configuration de build, cibles de script HTML, conventions de framework et le graphe d'import plutôt que le nom de fichier seul.
• La commande normale de build/typecheck de terminaison.
• Conventions de variables d'environnement publiques existantes.

Lisez references/rum-core.md, puis lisez exactement la référence du framework applicable :

Validez tous les prérequis dans la référence sélectionnée avant de provisionner les crédentials ou d'éditer. Ne mettez pas à jour un framework et ne basculez pas silencieusement vers RUM core-only quand un plugin de framework détecté n'est pas compatible.

Détectez l'instrumentation RUM existante

Cherchez dans les fichiers source, HTML et configuration en excluant les répertoires de dépendance, build, générés et couverture tels que node_modules, dist, build, .next, .nuxt et coverage.

Vérifiez :

• Les imports ou requires depuis @datadog/browser-rum, y compris les liaisons renommées et espace de noms.
• Les imports de tout paquet d'intégration @datadog/browser-rum-*.
• Les appels liés à datadogRum.init importé, y compris les alias et modules wrapper locaux.
• DD_RUM.init, window.DD_RUM.init, DD_RUM.onReady et les URLs du chargeur Datadog CDN.
• Les enregistrements de plugins existants, les wrappers/providers/composants de routeur et les hooks d'erreur du framework.

Traitez la simple présence du paquet comme insuffisante : une dépendance peut ne pas être utilisée.

• Aucun init : ajoutez-en un en utilisant la référence sélectionnée.
• Un init valide : conservez son emplacement et toutes les valeurs existantes. Ne résolvez pas et n'appliquez pas les crédentials de remplacement. Ajoutez uniquement le câblage plugin/routeur/erreur compatible manquant à celui-ci.
• Un init avec crédentials manquants ou invalides requis/site : arrêtez et signalez la configuration invalide ; ne superposez pas un autre init.
• Plusieurs appels init ou configurations npm/CDN mixtes : arrêtez et signalez chaque emplacement à moins qu'ils ne puissent être prouvés comme une seule configuration mutuellement exclusive. Ne devinez pas quelle configuration devrait l'emporter.
• Setup complet : ne faites aucun changement ; exécutez quand même la vérification applicable.

Phase 2 : instrumenter

Résolvez les crédentials via references/common-credentials.md uniquement après le succès de l'analyse. Si l'analyse a trouvé un init existant valide, réutilisez ses crédentials existants et ignorez complètement le remplacement de crédentials. Les crédentials de tâche fournis ne peuvent être utilisés que lors de la création d'un nouvel init. Ensuite :

1. Installez le SDK core et le(s) paquet(s) de framework compatible(s) avec le gestionnaire de paquets détecté, en utilisant le manifest du frontend déployé. Pour un init valide existant, installez uniquement un paquet d'intégration manquant ; ne remplacez jamais les paquets ou la configuration RUM déjà valides.
2. Appliquez la configuration canonique et la méthode d'installation depuis references/rum-core.md. Pour un init valide existant, appliquez uniquement les champs compatibles manquants à ce même objet ; ne copiez pas les crédentials ou placeholders d'option canonique sur les valeurs existantes.
3. Appliquez la référence du framework sélectionné, y compris le suivi des routeurs et l'intégration sûre d'erreurs du framework quand ces surfaces existent.
4. Mettez à jour le lockfile avec le même gestionnaire de paquets. Ne modifiez jamais manuellement un lockfile généré.
5. Détectez le formatage configuré depuis les scripts du manifest comme lint:fix, fix, ou format et depuis la configuration ESLint/Prettier. Exécutez le formateur ou la commande fix du projet uniquement pour les fichiers modifiés par ce travail.

N'ajoutez pas allowedTracingUrls ou aucune configuration de backend/CORS/tracing ; celles-ci appartiennent à un workflow d'onboarding APM.

Phase 3 : vérifier et signaler

Suivez references/common-verify-report.md. Avant de signaler le succès, inspectez le diff final par rapport au projet pré-édition. Quand un init valide existant a été trouvé, vérifiez que chaque valeur d'init pré-existante—y compris les deux crédentials—reste byte-for-byte inchangée et que les seuls changements de setup sont le câblage d'intégration manquant requis (plus tout changement de dépendance/lockfile strictement nécessaire). Si une valeur existante a changé, restaurez-la avant de signaler le succès. Ne signalez le succès que si les paquets requis sont persistés, le setup résultant contient exactement un init, et la build normale réussit.