Mettre à niveau le Datadog RUM Android SDK de la v2 à la v3

Utilisez cette skill quand un projet Android utilise Datadog Mobile SDK 2.x et doit être mis à niveau vers la dernière version stable 3.x. La migration v3 supprime le support OpenTracing hérité et met à jour les API dans les modules du SDK Android.

Cette skill incorpore les conseils de migration Android v2-to-v3 de DataDog/documentation, examinés au commit a27f7562165b9058f8cd597b48473cc7ecbeda81 le 2026-09-25. Utilisez les instructions ci-dessous comme source de vérité pour la migration ; consultez la documentation en direct uniquement si le projet contient une API non couverte ici ou si la cible demandée est plus récente que cette révision examinée.

1. Établir l'étendue de la migration

Avant d'éditer, inspectez l'ensemble du projet Android pour :

• chaque dépendance com.datadoghq:dd-sdk-android-*, y compris les dépendances dans les catalogues de versions, les plugins de convention et les builds inclus ;
• chaque import com.datadog.android et io.opentracing ;
• les appels qui initialisent Datadog ou activent RUM, Logs, Trace, Crash Reporting, Session Replay, WebView tracking ou NDK crash reporting ;
• les endpoints personnalisés passés à useCustomEndpoint ;
• les appels manuels de ressources RUM et le tracing personnalisé ;
• la construction de DatadogInterceptor et TracingInterceptor ;
• le minSdk et la version Kotlin du projet.

Ne supprimez pas une fonctionnalité Datadog, un chemin d'instrumentation ou un test simplement pour rendre la mise à niveau compilable. Préservez le comportement de télémétrie existant de l'application.

2. Satisfaire aux exigences de plateforme v3

• Définissez le niveau d'API Android minimum à au moins 23. Si l'application ne peut pas augmenter minSdk à 23, arrêtez et signalez qu'elle ne peut pas adopter le SDK v3.
• Utilisez Kotlin 1.9 ou plus récent.
• Si le projet utilise Jetpack Compose avec Kotlin inférieur à 2.0, mettez à jour Kotlin et composeOptions.kotlinCompilerExtensionVersion ensemble en utilisant la carte de compatibilité officielle Compose-Kotlin. Ne supprimez pas la vérification de compatibilité.
• Pour Kotlin 2.0 ou plus récent, utilisez le plugin Gradle Compose Compiler comme indiqué par la documentation de compatibilité au lieu de choisir une version dans le tableau de compatibilité hérité.
• Supprimez les dépendances OpenTracing directes après la migration de tout le code OpenTracing.
• Si la migration de trace OpenTelemetry préférée est utilisée avec minSdk inférieur à 26, activez le desugaring de la core-library comme requis par OpenTelemetry Java.

3. Mettre à niveau les dépendances du SDK

Avant de modifier les dépendances, interrogez les versions officielles DataDog/dd-sdk-android sur GitHub et sélectionnez la version sémantique stable la plus élevée correspondant à 3.x.y. Ignorez les brouillons, les préversions, les candidats à la version, les versions -SNAPSHOT et les versions d'autres versions majeures. L'API GitHub Releases peut être interrogée à :

https://api.github.com/repos/DataDog/dd-sdk-android/releases?per_page=100

Utilisez les champs tag_name, draft et prerelease de chaque objet de version plutôt que de supposer que le premier tag ou le changelog de développement du référentiel est une version stable. Si GitHub ne peut pas être atteint ou la réponse ne peut pas être analysée, utilisez 3.14.1 comme version de secours et signalez explicitement ce secours.

Remplacez chaque artefact Datadog Android SDK de 2.x par la version 3.x concrète sélectionnée. Suivez la convention de gestion des versions existante du projet et mettez à jour le lockfile ou le catalogue de versions où applicable.

N'introduisez pas de versions mobiles comme 3.+ ou latest.release, et ne laissez pas un mélange d'artefacts Datadog v2 et v3 dans le graphique de dépendances résolu.

Si l'application utilise Jetpack Compose et active l'instrumentation Compose dans le plugin Gradle Datadog, ajoutez l'intégration v3 Compose à la même version du SDK :

implementation("com.datadoghq:dd-sdk-android-compose:<datadog-v3-version>")

Laisser l'instrumentation Compose activée sans cet artefact fait échouer le plugin compilateur Datadog avec une erreur de dépendance manquante.

4. Migrer Core

L'ID utilisateur passé à Datadog.setUserInfo est obligatoire en v3. Remplacez null par l'identifiant d'utilisateur stable de l'application :

// v2
Datadog.setUserInfo(null, "Jane Smith", "jane@example.com")

// v3
Datadog.setUserInfo("user123", "Jane Smith", "jane@example.com")

N'inventez pas une valeur d'identité de production. Réutilisez l'identifiant d'utilisateur réel de l'application ou préservez sa stratégie d'utilisateur anonyme existante avec un identifiant non-null approprié.

5. Migrer RUM

Endpoint personnalisé

RumConfiguration.Builder.useCustomEndpoint doit recevoir l'URL d'upload RUM complète plutôt que seulement un hôte :

