Aperçu

Le suivi des erreurs Android Error Tracking vous offre une visibilité complète sur la santé de votre application mobile en capturant automatiquement les plantages, les exceptions et les erreurs. Avec cette fonctionnalité, vous pouvez :

• Surveiller la stabilité de l’application en temps réel avec des alertes instantanées de plantage et un suivi du taux d’erreur à travers les versions, les appareils et les segments d’utilisateurs.
• Déboguez les problèmes plus rapidement avec des traces de pile déobfusquées et des téléchargements automatiques de fichiers de mappage ProGuard pour une identification plus facile des problèmes.
• Améliorez la qualité de l’application en identifiant les fonctionnalités sujettes aux plantages, en suivant les tendances des erreurs et en priorisant les corrections pour une meilleure satisfaction des utilisateurs.
• Accédez aux tableaux de bord de plantage Android agrégés et aux attributs.
• Consultez les rapports de plantage Android déobfusqués avec analyse des tendances.

Le SDK Android de Datadog prend en charge Android 5.0+ (niveau API 21) et Android TV.

Vos rapports de plantage apparaissent dans Suivi des erreurs.

Configuration

Si vous n’avez pas encore configuré le SDK Android, suivez les instructions de configuration dans l’application ou consultez la documentation de configuration Android.

Étape 1 - Déclarez le SDK Android comme une dépendance

Déclarez dd-sdk-android-rum et le plugin Gradle comme dépendances dans votre fichier de module d’application build.gradle :

buildscript {
    dependencies {
        classpath("com.datadoghq:dd-sdk-android-gradle-plugin:x.x.x")
    }
}
plugins {
    id("com.datadoghq.dd-sdk-android-gradle-plugin")
    //(...)
}
android {
    //(...)
}
dependencies {
    implementation "com.datadoghq:dd-sdk-android-rum:x.x.x" 
    //(...)
}

Étape 2 - Spécifiez les détails de l’application dans l’interface utilisateur

1. Accédez à Erreurs > Paramètres > Navigateur et Mobile > + Nouvelle Application.
2. Sélectionnez android comme type d’application et entrez un nom d’application pour générer un ID d’application Datadog unique et un jeton client.
3. Cliquez sur Créer une Application.

Étape 3 - Initialisez le SDK Datadog avec le contexte de l’application

Mettez à jour le fragment d’initialisation

Dans le fragment d’initialisation, définissez un nom d’environnement, un nom de service et un numéro de version. Dans les exemples ci-dessous, APP_VARIANT_NAME spécifie la variante de l’application qui génère des données. Pour plus d’informations, consultez Utilisation des Tags.

Lors de l’initialisation, vous pouvez également définir le taux d’échantillonnage (sessions RUM) et définir le consentement au suivi pour la conformité au RGPD, comme décrit ci-dessous. Consultez d’autres options de configuration pour initialiser la bibliothèque.

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
            clientToken = <CLIENT_TOKEN>,
            env = <ENV_NAME>,
            variant = <APP_VARIANT_NAME>
        ).build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
                clientToken = <CLIENT_TOKEN>,
                env = <ENV_NAME>,
                variant = <APP_VARIANT_NAME>
            )
            .useSite(DatadogSite.EU1)
            .build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .useSite(DatadogSite.EU1)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
                clientToken = <CLIENT_TOKEN>,
                env = <ENV_NAME>,
                variant = <APP_VARIANT_NAME>
            )
            .useSite(DatadogSite.US3)
            .build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .useSite(DatadogSite.US3)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
                clientToken = <CLIENT_TOKEN>,
                env = <ENV_NAME>,
                variant = <APP_VARIANT_NAME>
            )
            .useSite(DatadogSite.US5)
            .build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .useSite(DatadogSite.US5)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
                clientToken = <CLIENT_TOKEN>,
                env = <ENV_NAME>,
                variant = <APP_VARIANT_NAME>
            )
            .useSite(DatadogSite.US1_FED)
            .build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .useSite(DatadogSite.US1_FED)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
                clientToken = <CLIENT_TOKEN>,
                env = <ENV_NAME>,
                variant = <APP_VARIANT_NAME>
            )
            .useSite(DatadogSite.AP1)
            .build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .useSite(DatadogSite.AP1)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val configuration = Configuration.Builder(
                clientToken = <CLIENT_TOKEN>,
                env = <ENV_NAME>,
                variant = <APP_VARIANT_NAME>
            )
            .useSite(DatadogSite.AP2)
            .build()
        Datadog.initialize(this, configuration, trackingConsent)
    }
}

