Modifier des données RUM et leur contexte

Modifier des données RUM et leur contexte

Vous pouvez modifier les données collectées par la fonctionnalité RUM de diverses façons afin de mieux répondre à vos besoins. Par exemple :

  • Protection des données sensibles, telles que les informations personnelles.
  • Connexion d’une session utilisateur à votre identification interne de cet utilisateur afin de faciliter l’assistance.
  • Réduction de la quantité de données RUM recueillies, à l’aide d’un échantillonnage des données.
  • Ajout de données de contexte en plus des attributs par défaut afin de mieux déterminer l’origine des données.

Remplacer les noms de vue RUM par défaut

Le SDK RUM génère automatiquement un événement de vue à chaque fois qu’un utilisateur consulte une nouvelle page, ou lorsque l’URL de la page est modifiée (pour les applications monopage). Un nom de vue est généré à partir de l’URL de la page en cours, où les ID alphanumériques de variable sont supprimés automatiquement : par exemple, « /dashboard/1234 » devient « /dashboard/? ».

À partir de la version 2.17.0, vous pouvez indiquer vos propres noms de vue en effectuant un suivi manuel des événements de vue avec l’option trackViewsManually :

  1. Configurez trackViewsManually sur true lors de l’initialisation du RUM.

    import { datadogRum } from '@datadog/browser-rum';
    
    datadogRum.init({
        ...,
        trackViewsManually: true,
        ...
    });
    
    DD_RUM.onReady(function() {
        DD_RUM.init({
            ...,
            trackViewsManually: true,
            ...
        })
    })
    
    window.DD_RUM &&
        window.DD_RUM.init({
            ...,
            trackViewsManually: true,
            ...
        });
    

  2. Vous devez démarrer une vue pour chaque nouvelle page ou changement de route (pour les applications monopage). Vous avez la possibilité de définir le nom de vue associé, qui a pour valeur par défaut le chemin de l’URL de la page. Aucune donnée RUM n’est recueillie tant que la vue n’est pas démarrée.

    datadogRum.startView('checkout')
    
    DD_RUM.onReady(function() {
        DD_RUM.startView('checkout')
    })
    
    window.DD_RUM && window.DD_RUM.startView('checkout')
    

Remarque : si vous utilisez React, Angular, Vue ou tout autre framework frontend, Datadog recommande d’implémenter la logique startView au niveau du routeur du framework.

Enrichir et contrôler les données RUM

Le SDK RUM enregistre les événements RUM et renseigne les attributs principaux correspondants. La fonction de rappel beforeSend vous permet d’accéder à chaque événement recueilli par le SDK RUM avant qu’il soit envoyé à Datadog. L’interception d’événements RUM vous permet d’effectuer les opérations suivantes :

  • Enrichir vos événements RUM avec des attributs de contexte supplémentaires
  • Modifier vos événements RUM pour en modifier le contenu ou pour effacer les séquences sensibles (consultez la liste des propriétés modifiables)
  • Ignorer des événements RUM sélectionnés

À partir de la version 2.13.0, beforeSend prend deux arguments : event, qui fait référence à l’événement généré par le SDK RUM, et context, qui fait référence au contexte qui a déclenché la création de l’événement RUM.

function beforeSend(event, context)

Voici les valeurs possibles pour context :

Type d’événement RUMContexte
VueLocation
ActionEvent
Ressource (XHR)XMLHttpRequest et PerformanceResourceTiming
Ressource (Fetch)Request, Response et PerformanceResourceTiming
Ressource (autre)PerformanceResourceTiming
ErreurError
Tâche longuePerformanceLongTaskTiming

Pour en savoir plus, consultez le guide pour enrichir et contrôler les données RUM.

Enrichir des événements RUM

En plus des attributs ajoutés avec l'API de contexte global, vous pouvez ajouter d’autres attributs de contexte à l’événement. Par exemple, ajoutez des tags à vos événements de ressource RUM à l’aide des données extraites à partir d’un objet de réponse Fetch :

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    beforeSend: (event, context) => {
        // recueillir les en-têtes de réponse d'une ressource RUM
        if (event.type === 'resource' && event.resource.type === 'fetch') {
            event.context = {...event.context, responseHeaders: context.response.headers}
        }
    },
    ...
});
DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event, context) => {
            // recueillir les en-têtes de réponse d'une ressource RUM
            if (event.type === 'resource' && event.resource.type === 'fetch') {
                event.context = {...event.context, responseHeaders: context.response.headers}
            }
        },
        ...
    })
})
window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event, context) => {
            // recueillir les en-têtes de réponse d'une ressource RUM
            if (event.type === 'resource' && event.resource.type === 'fetch') {
                event.context = {...event.context, responseHeaders: context.response.headers}
            }
        },
        ...
    });

