Associer RUM à vos traces

RUM et traces

Présentation

L’intégration d’APM avec la fonctionnalité Real User Monitoring vous permet de lier les requêtes de vos applications Web et mobiles aux traces backend correspondantes. Avec cette association, vous pouvez visualiser toutes vos données frontend et backend sous un seul angle.

Grâce aux données frontend de la fonctionnalité RUM et aux données relatives au backend, à l’infrastructure et aux logs provenant de l’injection d’ID de trace, vous pouvez identifier la cause de vos problèmes, où qu’ils se trouvent dans votre pile. Ainsi, vous saisissez parfaitement l’expérience que vous offrez à vos utilisateurs.

Pour commencer à envoyer les traces de votre application iOS à Datadog, consultez la section Collecte de traces iOS.

Utilisation

Prérequis

  • Vous avez configuré le tracing APM pour les services ciblés par vos applications RUM.
  • Vos services utilisent un serveur HTTP.
  • Vos serveurs HTTP utilisent une bibliothèque prenant en charge le tracing distribué.
  • Vous avez configuré ce qui suit en fonction de votre SDK :
    • Avec le SDK Browser, vous avez ajouté les ressources XMLHttpRequest (XHR) ou Fetch dans le RUM Explorer pour votre paramètre allowedTracingUrls.
    • Avec le SDK Mobile, vous avez ajouté les ressources Native ou XMLHttpRequest (XHR) pour votre paramètre firstPartyHosts.
  • Vous disposez de traces correspondant aux requêtes vers allowedTracingUrls ou firstPartyHosts.

Configurer RUM

