Mettre à jour le Datadog Browser SDK vers v5

Guide de migration systématique de v4 à v5. Suivez les étapes 1 à 7 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 du script src :

Remplacez us1 par votre site : eu1, us3, us5, ap1. Pour US1-FED, le motif est plat sans préfixe de site : datadog-rum-v5.js, datadog-logs-v5.js, datadog-rum-slim-v5.js. Remarque : AP2 n'est pas disponible pour v5 — mettez à jour vers v6 en premier si vous avez besoin d'AP2.

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

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

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

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

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

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

Étape 2 : Remplacer les paramètres init dépréciés

Ces noms de paramètres v4 n'existent plus dans v5. Remplacez-les :

Recherche : grep -rn 'proxyUrl\|sampleRate\|allowedTracingOrigins\|tracingSampleRate\|trackInteractions\|premiumSampleRate\|replaySampleRate' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Remarque : sampleRate correspond largement. Cherchez spécifiquement les objets de config init — sessionSampleRate est le nom v5 pour le taux d'échantillonnage de session.

Étape 3 : Remplacer les API publiques dépréciées

Ces noms de méthode API v4 n'existent plus dans v5 :

APIs RUM

APIs Logs

Recherche : grep -rn 'removeUser\|addRumGlobalContext\|removeRumGlobalContext\|getRumGlobalContext\|setRumGlobalContext\|addLoggerGlobalContext\|removeLoggerGlobalContext\|getLoggerGlobalContext\|setLoggerGlobalContext\|\.addContext\|\.removeContext' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Étape 4 : Mettre à jour la configuration Session Replay

v5 change plusieurs valeurs par défaut et comportements Session Replay :

4a. defaultPrivacyLevel changé en "mask"

En v4, la valeur par défaut était mask-user-input. En v5, tout le contenu est masqué par défaut.