Rum.enable(
    RumConfiguration.Builder("<application-id>")
        .useCustomEndpoint("https://example.com/rum/upload")
        .build()
)

Préservez l'hôte personnalisé et le chemin du projet.

Ressources manuelles

Remplacez l'argument de méthode HTTP en chaîne de startResource par RumResourceMethod :

import com.datadog.android.rum.RumResourceMethod

GlobalRumMonitor.get().startResource(
    key = "resource-key",
    method = RumResourceMethod.GET,
    url = "https://example.com/api/resource",
    attributes = mapOf("source" to "manual")
)

Utilisez le membre d'énumération correspondant à la méthode d'origine ; ne définissez pas par défaut chaque ressource à GET.

Renommage du moniteur global

Mettez à jour le symbole RUM global :

Utilisez GlobalRumMonitor.get() pour accéder au moniteur enregistré. Ne le remplacez pas par RumMonitor.get() ; RumMonitor ne fournit pas cet accesseur v3.

Attributs optionnels

En v3, le paramètre attributes: Map<String, Any?> est optionnel pour ces API :

• RumMonitor.addAction
• RumMonitor.startAction
• RumMonitor.stopResource
• RumMonitor.addError
• RumMonitor.addErrorWithStacktrace
• AdvancedNetworkRumMonitor.stopResource

Les cartes d'attributs existantes restent valides. Supprimez les cartes vides redondantes uniquement quand cela améliore le code migré sans changer le comportement.

6. Migrer Logs et Error Tracking de crash

Logs ne signale plus les erreurs fatales d'elle-même. Si l'application existante s'attend à ce que les crashes apparaissent dans Error Tracking, gardez RUM activé et activez Crash Reporting explicitement en plus de Logs.

LogsConfiguration.Builder.useCustomEndpoint doit recevoir l'URL d'upload Logs complète :

Logs.enable(
    LogsConfiguration.Builder()
        .useCustomEndpoint("https://example.com/logs/upload")
        .build()
)

Préservez tous les produits qui étaient activés avant la migration. En particulier, ne supprimez pas Rum.enable(...) ou Logs.enable(...) pour résoudre les échecs de compilation.

7. Migrer Trace

TraceConfiguration.Builder.useCustomEndpoint doit recevoir l'URL d'upload Trace complète :

Trace.enable(
    TraceConfiguration.Builder()
        .useCustomEndpoint("https://example.com/trace/upload")
        .build()
)

Le SDK v3 supprime OpenTracing. Choisissez l'une des migrations suivantes en fonction des contraintes du projet.

Préféré : migrer vers OpenTelemetry

Ajoutez le pont v3 OpenTelemetry en utilisant la même version du SDK que les autres artefacts Datadog :

implementation("com.datadoghq:dd-sdk-android-trace-otel:<datadog-v3-version>")

Pour le cas simple, remplacez l'enregistrement du traceur global :

// v2 OpenTracing
GlobalTracer.registerIfAbsent(
    AndroidTracer.Builder()
        .setService(BuildConfig.APPLICATION_ID)
        .build()
)

// v3 OpenTelemetry
GlobalOpenTelemetry.set(
    DatadogOpenTelemetry(BuildConfig.APPLICATION_ID)
)

DatadogOpenTelemetry est un wrapper de commodité. Son constructeur accepte uniquement le nom du service ; ne lui passez pas de SdkCore. Quand le traceur v2 a une configuration de constructeur personnalisée, comme une instance SDK ou un seuil de vidage partiel, construisez le provider directement à la place :

val tracerProvider = OtelTracerProvider.Builder(sdkCore)
    .setService(BuildConfig.APPLICATION_ID)
    .setPartialFlushThreshold(4)
    .build()

GlobalOpenTelemetry.set(object : OpenTelemetry {
    override fun getTracerProvider(): TracerProvider = tracerProvider

    override fun getPropagators(): ContextPropagators = ContextPropagators.noop()
})

val tracer = tracerProvider.get("SampleApplicationTracer")

OtelTracerProvider.Builder(...).build() retourne un TracerProvider, pas une instance OpenTelemetry. Ne passez pas le provider directement à GlobalOpenTelemetry.set(...) ; enveloppez-le comme montré ci-dessus.

setPartialFlushThreshold appartient à OtelTracerProvider.Builder, pas au OtelTracerProvider construit. Configurez-le avant d'appeler build() ; ne castez pas openTelemetry.tracerProvider et n'essayez pas de le muter ensuite.

Remplacez le tracing manuel par l'API OpenTelemetry :

val tracer: Tracer = GlobalOpenTelemetry
    .get()
    .getTracer("SampleApplicationTracer")

val span = tracer
    .spanBuilder("Executing operation")
    .startSpan()

// Instrumented operation

span.end()

Appliquez ces mappages de type et d'API :

Secours transitoire : migrer vers l'API de tracing Datadog

Utilisez ce chemin uniquement quand le projet ne peut pas activer le desugaring requis par OpenTelemetry. Il existe pour faciliter la migration et peut être supprimé dans une future version majeure du SDK.

