Collecte de logs Android
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Collecte de logs Android

Envoyez des logs à Datadog à partir de vos applications Android avec la bibliothèque de logging côté client dd-sdk-android de Datadog. Vous pourrez notamment :

  • Envoyer des logs vers Datadog au format JSON en natif
  • Ajouter du contexte et des attributs personnalisés supplémentaires pour chaque log envoyé
  • Transmettre les exceptions Java/Kotlin interceptées
  • Enregistrer les adresses IP et user agents réels du client
  • Optimiser l’utilisation du réseau grâce aux envois groupés automatiques

Remarque : la bibliothèque dd-sdk-android prend en charge toutes les versions d’Android à partir du niveau d’API 19 (KitKat).

Configuration

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

    repositories {
        maven { url "https://dl.bintray.com/datadog/datadog-maven" }
    }
    
    dependencies {
        implementation "com.datadoghq:dd-sdk-android:x.x.x"
    }
  2. Initialisez la bibliothèque avec le contexte de votre application et votre token client Datadog. Pour des raisons de sécurité, vous devez utiliser un token client : vous ne pouvez pas utiliser les clés d’API Datadog pour configurer la bibliothèque dd-sdk-android, car elles risqueraient d’être exposées côté client dans le bytecode de l’APK de l’application Android. Pour en savoir plus sur la configuration d’un token client, consultez la documentation dédiée :

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
    
            val config = DatadogConfig.Builder("<TOKEN_CLIENT>", "<NOM_ENVIRONNEMENT>", "<ID_APPLICATION>")
                            .build()
            Datadog.initialize(this, config)
        }
    }
    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
    
            val config = DatadogConfig.Builder("<TOKEN_CLIENT>", "<NOM_ENVIRONNEMENT>", "<ID_APPLICATION>")
                            .useEUEndpoints()
                            .build()
            Datadog.initialize(this, config)
        }
    }

    Une méthode utilitaire est également disponible pour obtenir le statut actuel du SDK. Vous pouvez vous en servir afin de vérifier si l’initialisation a été correctement effectuée ou non :

        if(Datadog.isInitialized()){
          // votre code ici
        }

    Lors de la création de votre application, vous pouvez activer les logs de développement. Tous les messages internes dans la bibliothèque dont la priorité est égale ou supérieure au niveau spécifié sont alors enregistrés dans le Logcat d’Android.

        Datadog.setVerbosity(Log.INFO)
  3. Configurer le logger Android :

    val logger = Logger.Builder()
        .setNetworkInfoEnabled(true)
        .setLogcatLogsEnabled(true)
        .setDatadogLogsEnabled(true)
        .setBundleWithTraceEnabled(true)
        .setLoggerName("<LOGGER_NAME>")
        .build();
  4. Envoyez une entrée de log personnalisée directement à Datadog avec l’une des fonctions suivantes :

    logger.d("A debug message.")
    logger.i("Some relevant information ?")
    logger.w("An important warning…")
    logger.e("An error was met!")
    logger.wtf("What a Terrible Failure!")

    Les exceptions interceptées peuvent être envoyées avec un message :

    try {
        doSomething()
    } catch (e : IOException) {
        logger.e("Error while doing something", e)
    }

    Remarque : toutes les méthodes de logging peuvent avoir un Throwable qui leur est associé.

  5. (Facultatif) - Fournissez une map avec votre message de log pour ajouter des attributs au log envoyé. Chaque entrée de la map est ajoutée en tant qu’attribut.

    logger.i("onPageStarted", attributes = mapOf("http.url", url))

    En Java, cela donnerait :

    Logger.d(
            "onPageStarted",
            null,
            new HashMap<String, Object>() {{
                put("http.url", url);
            }}
    );

Logging avancé

Initialisation

Les méthodes suivantes dans Logger.Builder peuvent être utilisées lors de l’initialisation du logger afin d’envoyer des logs à Datadog :