public class SampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Configuration configuration =
                new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
                        .useSite(DatadogSite.AP2)
                        .build();
        Datadog.initialize(this, configuration, trackingConsent);
    }
}

Les informations d’initialisation nécessitent le nom de variante de votre application et utilisent la valeur de BuildConfig.FLAVOR. Avec la variante, le SDK peut faire correspondre les erreurs signalées par votre application aux fichiers de mappage téléchargés par le plugin Gradle. Si vous n’avez pas de variantes, les informations d’identification utilisent une chaîne vide.

Le plugin Gradle télécharge automatiquement le fichier ProGuard approprié mapping.txt au moment de la construction afin que vous puissiez consulter les traces de pile d’erreurs déobfusquées. Pour plus d’informations, consultez la section Téléchargez votre fichier de mappage.

Activez la fonctionnalité pour commencer à envoyer des données

Pour activer le SDK Android afin de commencer à envoyer des données :

val rumConfig = RumConfiguration.Builder(applicationId)
    .trackUserInteractions()
    .trackLongTasks(durationThreshold) // Not applicable to Error Tracking
    .useViewTrackingStrategy(strategy)
    .build()
Rum.enable(rumConfig)

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .trackUserInteractions()
    .trackLongTasks(durationThreshold) // Not applicable to Error Tracking
    .useViewTrackingStrategy(strategy)
    .build();
Rum.enable(rumConfig);

Voir ViewTrackingStrategy pour activer le suivi automatique de toutes vos vues (activités, fragments, et plus).

Instrumentez vos webviews (optionnel)

Si votre application Android utilise des WebViews pour afficher du contenu web, vous pouvez les instrumenter pour suivre les erreurs JavaScript et les plantages qui se produisent dans le contenu web.

Pour instrumenter vos web views :

1. Ajoutez la dépendance Gradle en déclarant dd-sdk-android-webview comme dépendance dans votre fichier build.gradle :

   dependencies {
    implementation "com.datadoghq:dd-sdk-android-webview:<latest_version>"
   }
   

2. Activez le suivi des webviews pour une instance WebView donnée en fournissant une liste d’hôtes à suivre :

   WebViewTracking.enable(webView, hosts)
   

Pour plus d’informations, consultez Suivi des Web Views.

Étape 4 - Ajoutez le rapport de plantage NDK

Si votre application Android utilise du code natif (C/C++) via l’Android NDK (Native Development Kit), vous pouvez suivre les plantages qui se produisent dans ce code natif. Le code natif est souvent utilisé pour des opérations critiques en termes de performance, le traitement d’images, ou lors de la réutilisation de bibliothèques C/C++ existantes.

Sans le rapport de plantage NDK, les plantages dans votre code natif n’apparaissent pas dans le suivi des erreurs, ce qui rend difficile le débogage des problèmes dans cette partie de votre application.

Pour activer le rapport de plantage NDK, utilisez le plugin Datadog NDK :

1. Ajoutez la dépendance Gradle en déclarant la bibliothèque comme dépendance dans votre build.gradle fichier :

    dependencies {
        implementation("com.datadoghq:dd-sdk-android-ndk:x.x.x")
        //(...)
    }
   

2. Activez la collecte de plantages NDK après avoir initialisé le SDK :

   NdkCrashReports.enable()
   

Étape 5 - Ajoutez le rapport ANR

Un “Application Not Responding” (ANR) est un type d’erreur spécifique à Android qui se déclenche lorsque l’application ne répond pas pendant trop longtemps. Vous pouvez ajouter le rapport ANR à votre configuration RUM pour surveiller ces problèmes de réactivité de l’application.

Pour activer le rapport ANR, ajoutez ce qui suit à votre configuration RUM :

val rumConfig = RumConfiguration.Builder(applicationId)
    .trackUserInteractions()
    .trackLongTasks(durationThreshold)
    .trackNonFatalAnrs(true) // Enable non-fatal ANR reporting
    .useViewTrackingStrategy(strategy)
    .build()
Rum.enable(rumConfig)

RumConfiguration rumConfig = new RumConfiguration.Builder(applicationId)
    .trackUserInteractions()
    .trackLongTasks(durationThreshold)
    .trackNonFatalAnrs(true) // Enable non-fatal ANR reporting
    .useViewTrackingStrategy(strategy)
    .build();
Rum.enable(rumConfig);

Les ANR ne sont signalés que par le biais du SDK (pas par les journaux).

Signalement des ANR fatals

Les ANR fatals entraînent des plantages. L’application les signale lorsqu’elle est non réactive, ce qui amène le système d’exploitation Android à afficher une boîte de dialogue contextuelle à l’utilisateur, qui choisit de forcer la fermeture de l’application via la boîte de dialogue.

• Dans la page Suivi des erreurs, les ANR fatals sont regroupés en fonction de leur similarité, ce qui peut entraîner la création de plusieurs problèmes individuels.
• Par défaut, Datadog capture les ANR fatals via l’API ApplicationExitInfo (disponible depuis Android 30+), qui peut être lue lors du prochain lancement de l’application.
• Dans Android 29 et en dessous, le rapport sur les ANR fatals n’est pas possible.

Signalement des ANR non fatals

Les ANR non fatals peuvent ou non avoir conduit à la terminaison de l’application (plantage).

• Dans la page Suivi des erreurs, les ANRs non fatals sont regroupés sous un unique problème en raison de leur niveau de bruit.
• Par défaut, le rapport des ANRs non fatals sur Android 30+ est désactivé car cela créerait trop de bruit par rapport aux ANRs fatals. Sur Android 29 et en dessous, cependant, le rapport des ANRs non fatals est activé par défaut, car les ANRs fatals ne peuvent pas être rapportés sur ces versions.

Pour toute version d’Android, vous pouvez remplacer le paramètre par défaut pour le rapport des ANRs non fatals en définissant trackNonFatalAnrs sur true ou false lors de l’initialisation du SDK.

Étape 6 - Obtenir des traces de pile déobfusquées

Lorsque votre application Android est construite pour la production, le code est généralement obfusqué à l’aide de ProGuard ou R8 pour réduire la taille de l’application et protéger la propriété intellectuelle. Cette obfuscation rend les traces de pile dans les rapports de plantage illisibles, montrant des noms de classes et de méthodes sans signification comme a.b.c() au lieu de com.example.MyClass.myMethod().

Pour rendre ces traces de pile lisibles pour le débogage, vous devez télécharger vos fichiers de mappage sur Datadog. Ces fichiers contiennent le mappage entre le code obfusqué et le code original, permettant à Datadog de déobfusquer automatiquement les traces de pile dans vos rapports d’erreurs.

Comment cela fonctionne

Datadog utilise un identifiant de build unique généré pour chaque build afin d’associer automatiquement les traces de pile avec les fichiers de mappage corrects. Cela garantit que :

• Les traces de pile sont toujours déobfusquées avec le fichier de mappage correct, peu importe quand il a été téléchargé.
• Vous pouvez télécharger des fichiers de mappage lors des constructions de pré-production ou de production.
• Le processus fonctionne de manière transparente à travers différentes variantes de construction et environnements.

Le processus de correspondance dépend de votre version du plugin Gradle Android :

• Versions 1.13.0 et supérieures : Utilise le champ build_id (nécessite le SDK Android Datadog 2.8.0 ou version ultérieure)
• Versions antérieures : Utilise une combinaison des champs service, version et variant

Téléchargez votre fichier de mappage

Le plugin Gradle Android automatise le processus de téléchargement du fichier de mappage. Après configuration, il téléverse automatiquement le fichier de mappage ProGuard/R8 approprié pour chaque variante de build lorsque vous construisez votre application.

Remarque : Le téléversement d’un fichier de mappage ne remplace pas le fichier existant si la version n’a pas changé. Pour obtenir des informations sur les limitations de taille de fichier et d’autres contraintes, consultez la section Limitations.

Exécutez les tâches de téléversement

Après avoir configuré le plugin, exécutez les tâches Gradle pour téléverser votre fichier de mappage Proguard/R8 et les fichiers de symboles NDK vers Datadog :

./gradlew uploadMappingRelease
./gradlew uploadNdkSymbolFilesRelease

Pour toute erreur donnée, vous pouvez accéder au chemin du fichier, au numéro de ligne et à un extrait de code pour chaque trame de la trace d’appel associée.

Liste des fichiers de mappage téléversés

Consultez la page Symboles de débogage RUM pour voir tous les symboles téléversés.

Fonctionnalités avancées de suivi des erreurs

val rumConfig = RumConfiguration.Builder(applicationId)
        // Here 75% of the RUM sessions are sent to Datadog
        .setSessionSampleRate(75.0f)
        .build()
Rum.enable(rumConfig)

val tracedHostsWithHeaderType = mapOf(
    "example.com" to setOf(
        TracingHeaderType.DATADOG,
        TracingHeaderType.TRACECONTEXT),
    "example.eu" to setOf(
        TracingHeaderType.DATADOG,
        TracingHeaderType.TRACECONTEXT))
val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
    .build()