Remplacez l'enregistrement du traceur global :

// v2 OpenTracing
GlobalTracer.registerIfAbsent(
    AndroidTracer.Builder()
        .setService(BuildConfig.APPLICATION_ID)
        .build()
)

// v3 API de tracing Datadog
GlobalDatadogTracer.registerIfAbsent(
    DatadogTracing.newTracerBuilder(sdkCore)
        .withServiceName(BuildConfig.APPLICATION_ID)
        .withPartialFlushMinSpans(4)
        .build()
)

Remplacez le tracing manuel :

val tracer = GlobalDatadogTracer.get()

val span = tracer
    .buildSpan("Executing operation")
    .start()

val scope = tracer.activateSpan(span)
try {
    // Instrumented operation
    val traceId = span.context().traceId.toString()
} finally {
    scope?.close()
    span.finish()
}

DatadogTracer.activateSpan() retourne un DatadogScope nullable ; fermez-le avec scope?.close().

DatadogSpan.context() est une fonction, pas une propriété Kotlin. Appelez-la avec des parenthèses : utilisez span.context().traceId, pas span.context.traceId.

Appliquez ces mappages de type et d'API :

Après l'un ou l'autre chemin, vérifiez qu'aucune source ou dépendance ne repose toujours sur io.opentracing.

8. Migrer l'instrumentation OkHttp

L'artefact com.datadoghq:dd-sdk-android-okhttp lui-même ne nécessite pas de desugaring. Remplacez les constructeurs positionnels supprimés par des builders tout en préservant les noms de service, les hôtes tracés et les types d'en-têtes, les écouteurs, les providers d'attributs de ressources et les samplers.

Recherchez chaque surcharge, y compris les constructeurs qui acceptent toute combinaison de :

• un nom de service nullable ;
• des hôtes tracés List<String> ;
• une configuration d'hôtes tracés Map<String, Set<TracingHeaderType>> ;
• TracedRequestListener ;
• RumResourceAttributesProvider ;
• Sampler<Span>.

Le builder nécessite soit List<String> soit Map<String, Set<TracingHeaderType>> dans son constructeur. Il n'y a pas de builder sans argument et pas de méthode setTracedHostsWithHeaderType. Ne supprimez pas les arguments du constructeur lors de la conversion ; mappez chaque comportement à l'option du builder correspondante :

val datadogInterceptor = DatadogInterceptor.Builder(tracedHostsWithHeaderType)
    .setSdkInstanceName(sdkCore.name)
    .setTracedRequestListener(tracedRequestListener)
    .setRumResourceAttributesProvider(resourceAttributesProvider)
    .setTraceSampler(DeterministicTraceSampler(20f))
    .build()

val tracingInterceptor = TracingInterceptor.Builder(tracedHostsWithHeaderType)
    .setSdkInstanceName(sdkCore.name)
    .setTracedRequestListener(tracedRequestListener)
    .setTraceSampler(DeterministicTraceSampler(20f))
    .build()

En v3, TracedRequestListener reçoit un span Datadog, même quand le tracing manuel de l'application utilise OpenTelemetry :

val tracedRequestListener = object : TracedRequestListener {
    override fun onRequestIntercepted(
        request: Request,
        span: DatadogSpan,
        response: Response?,
        throwable: Throwable?
    ) {
        span.setTag("request.method", request.method)
    }
}

Mettez à jour les samplers personnalisés de Sampler<io.opentracing.Span> à Sampler<DatadogSpan>.

9. Migrer Session Replay

SessionReplayConfiguration.Builder.useCustomEndpoint doit recevoir l'URL d'upload Session Replay complète :

SessionReplay.enable(
    SessionReplayConfiguration.Builder(...)
        .useCustomEndpoint("https://example.com/session_replay/upload")
        .build()
)

Préservez la configuration de confidentialité et d'échantillonnage existante de Session Replay de l'application.

10. Vérifier le résultat

Exécutez la tâche de compilation Gradle normale du projet. Préférez la même commande de compilation utilisée par le CI du projet.

Avant de terminer, confirmez :

• tous les artefacts com.datadoghq:dd-sdk-android-* résolus sont sur une seule version stable 3.x ;
• minSdk est au moins 23 et Kotlin est au moins 1.9 ;
• aucune dépendance ou import io.opentracing n'existe ;
• chaque ID utilisateur est non-null ;
• les ressources RUM manuelles utilisent RumResourceMethod ;
• l'accès RUM global utilise GlobalRumMonitor.get() ;
• chaque endpoint personnalisé est une URL d'upload complète spécifique au produit ;
• chaque produit Datadog précédemment activé reste activé ;
• les intercepteurs OkHttp migrés préservent leur configuration précédente ;
• la compilation Gradle se termine avec succès.

Corrigez uniquement les échecs liés à la migration. Ne réécrivez pas le code d'application non lié ou ne supprimez pas d'instrumentation pour obtenir une compilation réussie.

Signalez les versions du SDK d'origine et résultantes, le chemin de migration choisi pour le tracing, les fichiers modifiés et la commande de compilation Gradle exacte qui a réussi.