Remarque : la configuration de RUM et des traces nécessite l’utilisation des données APM facturées dans RUM, ce qui peut affecter votre facture APM.

  1. Configurez la surveillance Browser RUM.

  2. Initialisez le SDK RUM. Configurez le paramètre d’initialisation allowedTracingUrls avec la liste des origines internes first party appelées par votre application Browser.

    Pour une installation via npm :

    import { datadogRum } from '@datadog/browser-rum'
    
    datadogRum.init({
        applicationId: '<DATADOG_APPLICATION_ID>',
        clientToken: '<DATADOG_CLIENT_TOKEN>',
        ...otherConfig,
        service: "my-web-application",
        allowedTracingUrls: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/, (url) => url.startsWith("https://api.example.com")]
    })
    

    Pour une installation via CDN :

    window.DD_RUM.init({
       clientToken: '<CLIENT_TOKEN>',
       applicationId: '<APPLICATION_ID>',
       site: '<http://datadoghq.com|datadoghq.com>',
       //  service: 'my-web-application',
       //  env: 'production',
       //  version: '1.0.0',
       allowedTracingUrls: ["<https://api.example.com>", /https:\/\/.*\.my-api-domain\.com/, (url) => url.startsWith("<https://api.example.com>")]
       sessionSampleRate: 100,
       sessionReplaySampleRate: 100, // if not included, the default is 100
       trackResources: true,
       trackLongTasks: true,
       trackUserInteractions: true,
     })
    

    Pour associer RUM à vos traces, vous devez indiquer votre application Browser dans le champ service.

    allowedTracingUrls prend l’URL complète (<schéma>://<host>[:<port>]/<chemin>[?<requête>][#<fragment>]). Ce paramètre accepte les types suivants :

    • string : toutes les URL qui commencent par la valeur définie sont incluses. Par exemple, https://api.example.com inclut https://api.example.com/v1/resource.
    • RegExp : exécute un test avec le RegExp et l’URL fournis.
    • function : l’URL est utilisée en tant que paramètre pour l’évaluation. Lorsqu’un boolean défini sur true est renvoyé, cela indique une correspondance.
  3. (Facultatif) Configurez le paramètre d’initialisation traceSampleRate pour conserver un certain pourcentage des traces backend. Si ce paramètre n’est pas défini, 100 % des traces issues des requêtes Browser sont envoyées à Datadog. Par exemple, pour ne conserver que 20 % des traces backend :

    import { datadogRum } from '@datadog/browser-rum'
    
    datadogRum.init({
        ...otherConfig,
        traceSampleRate: 20
    })
    

Remarque : le paramètre traceSampleRate n’affecte pas l’échantillonnage des sessions RUM. Seules les traces backend sont filtrées.

Le tracing de bout en bout est disponible pour les requêtes déclenchées après l'initialisation du SDK Browser. Le tracing de bout en bout du document HTML initial ainsi que des premières requêtes Browser n'est pas pris en charge.
  1. Configurez la surveillance Android RUM.

  2. Configurez la collecte de traces Android.

  3. Ajoutez la dépendance Gradle à la bibliothèque dd-sdk-android-okhttp dans le fichier build.gradle au niveau du module :

    dependencies {
        implementation "com.datadoghq:dd-sdk-android-okhttp:x.x.x"
    }
    
  4. Configurez l’intercepteur OkHttpClient avec la liste des origines internes first party appelées par votre application Android.

    val tracedHosts = listOf("example.com", "example.eu")
    
    val okHttpClient = OkHttpClient.Builder()
        .addInterceptor(DatadogInterceptor(tracedHosts))
        .addNetworkInterceptor(TracingInterceptor(tracedHosts))
        .eventListenerFactory(DatadogEventListener.Factory())
       .build()
    

    Par défaut, tous les sous-domaines des hosts répertoriés sont tracés. Par exemple, si vous ajoutez example.com, vous activez également le tracing de api.example.com et foo.example.com.

  5. (Facultatif) Configurez le paramètre traceSampler pour conserver un certain pourcentage des traces backend. Si ce paramètre n’est pas défini, 20 % des traces issues des requêtes d’application sont envoyées à Datadog. Pour conserver 100 % des traces backend :

    val okHttpClient = OkHttpClient.Builder()
       .addInterceptor(DatadogInterceptor(traceSampler = RateBasedSampler(100f)))
       .build()

Remarque : le paramètre traceSamplingRate n’affecte pas l’échantillonnage des sessions RUM. Seules les traces backend sont filtrées.

  1. Configurez la surveillance iOS RUM.

  2. Appelez la fonction builder trackURLSession(firstPartyHosts:) avec la liste des origines internes first party appelées par votre application iOS.

    Datadog.initialize(
        appContext: .init(),
        configuration: Datadog.Configuration
            .builderUsing(
                rumApplicationID: "<rum_app_id>", 
                clientToken: "<client_token>", 
                environment: "<env_name>"
            )
            .trackURLSession(firstPartyHosts: ["example.com", "api.yourdomain.com"])
            .build()
    )
    
  3. Initialisez le Tracer global :

    Global.sharedTracer = Tracer.initialize(
        configuration: Tracer.Configuration(...)
    )
    
  4. Initialisez URLSession tel qu’indiqué à la rubrique Configuration :

    let session =  URLSession(
        configuration: ...,
        delegate: DDURLSessionDelegate(),
        delegateQueue: ...
    )
    

    Par défaut, tous les sous-domaines des hosts répertoriés sont tracés. Par exemple, si vous ajoutez example.com, vous activez également le tracing de api.example.com et foo.example.com.

    Pour que l’injection des ID de trace fonctionne, vous devez spécifier une URLRequest pour la URLSession. Le tracing distribué ne fonctionne pas lorsque vous utilisez un objet URL.

  5. (Facultatif) Configurez le paramètre tracingSamplingRate pour conserver un certain pourcentage des traces backend. Si ce paramètre n’est pas défini, 20 % des traces issues des requêtes d’application sont envoyées à Datadog.

    Pour conserver 100 % des traces backend :

    Datadog.initialize(
        appContext: .init(),
        configuration: Datadog.Configuration
            .builderUsing(rumApplicationID: "<rum_app_id>", clientToken: "<client_token>", environment: "<env_name>")
            .set(tracingSamplingRate: 100)
            .build()
    )
    

Remarque : le paramètre tracingSamplingRate n’affecte pas l’échantillonnage des sessions RUM. Seules les traces backend sont filtrées.

  1. Configurez la surveillance React Native RUM.

  2. Configurez le paramètre d’initialisation firstPartyHosts pour définir la liste des origines internes first party appelées par votre application React Native.

    const config = new DatadogProviderConfiguration(
        // ...
    );
    config.firstPartyHosts = ["example.com", "api.yourdomain.com"];
    

    Par défaut, tous les sous-domaines des hosts répertoriés sont tracés. Par exemple, si vous ajoutez example.com, vous activez également le tracing de api.example.com et foo.example.com.

  3. (Facultatif) Configurez le paramètre resourceTracingSamplingRate pour conserver un certain pourcentage des traces backend. Si ce paramètre n’est pas défini, 20 % des traces issues des requêtes d’application sont envoyées à Datadog.

    Pour conserver 100 % des traces backend :

    const config = new DatadogProviderConfiguration(
        // ...
    );
    config.resourceTracingSamplingRate = 100;
    

    Remarque : le paramètre resourceTracingSamplingRate n’affecte pas l’échantillonnage des sessions RUM. Seules les traces backend sont filtrées.

  1. Configurez la surveillance Flutter RUM.

  2. Suivez les instructions de la section Suivi automatique de ressources pour inclure le package Datadog Tracking HTTP Client et activer le suivi HTTP. Vous devrez notamment apporter les modifications suivantes à vos paramètres d’initialisation pour ajouter la liste des origines internes first party appelées par votre application Flutter :

    final configuration = DdSdkConfiguration(
      // ...
      // added configuration
      firstPartyHosts: ['example.com', 'api.yourdomain.com'],
    )..enableHttpTracking()
    

RUM pour Roku n'est pas disponible pour le site US1-FED de Datadog.

RUM pour Roku est en version bêta.
  1. Configurez la surveillance Roku RUM.

  2. Utilisez le composant datadogroku_DdUrlTransfer pour lancer vos requêtes réseau.

        ddUrlTransfer = datadogroku_DdUrlTransfer(m.global.datadogRumAgent)
        ddUrlTransfer.SetUrl(url)
        ddUrlTransfer.EnablePeerVerification(false)
        ddUrlTransfer.EnableHostVerification(false)
        result = ddUrlTransfer.GetToString()
    

Vérification de la configuration

Pour vérifier que vous avez bien configuré l’intégration d’APM avec RUM, suivez les étapes ci-dessous en fonction du SDK avec lequel vous avez installé RUM.

  1. Consultez une page dans votre application.
  2. Dans les outils de développement de votre navigateur, accédez à l’onglet Network.
  3. Examinez les en-têtes de requête, trouvez une requête de ressource qui devrait être corrélée, et vérifiez qu’elle contient les en-têtes de mise en corrélation de Datadog.
  1. Exécutez votre application depuis Android Studio.
  2. Consultez un écran dans votre application.
  3. Ouvrez l’outil d’inspection de réseau d’Android Studio.
  4. Examinez les en-têtes de requête, trouvez une ressource RUM, et vérifiez que les en-têtes requis sont définis par le SDK.
  1. Exécutez votre application depuis Xcode.
  2. Consultez un écran dans votre application.
  3. Ouvrez l’instrument Network Connections and HTTP Traffic de Xcode.
  4. Examinez les en-têtes de requête, trouvez une ressource RUM, et vérifiez que les en-têtes requis sont définis par le SDK.
  1. Exécutez votre application depuis Xcode (iOS) ou Android Studio (Android).
  2. Consultez un écran dans votre application.
  3. Ouvrez l’instrument Network Connections and HTTP Traffic de Xcode ou l’outil d’inspection de réseau d’Android Studio.
  4. Examinez les en-têtes de requête, trouvez une ressource RUM, et vérifiez que les en-têtes requis sont définis par le SDK.
  1. Exécutez votre application depuis l’IDE de votre choix ou via flutter run.
  2. Consultez un écran dans votre application.
  3. Ouvrez les outils de développement de Flutter et accédez à la vue Réseau.
  4. Examinez les en-têtes de requête, trouvez une ressource RUM, et vérifiez que les en-têtes requis sont définis par le SDK.

Bibliothèques compatibles

Les bibliothèques de tracing Datadog suivantes sont prises en charge :

Prise en charge d’OpenTelemetry

RUM prend en charge plusieurs types de propagateurs pour associer les ressources aux backends instrumentés avec des bibliothèques OpenTelemetry.

  1. Configurez RUM pour qu’il se connecte avec APM en suivant les instructions ci-dessus.

  2. Modifiez le paramètre allowedTracingUrls comme suit :

    import { datadogRum } from '@datadog/browser-rum'
    
    datadogRum.init({
        ...otherConfig,
        allowedTracingUrls: [
          { match: "https://api.example.com", propagatorTypes: ["tracecontext"]}
        ]
    })
    

    match accepte les mêmes types de paramètres (string, RegExp ou function) que lorsqu’il est utilisé dans sa forme simple, comme décrit ci-dessus.

    propagatorTypes accepte une liste de chaînes avec les propagateurs souhaités :

  1. Configurez RUM pour qu’il se connecte avec APM en suivant les instructions ci-dessus.

  2. Utilisez trackURLSession(firstPartyHostsWithHeaderTypes:) au lieu de trackURLSession(firstPartyHosts:) comme suit :

    Datadog.initialize(
        appContext: .init(),
        configuration: Datadog.Configuration
            .builderUsing(
                rumApplicationID: "<rum_app_id>", 
                clientToken: "<client_token>", 
                environment: "<env_name>"
            )
            .trackURLSession(
                firstPartyHostsWithHeaderTypes: [
                    "api.example.com": [.tracecontext]
                ]
            )
            .build()
        )
    

    trackURLSession(firstPartyHostsWithHeaderTypes:) accepte Dictionary<Chaîne, Set<TypeEn-têteTracing>> en tant que paramètre, la clé étant un host et la valeur étant une liste de types d’en-têtes de tracing pris en charge.

    TracingHeaderType est un enum représentant les types d’en-têtes de tracing suivants :

  1. Configurez RUM pour qu’il se connecte avec APM en suivant les instructions ci-dessus.

  2. Configurez l’intercepteur OkHttpClient avec la liste des origines internes first party et le type d’en-tête de tracing à utiliser, comme suit :

    val tracedHosts = mapOf("example.com" to setOf(TracingHeaderType.TRACECONTEXT), 
                          "example.eu" to setOf(TracingHeaderType.DATADOG))
    
    val okHttpClient = OkHttpClient.Builder()
        .addInterceptor(DatadogInterceptor(tracedHosts))
        .addNetworkInterceptor(TracingInterceptor(tracedHosts))
        .eventListenerFactory(DatadogEventListener.Factory())
       .build()
    

    TracingHeaderType est un enum représentant les types d’en-têtes de tracing suivants :

  1. Configurez RUM pour qu’il se connecte avec APM.

  2. Configurez le SDK RUM avec la liste des origines internes first party et le type d’en-tête de tracing à utiliser, comme suit :

    const config = new DatadogProviderConfiguration(
        // ...
    );
    config.firstPartyHosts = [
        {match: "example.com", propagatorTypes: PropagatorType.TRACECONTEXT},
        {match: "example.com", propagatorTypes: PropagatorType.DATADOG}
    ];
    

    PropagatorType est un enum représentant les types d’en-têtes de tracing suivants :

  1. Configurez RUM pour qu’il se connecte avec APM en suivant les instructions ci-dessus.

  2. Utilisez firstPartyHostsWithTracingHeaders au lieu de firstPartyHosts, comme suit :

    final configuration = DdSdkConfiguration(
      // ...
      // added configuration
      firstPartyHostsWithTracingHeaders: {
        'example.com': { TracingHeaderType.tracecontext },
      },
    )..enableHttpTracking()
    

    firstPartyHostsWithTracingHeaders accepte Map<Châine, Set<TypeEn-têteTracing>> en tant que paramètre, la clé étant un host et la valeur étant une liste de types d’en-têtes de tracing pris en charge.

    TracingHeaderType est un enum représentant les types d’en-têtes de tracing suivants :

Comment les ressources RUM sont-elles associées aux traces ?

Datadog utilise un protocole de tracing distribué et configure les en-têtes HTTP suivants :

x-datadog-trace-id
Généré à partir du SDK RUM. Permet à Datadog de lier la trace à la ressource RUM.
x-datadog-parent-id
Généré à partir du SDK RUM. Permet à Datadog de générer la première span depuis la trace.
x-datadog-origin: rum
Permet de s’assurer que les traces générées à partir de la fonctionnalité RUM ne rentrent pas en compte dans le calcul de vos spans indexées APM.
x-datadog-sampling-priority: 1
Permet de s’assurer que l’Agent conserve la trace.
traceparent: [version]-[trace id]-[parent id]-[trace flags]
version : la spécification actuelle part du principe que la version est définie sur 00.
trace id : ID de trace 128 bits, hexadécimal sur 32 caractères. L’ID de la trace source est en 64 bits pour assurer la compatibilité avec APM.
parent id : ID de span 64 bits, hexadécimal sur 16 caractères.
trace flags : avec échantillonnage (01) ou sans échantillonnage (00)
Exemple :
traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331s-01
b3: [trace id]-[span id]-[sampled]
trace id : ID de trace 64 bits, hexadécimal sur 16 caractères.
span id : ID de span 64 bits, hexadécimal sur 16 caractères.
sampled : True (1) ou False (0)
Exemple pour le propagateur b3 single header :
b3: 8448eb211c80319c-b7ad6b7169203331-1
Exemple pour le propagateur b3 multiple headers :
X-B3-TraceId: 8448eb211c80319c
X-B3-SpanId: b7ad6b7169203331
X-B3-Sampled: 1

Ces en-têtes HTTP ne sont pas ajoutés à la liste blanche du mécanisme CORS. Vous devez donc configurer Access-Control-Allow-Headers sur le serveur traitant les requêtes que le SDK surveille. Le serveur doit également accepter les requêtes préliminaires (requêtes OPTIONS), qui sont transmises par le SDK avant chaque requête.

Cela a-t-il une incidence sur les quotas d’APM ?

Le fait d’associer RUM à vos traces peut considérablement augmenter les volumes ingérés par APM. Utilisez le paramètre d’initialisation traceSampleRate pour ne conserver qu’une partie des traces backend issues des requêtes Browser et Mobile.

Pendant combien de temps les traces sont-elles conservées ?

Ces traces restent disponibles pendant 15 minutes dans l’explorateur Live Search. Pour augmenter la durée de rétention des traces, créez des filtres de rétention. Définissez des tags de span spécifiques sur ces filtres pour ne conserver que les traces associées aux pages et aux actions utilisateur qui vous intéressent.

Pour aller plus loin