MéthodeDescription
setNetworkInfoEnabled(true)Ajouter l’attribut network.client.connectivity à tous les logs. Les données enregistrées par défaut sont connectivity (Wifi, 3G, 4G, etc.) et carrier_name (AT&T - US). carrier_name est seulement disponible à partir du niveau d’API 28 d’Android.
setServiceName(<NOM_SERVICE>)Définir <NOM_SERVICE> en tant que valeur pour l’attribut standard service joint à tous les logs envoyés à Datadog.
setLogcatLogsEnabled(true)Définir ce paramètre sur true pour utiliser Logcat en tant que logger.
setDatadogLogsEnabled(true)Définir ce paramètre sur true pour envoyer les logs à Datadog.
setBundleWithTraceEnabled(true)Définir sur true (valeur par défaut) pour associer les logs à la trace active dans votre application. Ce paramètre permet de visualiser tous les logs envoyés lors d’une trace spécifique depuis le dashboard Datadog.
setLoggerName(<NOM_LOGGER>)Définir <NOM_LOGGER> en tant que valeur pour l’attribut logger.name joint à tous les logs envoyés à Datadog.
setVerbosity(Log.INFO)Définir le niveau de détail du logger. Tous les messages internes dans la bibliothèque dont la priorité est égale ou supérieure au niveau spécifié sont enregistrés dans le Logcat d’Android.
setSampleRate(<TAUX_ÉCHANTILLONNAGE>)Définir le taux d’échantillonnage de ce logger. Tous les logs générés par l’instance du logger sont échantillonnés de manière aléatoire selon le taux d’échantillonnage fourni (par défaut 1.0 = tous les logs). Remarque : les logs Logcat ne sont pas échantillonnés.
build()Créer une instance de logger avec toutes les options définies.

Configuration globale

Vous trouverez ci-dessous les fonctions pour ajouter/supprimer des tags et des attributs de tous les logs envoyés par un logger donné.

Tags globaux

Ajouter des tags

Utilisez la fonction addTag("<CLÉ_TAG>","<VALEUR_TAG>") pour ajouter des tags à tous les logs envoyés par un logger spécifique :

// Ajouter un tag build_type:debug ou build_type:release
logger.addTag("build_type", BuildConfig.BUILD_TYPE)

// Ajouter un tag device:android
logger.addTag("device", "android")

Remarque : <VALEUR_TAG> doit être une chaîne.

Supprimer des tags

Utilisez la fonction removeTagsWithKey("<CLÉ_TAG>") pour supprimer des tags de tous les logs envoyés par un logger spécifique :

// Supprimer tous les tags commençant par build_type
logger.removeTagsWithKey("build_type")

En savoir plus sur les tags Datadog.

Attributs globaux

Ajouter des attributs

Par défaut, les attributs suivants sont ajoutés à tous les logs envoyés par un logger :

  • http.useragent et ses propriétés extraites device et OS
  • network.client.ip et ses propriétés géographiques extraites (country, city)

Utilisez la fonction addAttribute("<CLÉ_ATTRIBUT>", "<VALEUR_ATTRIBUT>") pour ajouter un attribut personnalisé à tous les logs envoyés par un logger spécifique :

// Ajouter un attribut version_code avec un entier comme valeur
logger.addAttribute("version_code", BuildConfig.VERSION_CODE)

// Ajouter un attribut version_name avec une chaîne comme valeur
logger.addAttribute("version_name", BuildConfig.VERSION_NAME)

Remarque : <VALEUR_ATTRIBUT> peut être une date ou une chaîne primitive.

Supprimer des attributs

Utilisez la fonction removeAttribute("<CLÉ_ATTRIBUT>", "<VALEUR_ATTRIBUT>") pour supprimer un attribut personnalisé de tous les logs envoyés par un logger spécifique :

// Supprimer l'attribut version_code de tous les prochains logs envoyés.
logger.removeAttribute("version_code")

// Supprimer l'attribut version_name de tous les prochains logs envoyés.
logger.removeAttribute("version_name")

Collecte groupée des logs

Tous les logs sont d’abord stockés sur l’appareil local sous forme groupée. Chaque groupe de logs respecte les spécifications d’admission. Ils sont envoyés dès que le réseau est disponible, et dès que la batterie est suffisamment élevée pour que le SDK Datadog n’affecte pas l’expérience de l’utilisateur final. Si le réseau n’est pas disponible alors que votre application s’exécute au premier plan, ou si l’envoi des données échoue, le groupe de logs est conservé jusqu’à ce qu’il puisse être envoyé.

Cela signifie que même si les utilisateurs ouvrent votre application en étant hors ligne, aucune donnée ne sera perdue.

Les données stockées sont automatiquement supprimées si elles sont trop anciennes pour limiter l’espace utilisé par le SDK.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles: