Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

Obtenez des rapports de plantage Android NDK

Si votre application Android contient des bibliothèques natives , vous pouvez activer des traces de pile complètes et des rapports de plantage détaillés pour votre code natif à partir de Firebase Crashlytics avec quelques petites mises à jour de la configuration de build de votre application. Ce guide explique comment configurer les rapports de plantage avec le nouveau SDK Firebase Crashlytics.

Avant que tu commences

  1. Pour commencer, configurez Crashlytics .

  2. Dans le cadre de l' étape 2 (Ajouter Firebase Crashlytics à votre application) , assurez-vous que votre application utilise le plug-in Crashlytics Gradle v2.4.0+, qui vous permet de télécharger des symboles en utilisant uniquement vos fichiers binaires non supprimés pour générer des plantages symboliques.

Étape 1 : Mettez à jour votre configuration Gradle

Dans votre build.gradle niveau de l' build.gradle , déclarez la dépendance d'exécution Crashlytics NDK :

Java

apply plugin: 'com.android.application'
apply plugin: 'com.google.firebase.crashlytics'

dependencies {
  // ...

  // Import the BoM for the Firebase platform
  implementation platform('com.google.firebase:firebase-bom:28.1.0')

  // Declare the dependency for the Firebase Crashlytics NDK library.
  // If you previously declared the Firebase Crashlytics dependency, replace it.
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation 'com.google.firebase:firebase-crashlytics'
  implementation 'com.google.firebase:firebase-crashlytics-ndk'
  implementation 'com.google.firebase:firebase-analytics'
}

// …
android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Crashlytics servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

En utilisant Firebase Android BoM , votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.

(Alternative) Déclarer les dépendances de la bibliothèque Firebase sans utiliser la nomenclature

Si vous choisissez de ne pas utiliser la nomenclature de Firebase, vous devez spécifier chaque version de la bibliothèque Firebase dans sa ligne de dépendance.

Notez que si vous utilisez plusieurs bibliothèques Firebase dans votre application, nous vous recommandons fortement d'utiliser la nomenclature pour gérer les versions de la bibliothèque, ce qui garantit que toutes les versions sont compatibles.

  dependencies {
      // Declare the dependency for the Firebase Crashlytics NDK library.
      // If you previously declared the Firebase Crashlytics dependency, replace it.
      // When NOT using the BoM, you must specify versions in Firebase library dependencies
      implementation 'com.google.firebase:firebase-crashlytics:18.0.1'
      implementation 'com.google.firebase:firebase-crashlytics-ndk:18.0.1'
      implementation 'com.google.firebase:firebase-analytics:19.0.0'
  }
  

Kotlin+KTX

apply plugin: 'com.android.application'
apply plugin: 'com.google.firebase.crashlytics'

dependencies {
  // ...

  // Import the BoM for the Firebase platform
  implementation platform('com.google.firebase:firebase-bom:28.1.0')

  // Declare the dependency for the Firebase Crashlytics NDK library.
  // If you previously declared the Firebase Crashlytics dependency, replace it.
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation 'com.google.firebase:firebase-crashlytics-ktx'
  implementation 'com.google.firebase:firebase-crashlytics-ndk'
  implementation 'com.google.firebase:firebase-analytics-ktx'
}

// …
android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Crashlytics servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

En utilisant Firebase Android BoM , votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.

(Alternative) Déclarer les dépendances de la bibliothèque Firebase sans utiliser la nomenclature

Si vous choisissez de ne pas utiliser la nomenclature de Firebase, vous devez spécifier chaque version de la bibliothèque Firebase dans sa ligne de dépendance.

Notez que si vous utilisez plusieurs bibliothèques Firebase dans votre application, nous vous recommandons fortement d'utiliser la nomenclature pour gérer les versions de la bibliothèque, ce qui garantit que toutes les versions sont compatibles.

  dependencies {
      // Declare the dependency for the Firebase Crashlytics NDK library.
      // If you previously declared the Firebase Crashlytics dependency, replace it.
      // When NOT using the BoM, you must specify versions in Firebase library dependencies
      implementation 'com.google.firebase:firebase-crashlytics-ktx:18.0.1'
      implementation 'com.google.firebase:firebase-crashlytics-ndk:18.0.1'
      implementation 'com.google.firebase:firebase-analytics-ktx:19.0.0'
  }
  

Requis pour Crashlytics NDK version 17.3.0 : si votre application utilise targetSdkLevel 30 ou supérieur, vous devez également désactiver la fonctionnalité Pointer Tagging dans votre application en ajoutant ce qui suit à votre AndroidManifest.xml :

<application android:allowNativeHeapPointerTagging="false">
...
</application>

Pour plus d'informations, lisez Prise en charge par les développeurs des pointeurs marqués .

Étape 2 : Activer le téléchargement de symboles natifs

Pour produire des traces de pile lisibles à partir des plantages de NDK, Crashlytics doit connaître les symboles de vos binaires natifs. Notre plugin Gradle inclut la tâche uploadCrashlyticsSymbolFile BUILD_VARIANT pour automatiser ce processus (pour accéder à cette tâche, assurez-vous que nativeSymbolUploadEnabled est défini sur true).

Pour que les noms de méthode apparaissent dans vos traces de pile, vous devez appeler explicitement la tâche uploadCrashlyticsSymbolFile BUILD_VARIANT après chaque build de votre bibliothèque NDK. Par example:

>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

Le Crashlytics NDK v17.3.0+ et le plugin Gradle v2.4.1+ dépendent de la présence de l'identifiant de build GNU dans les objets partagés natifs. Vous pouvez vérifier la présence de cet identifiant en exécutant readelf -n sur chaque binaire. Si l'identifiant de build est absent, ajoutez -Wl,--build-id aux indicateurs de votre système de build pour résoudre le problème.

