Modifier des données RUM et leur contexte

Présentation

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 Browser 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 monopages). Un nom de vue est généré à partir de l’URL de la page active, et les ID alphanumériques de variable sont supprimés automatiquement : par exemple, /dashboard/1234 devient /dashboard/?.

Depuis la version 2.17.0, vous pouvez ajouter des noms de vue et les attribuer à un service dédié appartenant à une équipe, en effectuant un suivi manuel des événements de vue avec l’option trackViewsManually :

1. Définissez trackViewsManually sur true lors de l’initialisation du SDK Browser 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 lancer des vues pour chaque nouvelle page ou chaque changement de route (pour les applications monopages). Les données RUM sont recueillies à l’initialisation de la vue. Vous avez également la possibilité de définir le nom de la vue associée, le nom du service ainsi que la version.

   • Vue : correspond par défaut au chemin d’URL de la page.
   • Service : correspond pas défaut au service par défaut spécifié lors de la création de votre application RUM.
   • Version : correspond pas défaut à la version par défaut spécifiée lors de la création de votre application RUM.

   Pour en savoir plus, consultez la section Surveillance Browser RUM.

L’exemple suivant permet de surveiller manuellement les vues de la page checkout d’une application RUM. Utilisez le nom de vue checkout, avec le service purchase et la version 1.2.3.

datadogRum.startView({
  name: 'checkout',
  service: 'purchase',
  version: '1.2.3'
})

DD_RUM.onReady(function() {
    DD_RUM.startView({
      name: 'checkout',
      service: 'purchase',
      version: '1.2.3'
    })
})

window.DD_RUM && window.DD_RUM.startView({
  name: 'checkout',
  service: 'purchase',
  version: '1.2.3'
})

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 Browser 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 Browser RUM avant qu’il ne 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

Depuis la version 2.13.0, beforeSend prend deux arguments : event, qui fait référence à l’événement généré par le SDK Browser 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 :

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 associer 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 des 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}
            }
        },
        ...
    });

Lorsqu’un utilisateur appartient à plusieurs équipes, ajoutez des paires key-value supplémentaires dans vos appels de l’API de contexte global.

Le SDK Browser RUM ignore :

• les attributs ajoutés en dehors de event.context ;
• les modifications apportées à un contexte d’événement de vue RUM.

Modifier le contenu d’un événement RUM

Par exemple, pour 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 :

Le SDK Browser RUM ne tient pas compte des modifications apportées aux propriétés d’événement non répertoriées ci-dessus. Pour en savoir plus les propriétés d’événement, consultez le référentiel GitHub du SDK Browser RUM.

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
            }
            ...
        },
        ...
    });

Session utilisateur

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

• 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 Datadog vous recommande d’en renseigner au moins un :

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.

Lorsque vous modifiez l’objet de la session utilisateur, tous les événements RUM recueillis après la modification contiennent les informations les plus récentes.

Identifier une session utilisateur

datadogRum.setUser(<OBJET_CONFIGURATION_UTILISATEUR>)

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',
    ...
})

Accéder à une session utilisateur

datadogRum.getUser()

datadogRum.getUser()

DD_RUM.onReady(function() {
    DD_RUM.getUser()
})

window.DD_RUM && window.DD_RUM.getUser()

Ajouter ou remplacer une propriété de session utilisateur

datadogRum.setUserProperty('<CLÉ_UTILISATEUR>', <VALEUR_UTILISATEUR>)

datadogRum.setUserProperty('name', 'John Doe')

DD_RUM.onReady(function() {
    DD_RUM.setUserProperty('name', 'John Doe')
})

window.DD_RUM && window.DD_RUM.setUserProperty('name', 'John Doe')

Supprimer une propriété de session utilisateur

datadogRum.removeUserProperty('<CLÉ_UTILISATEUR>')

datadogRum.removeUserProperty('name')

DD_RUM.onReady(function() {
    DD_RUM.removeUserProperty('name')
})

window.DD_RUM && window.DD_RUM.removeUserProperty('name')

Effacer une propriété de session utilisateur

datadogRum.clearUser()

datadogRum.clearUser()

DD_RUM.onReady(function() {
    DD_RUM.clearUser()
})

window.DD_RUM && window.DD_RUM.clearUser()

É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 sessionSampleRate 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>',
    sessionSampleRate: 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-v4.js','DD_RUM')
  DD_RUM.onReady(function() {
    DD_RUM.init({
        clientToken: '<TOKEN_CLIENT>',
        applicationId: '<ID_APPLICATION>',
        site: '<SITE_DATADOG>',
        sessionSampleRate: 90,
    })
  })
</script>

window.DD_RUM &&
    window.DD_RUM.init({
        clientToken: '<TOKEN_CLIENT>',
        applicationId: '<ID_APPLICATION>',
        site: '<SITE_DATADOG>',
        sessionSampleRate: 90,
    });

Lorsqu’une session est exclue en raison d’un échantillonnage, aucune vue de page ni aucune donnée de télémétrie associée à cette session ne sont recueillies.

Contexte global

Ajouter une propriété de 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 setGlobalContextProperty(key: string, value: any) :

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

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

// Exemple de code
datadogRum.setGlobalContextProperty('activity', {
    hasPaid: true,
    amount: 23.42
});

DD_RUM.onReady(function() {
    DD_RUM.setGlobalContextProperty('<CLÉ_CONTEXTE>', '<VALEUR_CONTEXTE>');
})

// Exemple de code
DD_RUM.onReady(function() {
    DD_RUM.setGlobalContextProperty('activity', {
        hasPaid: true,
        amount: 23.42
    });
})

window.DD_RUM && window.DD_RUM.setGlobalContextProperty('<CLÉ_CONTEXTE>', '<VALEUR_CONTEXTE>');

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

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

Supprimer une propriété de contexte global

Vous pouvez supprimer une propriété de contexte global précédemment définie.

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

Remplacez le contexte par défaut de tous vos événements RUM avec l’API setGlobalContext(context: Context) :

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

Effacer le contexte global

Vous pouvez effacer le contexte global à l’aide du paramètre clearGlobalContext.

Lire le contexte global

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

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Real User MonitoringBLOG Données RUM recueillies (Browser)DOCUMENTATION Explorer vos vues dans DatadogDOCUMENTATION Appliquer des visualisations sur vos événementsDOCUMENTATION Attributs standard DatadogDOCUMENTATION