Remarque : le SDK RUM ne tient pas compte des éléments suivants :

  • Attributs ajoutés en dehors de event.context.
  • Modifications apportées à un contexte d’événement de vue RUM.

Modifier le contenu d’un événement RUM

Vous pouvez par exemple censurer les adresses e-mail de vos URL d’applications Web :

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    beforeSend: (event) => {
        // supprimer l'adresse e-mail de l'url de la vue
        event.view.url = event.view.url.replace(/email=[^&]*/, "email=CENSURÉ")
    },
    ...
});
DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event) => {
            // supprimer l'adresse e-mail de l'url de la vue
            event.view.url = event.view.url.replace(/email=[^&]*/, "email=CENSURÉ")
        },
        ...
    })
})
window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event) => {
            // supprimer l'adresse e-mail de l'url de la vue
            event.view.url = event.view.url.replace(/email=[^&]*/, "email=CENSURÉ")
        },
        ...
    });

Vous pouvez modifier les propriétés d’événement suivantes :

AttributTypeDescription
view.urlChaîneL’URL de la page Web active.
view.referrerChaîneL’URL de la page Web précédente à partir de laquelle l’utilisateur a accédé à la page actuelle.
action.target.nameChaîneL’élément avec lequel l’utilisateur a interagi. Uniquement pour les actions recueillies automatiquement.
error.messageChaîneUn message d’une ligne lisible et concis décrivant l’erreur.
error.stackChaîneLa stack trace ou toutes informations complémentaires relatives à l’erreur.
error.resource.urlChaîneL’URL de la ressource qui a déclenché l’erreur.
resource.urlChaîneL’URL de la ressource.
contextObjetAttributs ajoutés via l'API de contexte global ou lors de la génération manuelle d’événements (par exemple, addError et addAction). La valeur context des événements de vue RUM est en lecture seule.

Remarque : le SDK RUM ne tient pas compte des modifications apportées aux propriétés d’événement non répertoriées ci-dessus. Découvrez toutes les propriétés d’événement sur le référentiel du SDK Browser.

Ignorer un événement RUM

L’API beforeSend vous permet d’ignorer un événement RUM en renvoyant false :

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    ...,
    beforeSend: (event) => {
        if (shouldDiscard(event)) {
            return false
        }
        ...
    },
    ...
});
DD_RUM.onReady(function() {
    DD_RUM.init({
        ...,
        beforeSend: (event) => {
            if (shouldDiscard(event)) {
                return false
            },
            ...
        },
        ...
    })
})
window.DD_RUM &&
    window.DD_RUM.init({
        ...,
        beforeSend: (event) => {
            if (shouldDiscard(event)) {
                return false
            }
            ...
        },
        ...
    });

Identifier les sessions utilisateur

L’ajout des informations utilisateur à vos sessions RUM facilite :

  • le suivi du parcours d’un utilisateur donné ;
  • l’identification des utilisateurs les plus touchés par les erreurs ;
  • la surveillance des performances de vos utilisateurs les plus importants.

Les attributs suivants sont facultatifs, mais nous vous conseillons d’en renseigner au moins un :

AttributTypeDescription
usr.idChaîneIdentificateur d’utilisateur unique.
usr.nameChaîneNom courant de l’utilisateur, affiché par défaut dans l’interface RUM.
usr.emailChaîneAdresse e-mail de l’utilisateur, affichée dans l’interface RUM si le nom de l’utilisateur n’est pas connu. Elle sert également à récupérer des Gravatars.

Remarque : améliorez vos capacités de filtrage en ajoutant d’autres attributs en plus de ceux recommandés. Par exemple, ajoutez des informations à propos de l’abonnement de l’utilisateur, ou du groupe d’utilisateurs auquel il appartient.

Pour identifier les sessions utilisateur, utilisez l’API setUser :

datadogRum.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
    plan: 'premium',
    ...
})
DD_RUM.onReady(function() {
    DD_RUM.setUser({
        id: '1234',
        name: 'John Doe',
        email: 'john@doe.com',
        plan: 'premium',
        ...
    })
})
window.DD_RUM && window.DD_RUM.setUser({
    id: '1234',
    name: 'John Doe',
    email: 'john@doe.com',
    plan: 'premium',
    ...
})

Supprimer l’identification de l’utilisateur

Supprimez un utilisateur précédemment défini avec l’API removeUser. Tous les événements RUM recueillis par la suite ne contiendront pas d’informations sur l’utilisateur.

datadogRum.removeUser()
DD_RUM.onReady(function() {
    DD_RUM.removeUser()
})
window.DD_RUM && window.DD_RUM.removeUser()

Échantillonnage

Par défaut, aucun échantillonnage n’est appliqué au nombre de sessions recueillies. Pour appliquer un échantillonnage relatif (en pourcentage), utilisez le paramètre sampleRate lors de l’initialisation de RUM. L’exemple suivant recueille seulement 90 % de toutes les sessions pour une application RUM donnée :

import { datadogRum } from '@datadog/browser-rum';

datadogRum.init({
    applicationId: '<ID_APPLICATION_DATADOG>',
    clientToken: '<TOKEN_CLIENT_DATADOG>',
    site: '<SITE_DATADOG>',
    sampleRate: 90,
});
<script>
 (function(h,o,u,n,d) {
   h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
   d=o.createElement(u);d.async=1;d.src=n
   n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
})(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-rum.js','DD_RUM')
  DD_RUM.onReady(function() {
    DD_RUM.init({
        clientToken: '<TOKEN_CLIENT>',
        applicationId: '<ID_APPLICATION>',
        site: '<SITE_DATADOG>',
        sampleRate: 90,
    })
  })
</script>
window.DD_RUM &&
    window.DD_RUM.init({
        clientToken: '<TOKEN_CLIENT>',
        applicationId: '<ID_APPLICATION>',
        site: '<SITE_DATADOG>',
        sampleRate: 90,
    });

Remarque : lorsqu’une session est exclue en raison d’un échantillonnage, toutes les vues de page et la télémétrie associées à cette session ne sont pas recueillies.

Contexte global

Ajouter un contexte global

Une fois la fonctionnalité RUM initialisée, ajoutez du contexte supplémentaire à l’ensemble des événements RUM recueillis depuis votre application avec l’API addRumGlobalContext(key: string, value: any) :

import { datadogRum } from '@datadog/browser-rum';

datadogRum.addRumGlobalContext('<CLÉ_CONTEXTE>', <VALEUR_CONTEXTE>);

// Exemple de code
datadogRum.addRumGlobalContext('activity', {
    hasPaid: true,
    amount: 23.42
});
DD_RUM.onReady(function() {
    DD_RUM.addRumGlobalContext('<CLÉ_CONTEXTE>', '<VALEUR_CONTEXTE>');
})

// Exemple de code
DD_RUM.onReady(function() {
    DD_RUM.addRumGlobalContext('activity', {
        hasPaid: true,
        amount: 23.42
    });
})
window.DD_RUM && window.DD_RUM.addRumGlobalContext('<CLÉ_CONTEXTE>', '<VALEUR_CONTEXTE>');

// Exemple de code
window.DD_RUM && window.DD_RUM.addRumGlobalContext('activity', {
    hasPaid: true,
    amount: 23.42
});

Remarque : respectez la convention de nommage Datadog pour améliorer la corrélation de vos données sur l’ensemble de la solution.

Remplacer le contexte global

Une fois la fonctionnalité RUM initialisée, remplacez le contexte par défaut de tous vos événements RUM avec l’API setRumGlobalContext(context: Context) :

import { datadogRum } from '@datadog/browser-rum';

datadogRum.setRumGlobalContext({ '<CLÉ_CONTEXTE>': '<VALEUR_CONTEXTE>' });

// Exemple de code
datadogRum.setRumGlobalContext({
    codeVersion: 34,
});
DD_RUM.onReady(function() {
    DD_RUM.setRumGlobalContext({ '<CLÉ_CONTEXTE>': '<VALEUR_CONTEXTE>' });
})

// Exemple de code
DD_RUM.onReady(function() {
    DD_RUM.setRumGlobalContext({
        codeVersion: 34,
    })
})
window.DD_RUM &&
    DD_RUM.setRumGlobalContext({ '<CLÉ_CONTEXTE>': '<VALEUR_CONTEXTE>' });

// Exemple de code
window.DD_RUM &&
    DD_RUM.setRumGlobalContext({
        codeVersion: 34,
    });

Remarque : respectez la convention de nommage Datadog pour améliorer la corrélation de vos données sur l’ensemble de la solution.

Lire le contexte global

Une fois la fonctionnalité RUM initialisée, lisez le contexte global avec l’API getRumGlobalContext() :

import { datadogRum } from '@datadog/browser-rum';

const context = datadogRum.getRumGlobalContext();
DD_RUM.onReady(function() {
  var context = DD_RUM.getRumGlobalContext();
});
var context = window.DD_RUM && DD_RUM.getRumGlobalContext();

Pour aller plus loin