Mettre à jour le SDK Datadog Browser à la v6

Guide de migration systématique de v5 à v6. Suivez les étapes 1-6 dans l'ordre. Chaque étape inclut un motif de recherche pour trouver le code affecté.

Étape 1 : Mettre à jour la version du SDK

Configuration CDN — mettez à jour les URLs src du script :

Remplacez us1 par votre site : eu1, us3, us5, ap1, ap2. Pour US1-FED, le motif est plat sans préfixe de site : datadog-rum-v6.js, datadog-logs-v6.js, datadog-rum-slim-v6.js.

Recherche : grep -r "datadoghq-browser-agent.com.*v5" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"

Configuration npm — mettez à jour les dépendances package.json :

"@datadog/browser-rum": "^6.0.0"
"@datadog/browser-logs": "^6.0.0"
"@datadog/browser-rum-slim": "^6.0.0"

Ensuite, exécutez votre gestionnaire de paquets (npm install, yarn install, etc.) et rebuildez.

Mettez aussi à jour les intégrations framework vers v6 si utilisées : @datadog/browser-rum-react.

Recherche : grep -r "@datadog/browser-" --include="package.json" .

Étape 2 : Supprimer les options dépréciées

Supprimées du Core (affecte RUM et Logs)

Supprimées de Logs

Recherche : grep -rn 'useCrossSiteSessionCookie\|sendLogsAfterSessionExpiration' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Étape 3 : Mettre à jour les valeurs par défaut modifiées

v6 change plusieurs comportements par défaut. Vérifiez chacun et ajustez si nécessaire :

3a. trackUserInteractions, trackResources, et trackLongTasks valent true par défaut

En v5, ils valaient false par défaut. En v6, ils sont activés dès le départ. Cela n'impacte pas la facturation.

Pour préserver le comportement v5, désactivez explicitement uniquement les options qui n'étaient pas déjà activées en v5. Si une option valait déjà true en v5, laissez-la inchangée :

DD_RUM.init({
  trackUserInteractions: false, // seulement si pas déjà true en v5
  trackResources: false, // seulement si pas déjà true en v5
  trackLongTasks: false, // seulement si pas déjà true en v5
})

3b. traceContextInjection vaut "sampled" par défaut

En v5, le contexte de trace était injecté pour toutes les requêtes. En v6, il n'est injecté que pour les traces échantillonnées. Si votre traceSampleRate est 100 % (la valeur par défaut), cela n'a aucun impact.

Pour préserver le comportement v5 :

DD_RUM.init({
  traceContextInjection: 'all',
})

3c. En-tête tracestate ajouté avec le propagateur tracecontext

Le propagateur tracecontext envoie maintenant un en-tête tracestate supplémentaire. Votre serveur doit l'accepter. Ajoutez-le à vos Access-Control-Allow-Headers existants — ne remplacez pas la liste complète :

# Ajoutez tracestate aux côtés de vos en-têtes existants
Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate

3d. Le paramètre site est fortement typé

L'option site a un type TypeScript plus strict. Si vous passez une valeur non-standard, vous obtenez une erreur de type. Utilisez proxy pour les URLs d'intake non-standard à la place.

Recherche : grep -rn 'trackUserInteractions\|trackResources\|trackLongTasks\|traceContextInjection\|tracestate\|allowedTracingUrls\|propagatorTypes' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Cherchez aussi tous les appels d'init RUM pour attraper les projets qui omettent ces options et s'appuyaient sur les valeurs par défaut v5 false : grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte". Pour chaque appel init, vérifiez si trackUserInteractions, trackResources, et trackLongTasks sont explicitement définis — s'ils sont omis, ils valent maintenant true en v6 par défaut.

Étape 4 : Gérer le chargement lazy de Session Replay

Session Replay est maintenant chargé en lazy-loading via des imports dynamiques. Le module se charge uniquement pour les sessions échantillonnées pour la replay, réduisant la taille du bundle pour les autres.

Configuration npm

Assurez-vous que votre bundler supporte les imports dynamiques (code splitting). La plupart des bundlers modernes le font :

• Webpack: Documentation code splitting
• Esbuild: Option splitting
• Rollup: Documentation code splitting
• Parcel: Documentation code splitting

Configuration CDN

Aucune modification de code nécessaire. Le SDK charge dynamiquement un chunk supplémentaire lors de l'enregistrement (ex. datadogRecorder-<hash>-datadog-rum.js). Mettez à jour les règles CSP script-src si nécessaire pour autoriser le chunk.

Étape 5 : Passer en revue les changements comportementaux (aucun code requis, mais peut nécessiter attention)

Étape 6 : Mettre à jour l'infrastructure

• Support du navigateur : Baseline ES2018. IE11 n'est plus supporté.
• CORS : Ajoutez tracestate à vos Access-Control-Allow-Headers existants si vous utilisez le propagateur tracecontext (ne remplacez pas la liste complète) : Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate
• CSP : Autorisez le chunk Session Replay chargé dynamiquement (ex. datadogRecorder-*-datadog-rum.js) dans les règles script-src.
• Configuration du bundler : Assurez-vous que votre bundler supporte les imports dynamiques pour le lazy-loading de Session Replay.

Erreurs courantes

Liste de vérification de vérification

Après la mise à jour, confirmez :

• [ ] Le SDK se charge sans erreurs console
• [ ] Aucune référence aux options supprimées (useCrossSiteSessionCookie, sendLogsAfterSessionExpiration)
• [ ] Les enregistrements Session Replay fonctionnent (si utilisés)
• [ ] La traçabilité distribuée fonctionne (pas d'erreurs CORS de l'en-tête tracestate)
• [ ] La taille du bundle diminuée (polyfills IE11 supprimés)
• [ ] Les long tasks sont toujours collectés (maintenant en tant que Long Animation Frames sur les navigateurs supportés)
• [ ] Aucune erreur TypeScript du typage du paramètre site