Étape 3 (facultatif) : Télécharger des symboles pour les dépendances externes

Notre tâche de téléchargement de symboles suppose que vous construisez vos bibliothèques natives dans le cadre de votre build Gradle, en utilisant des outils de build NDK standard tels que CMake. Si vous disposez de bibliothèques natives construites en externe ou si vous utilisez un processus de construction NDK personnalisé dans Gradle, vous devrez peut-être spécifier explicitement le chemin d'accès à vos bibliothèques non supprimées. L'extension firebaseCrashlytics fournit la propriété unstrippedNativeLibsDir pour ce faire.

Ajoutez les éléments suivants à votre fichier build.gradle niveau de l' build.gradle :

// …
android {
    // ...
    buildTypes {
        release {
            firebaseCrashlytics {
                nativeSymbolUploadEnabled true
                unstrippedNativeLibsDir file("path/to/unstripped/dir")
            }
        }
    }
}

Le plugin Crashlytics recherchera dans le répertoire spécifié et tous ses sous-répertoires les bibliothèques natives avec une extension .so . Crashlytics extraira ensuite les symboles de débogage de toutes ces bibliothèques et les téléchargera sur les serveurs Firebase.

La propriété unstrippedNativeLibsDir accepte tous les arguments autorisés pour org.gradle.api.Project#files(Object...) , y compris java.lang.String , java.io.File et org.gradle.api.file.FileCollection . Vous pouvez spécifier plusieurs répertoires pour une seule version de build en fournissant une liste ou une instance FileCollection .

Étape 4 (facultatif) : Personnaliser les rapports d'erreur NDK

Vous pouvez éventuellement inclure l'en crashlytics.h tête crashlytics.h dans votre code C++ pour ajouter des métadonnées aux rapports d'incident NDK, telles que les journaux, les clés personnalisées et les ID utilisateur. crashlytics.h est disponible en tant que bibliothèque C++ d'en-tête uniquement dans le référentiel GitHub du SDK Android Firebase . Lisez les commentaires dans le fichier d'en-tête pour obtenir des instructions sur l'utilisation des API NDK C++.

Étape 5 (facultatif) : Activez le fichier de symboles Breakpad pour la symbolisation

Le plug-in Crashlytics Gradle fournit les fonctionnalités suivantes :

  • Traite vos binaires natifs non extraits pour générer des fichiers de symboles.
  • Télécharge les fichiers de symboles générés sur nos serveurs pour être utilisés plus tard lors de la symbolisation des plantages natifs.

Le plugin Crashlytics Gradle prend en charge deux types de formats de fichiers de symboles :
le fichier de symboles Crashlytics (cSYM) et le fichier de symboles Breakpad .

Un fichier de symboles généré par Breakpad contient plus d'informations qu'un fichier de symboles généré par Crashlytics, y compris les informations de trame d'appel (CFI) qui sont utilisées dans le processus de déroulement pour aider à calculer les trames de pile. L'utilisation de CFI se traduira par des traces de pile plus fidèles, en particulier pour les applications hautement optimisées telles que les jeux et les applications multimédias.

Vous pouvez activer l'utilisation du générateur de fichiers de symboles basé sur Breakpad de l'une des deux manières suivantes :

  • Option 1 : Activer via l'extension firebaseCrashlytics dans votre fichier build.gradle

    Ajoutez les éléments suivants à votre fichier build.gradle niveau de l' build.gradle :

    android {
      // ...
      buildTypes {
        // ...
        release {
          // ...
          firebaseCrashlytics {
            // existing; required for either symbol file generator
            nativeSymbolUploadEnabled true
            // Add this optional new block to specify breakpad() or csym()
            symbolGenerator {
               breakpad()
            }
          }
        }
      }
    }
    

    Pour revenir au générateur de fichiers de symboles Crashlytics par défaut, vous pouvez effectuer l'une des opérations suivantes :

    • symbolGenerator entièrement le bloc symbolGenerator , car le plugin utilise le générateur de fichiers de symboles Crashlytics par défaut.

    • Conservez le bloc, mais changez breakpad() en csym() .

  • Option 2 : Activer via une ligne de propriété dans votre fichier de propriétés Gradle

    Vous pouvez utiliser la propriété com.google.firebase.crashlytics.symbolGenerator pour contrôler le générateur de fichiers de symboles à utiliser. Les valeurs valides pour la propriété sont breakpad ou csym . Si non spécifié, la valeur par défaut actuelle est équivalente à csym , bien que cela puisse changer dans les versions futures.

    Vous pouvez mettre à jour manuellement votre fichier de propriétés Gradle ou mettre à jour le fichier via la ligne de commande. Par exemple, pour activer le générateur de fichier de symboles Breakpad, spécifiez la valeur de breakpad comme indiqué dans la commande suivante :

    ./gradlew -Pcom.google.firebase.crashlytics.symbolGenerator=breakpad \
    app:assembleRelease app:uploadCrashlyticsSymbolFileRelease
    

Étape 6 : Consultez vos rapports de plantage

Vérifiez que Crashlytics signale correctement les plantages NDK en créant votre application, en téléchargeant des symboles et en forçant un plantage natif. Vous devrez redémarrer l'application après son blocage pour que Crashlytics envoie le rapport. Vous devriez voir le plantage dans votre console Firebase en quelques minutes.

Dépannage

Si vous voyez des traces de pile différentes dans la console Firebase et dans le logcat, reportez-vous au guide de dépannage .