Pour préserver le comportement v4 (masquer uniquement l'entrée utilisateur) :

DD_RUM.init({
  defaultPrivacyLevel: 'mask-user-input',
})

4b. L'enregistrement démarre automatiquement

Les sessions échantillonnées pour Session Replay sont maintenant automatiquement enregistrées. Vous n'avez plus besoin d'appeler startSessionReplayRecording().

Pour préserver le comportement v4 (démarrage manuel de l'enregistrement) :

DD_RUM.init({
  startSessionReplayRecordingManually: true,
})

4c. sessionReplaySampleRate par défaut est maintenant 0

En v4, le taux d'échantillonnage de replay par défaut était 100. En v5, il est 0 — aucun replay sauf si vous le définissez explicitement.

Action : Assurez-vous que sessionReplaySampleRate est explicitement défini dans votre config init :

DD_RUM.init({
  sessionReplaySampleRate: 100, // ou le taux que vous désirez
})

4d. trackResources et trackLongTasks doivent être explicites

Lors de l'utilisation de sessionReplaySampleRate (au lieu de la supprimée replaySampleRate ou premiumSampleRate), les ressources et les tâches longues ne sont plus collectées par défaut. Activez-les explicitement — sauf si la config v4 les avait déjà définis à false intentionnellement :

DD_RUM.init({
  sessionReplaySampleRate: 100,
  trackResources: true, // omettez si v4 avait explicitement trackResources: false
  trackLongTasks: true, // omettez si v4 avait explicitement trackLongTasks: false
})

Recherche : grep -rn 'sessionReplaySampleRate\|startSessionReplayRecording\|defaultPrivacyLevel\|trackResources\|trackLongTasks' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Recherchez aussi tous les appels d'init RUM pour détecter les projets qui omettent ces options et se fient aux valeurs par défaut v4 : grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte". Pour chaque appel d'init, vérifiez que sessionReplaySampleRate, defaultPrivacyLevel et trackResources/trackLongTasks sont explicitement définis.

Étape 5 : Mettre à jour les APIs et comportements modifiés

5a. beforeSend doit retourner un booléen

Les fonctions de rappel beforeSend doivent retourner true pour conserver l'événement ou false pour l'ignorer. Si aucune valeur n'est retournée, l'événement est conservé. Cela résout les erreurs de compilation TypeScript.

beforeSend: (event, context) => {
  // retournez true pour conserver, false pour ignorer
  return true
}

5b. Contexte d'action beforeSend : context.event → context.events

Avec les signaux de frustration, un événement d'action peut être associé à plusieurs événements DOM. context.event est remplacé par context.events (array).

// v4
beforeSend: (event, context) => {
  if (event.type === 'action') {
    const domEvent = context.event
  }
}

// v5
beforeSend: (event, context) => {
  if (event.type === 'action') {
    const domEvents = context.events // array
  }
}

5c. L'entrée de performance beforeSend est maintenant un objet PerformanceEntry

Le performanceEntry dans le contexte beforeSend est maintenant l'objet PerformanceEntry brut, pas une représentation JSON. Le type PerformanceEntryRepresentation a été supprimé.

5d. startTime supprimé du contexte beforeSend XHR

La propriété context.startTime a été supprimée du contexte beforeSend de ressource XHR. Utilisez à la place performanceEntry.

5e. view.in_foreground_periods supprimé de beforeSend

Cet attribut est maintenant calculé par le backend. Supprimez tout code beforeSend qui accède à view.in_foreground_periods.

5f. Signaux de frustration collectés automatiquement

Définissez trackUserInteractions: true pour collecter toutes les interactions utilisateur, y compris les signaux de frustration. Le paramètre trackFrustrations n'est plus nécessaire.

5g. Les noms de méthode de ressource sont en majuscules

Le champ method de ressource est maintenant toujours en majuscules (par ex., GET, POST). Mettez à jour tout dashboard ou moniteur filtrant sur resource.method.

5h. Champ session.plan supprimé

Le champ session.plan (lite/premium) est supprimé dans v5 et non émis sur aucun type d'événement. Remplacez tout filtre de dashboard ou moniteur sur session.plan par les nouveaux champs de replay :

• @session.sampled_for_replay:true — la session a été échantillonnée pour Session Replay
• @session.has_replay:true — la session a un enregistrement de replay réel

Recherche : grep -rn 'beforeSend\|trackFrustrations\|PerformanceEntryRepresentation\|in_foreground_periods\|context\.event\b\|startTime' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Étape 6 : Gérer les événements fiables

v5 ne se fie qu'aux événements générés par l'utilisateur (fiables). Les événements générés par les scripts sont ignorés par défaut.

Si vous dépendez d'événements programmatiques (par ex., dispatchEvent), ajoutez l'attribut __ddIsTrusted :

// JavaScript
const click = new Event('click')
click.__ddIsTrusted = true
document.dispatchEvent(click)

// TypeScript
const click = new Event('click') as Event & { __ddIsTrusted?: boolean }
click.__ddIsTrusted = true
document.dispatchEvent(click)

Ou autorisez tous les événements non fiables globalement :

DD_RUM.init({
  allowUntrustedEvents: true,
})

Recherche : grep -rn 'dispatchEvent\|new Event\|new MouseEvent\|new KeyboardEvent\|\.click()' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"

Étape 7 : Mettre à jour l'infrastructure

Les domaines connect-src CSP ont changé

v5 envoie les données vers de nouveaux domaines d'intake. Mettez à jour votre politique de sécurité du contenu :

En-têtes CORS pour le distributed tracing

v5 ajoute tracecontext comme propagateur par défaut. Si vous utilisez allowedTracingUrls, votre serveur doit accepter l'en-tête traceparent. Ajoutez-le à vos Access-Control-Allow-Headers existants — ne remplacez pas la liste complète :

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

Logs : error.origin supprimé

Mettez à jour les dashboards/moniteurs utilisant error.origin pour utiliser origin à la place.

Logs : préfixe d'erreur console supprimé

Le préfixe "console error:" est supprimé des messages de journal. Mettez à jour les requêtes utilisant ce préfixe pour utiliser @origin:console à la place.

Logs : logger principal découplé

Les erreurs runtime, les logs de réseau, les logs de rapport et les logs de console n'héritent plus du contexte, du niveau ou du gestionnaire du logger principal. Utilisez plutôt le contexte global et les paramètres d'init dédiés.

Recherchez la configuration du logger principal qui aurait pu dépendre de cet héritage : grep -rn 'DD_LOGS\.logger\.setLevel\|DD_LOGS\.logger\.setHandler\|DD_LOGS\.logger\.setContext\|DD_LOGS\.logger\.setContextProperty' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte". Pour chaque correspondance, vérifiez que le paramètre est intentionnel pour le logger principal uniquement — il n'affectera plus les erreurs runtime, les logs de réseau ou les logs de console.

Erreurs courantes

Liste de vérification de vérification

Après la mise à jour, confirmez :

• [ ] Le SDK se charge sans erreurs de console
• [ ] Aucune référence aux paramètres init supprimés (proxyUrl, sampleRate, replaySampleRate, etc.)
• [ ] Aucune référence aux APIs supprimées (addRumGlobalContext, removeUser, etc.)
• [ ] Les rappels beforeSend retournent des valeurs booléennes
• [ ] Les gestionnaires d'action beforeSend utilisent context.events (pas context.event)
• [ ] trackResources et trackLongTasks explicitement définis si vous utilisez sessionReplaySampleRate
• [ ] L'enregistrement Session Replay fonctionne (si sessionReplaySampleRate > 0)
• [ ] Le distributed tracing fonctionne (pas d'erreurs CORS du header traceparent)
• [ ] connect-src CSP mise à jour vers les nouveaux domaines d'intake
• [ ] Dashboards/moniteurs mis à jour pour resource.method en majuscules
• [ ] Aucune requête utilisant error.origin (utilisez origin à la place)