Map<String, Set<TracingHeaderType>> tracedHostsWithHeaderType = new HashMap<>();
Set<TracingHeaderType> datadogAndW3HeadersTypes = new HashSet<>(Arrays.asList(TracingHeaderType.DATADOG, TracingHeaderType.TRACECONTEXT));
tracedHostsWithHeaderType.put("example.com", datadogAndW3HeadersTypes);
tracedHostsWithHeaderType.put("example.eu", datadogAndW3HeadersTypes);
OkHttpClient okHttpClient = new OkHttpClient.Builder()
    .addInterceptor(new DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
    .build();

val okHttpClient = OkHttpClient.Builder()
    .addNetworkInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
    .build()

OkHttpClient okHttpClient = new OkHttpClient.Builder()
    .addNetworkInterceptor(new DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
    .build();

.trackBackgroundEvents(true)

.trackBackgroundEvents(true)

datadog {
    foo {
        versionName = "foo"
    }
    bar {
        versionName = "bar"
    }
    fooBar {
        versionName = "fooBar"
    }
}

tasks["minify${variant}WithR8"].finalizedBy { tasks["uploadMapping${variant}"] }

Limitations

Taille des fichiers

Les fichiers de mappage sont limités en taille à 500 MB chacun. Si votre projet a un fichier de mappage plus grand que cette limite, utilisez l’une des options suivantes pour réduire la taille du fichier :

• Définissez l’option mappingFileTrimIndents sur true. Cela réduit la taille de votre fichier de 5 %, en moyenne.
• Définissez une table de correspondance de mappingFilePackagesAliases : Cela remplace les noms de packages par des alias plus courts. Remarque : La trace de pile de Datadog utilise le même alias au lieu du nom de package original, il est donc préférable d’utiliser cette option pour les dépendances tierces.

datadog {
    mappingFileTrimIndents = true
    mappingFilePackageAliases = mapOf(
        "kotlinx.coroutines" to "kx.cor",
        "com.google.android.material" to "material",
        "com.google.gson" to "gson",
        "com.squareup.picasso" to "picasso"
    )
}

Collection

Lors de l’examen des comportements de rapport de crash RUM pour Android, tenez compte des éléments suivants :

• Le crash ne peut être détecté qu’après l’initialisation du SDK. Dans ce contexte, la recommandation est d’initialiser le SDK dès que possible dans la méthode onCreate de votre application.
• Les plantages RUM doivent être associés à une vue RUM. Si un crash survient avant qu’une vue ne soit visible (typiquement une Activité ou un Fragment dans un état onResume), ou après que l’application a été mise en arrière-plan par l’utilisateur final en quittant l’application, le crash est atténué et n’est pas signalé pour la collecte. Pour atténuer cela, utilisez la méthode trackBackgroundEvents() méthode dans votre constructeur RumConfiguration.
• Seuls les plantages qui se produisent dans des sessions échantillonnées sont conservés. Si un taux d’échantillonnage de session n’est pas de 100 %, certains plantages ne sont pas signalés.

Testez votre implémentation

Pour vérifier votre configuration de rapport de crash Android et de suivi des erreurs, vous devez déclencher un crash dans votre application et confirmer que l’erreur apparaît dans Datadog.

Pour tester votre implémentation :

1. Exécutez votre application sur un émulateur Android ou un appareil réel.

2. Exécutez du code contenant une erreur ou un crash. Par exemple :

   fun onEvent() {
       throw RuntimeException("Crash the app")
   }
   

3. Après que le crash se soit produit, redémarrez votre application et attendez que le SDK Android télécharge le rapport de crash dans Suivi des erreurs.

Extensions Kotlin

Closeable extension

Vous pouvez surveiller l’utilisation de l’instance Closeable avec la méthode useMonitored, qui signale les erreurs à Datadog et ferme la ressource par la suite :

val closeable: Closeable = ...
closeable.useMonitored {
    // Your code here
}

Suivez les assets locaux en tant que ressources

Vous pouvez suivre l’accès aux assets en utilisant la méthode d’extension getAssetAsRumResource :

val inputStream = context.getAssetAsRumResource(fileName)

L’utilisation des assets locaux peut être suivie en utilisant la méthode d’extension getRawResAsRumResource :

val inputStream = context.getRawResAsRumResource(id)

Pour en savoir plus

Documentation, liens et articles supplémentaires utiles:

Suivi des erreurs frontendDOCUMENTATION Code source pour dd-sdk-androidSOURCE CODE Commencez avec le suivi des erreursDOCUMENTATION Visualisez les données de suivi des erreurs dans l'ExplorateurDOCUMENTATION