Google is committed to advancing racial equity for Black communities. See how.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

Personnalisez vos rapports d'incidents Firebase Crashlytics

Ce guide décrit comment personnaliser vos rapports d'erreur à l'aide du SDK Firebase Crashlytics. Par défaut, Crashlytics collecte automatiquement les rapports d'erreur pour tous les utilisateurs de votre application (vous pouvez désactiver le rapport automatique des pannes et activer le rapport opt-in pour vos utilisateurs à la place). Crashlytics fournit quatre mécanismes de journalisation prêts à l'emploi: des clés personnalisées , des journaux personnalisés , des identifiants d'utilisateur et des exceptions interceptées .

Ajouter des clés personnalisées

Les clés personnalisées vous aident à connaître l'état spécifique de votre application menant à un plantage. Vous pouvez associer des paires clé / valeur arbitraires à vos rapports de plantage et les afficher dans la console Firebase .

Utilisez la méthode setCustomValue pour définir des paires clé / valeur. Par exemple:

Rapide

// Set int_key to 100.
Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set str_key to "hello".
Crashlytics.crashlytics().setCustomValue("hello", forKey: "str_key")

Objectif c

Lors de la définition de nombres entiers, booléens ou flottants, définissez la valeur sous la forme @( value ) .

// Set int_key to 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set str_key to "hello".
[[FIRCrashlytics crashlytics] setCustomValue:@"hello" forKey:@"str_key"];

Vous pouvez également modifier la valeur d'une clé existante en appelant la clé et en la définissant sur une valeur différente. Par exemple:

Rapide

Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set int_key to 50 from 100.
Crashlytics.crashlytics().setCustomValue(50, forKey: "int_key")

Objectif c

[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set int_key to 50 from 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(50) forKey:@"int_key"];

Ajouter des messages de journal personnalisés

Pour vous donner plus de contexte pour les événements menant à un crash, vous pouvez ajouter des journaux Crashlytics personnalisés à votre application. Crashlytics associe les journaux à vos données de plantage et les affiche dans la page Crashlytics de la console Firebase , sous l'onglet Journaux .

Rapide

Utilisez log() ou log(format:, arguments:) pour identifier les problèmes. Si vous souhaitez obtenir une sortie de journal utile avec des messages, l'objet que vous passez à log() doit être conforme à la propriété CustomStringConvertible . log() renvoie la propriété de description que vous définissez pour l'objet. Par exemple:

Crashlytics.crashlytics().log("Higgs-Boson detected! Bailing out…, \( attributesDict )")

.log(format:, arguments:) forme les valeurs renvoyées par l'appel de getVaList() . Par exemple:

Crashlytics.crashlytics().log(format: "%@, %@", arguments: getVaList(["Higgs-Boson detected! Bailing out…", attributesDict ]))

Pour plus de détails sur l'utilisation de log() ou log(format:, arguments:) , reportez-vous à la documentation de référence des fonctions Crashlytics.

Objectif c

Utilisez log ou logWithFormat pour identifier les problèmes. Notez que si vous souhaitez obtenir une sortie de journal utile avec des messages, l'objet que vous passez à l'une ou l'autre des méthodes doit remplacer la propriété d'instance de description . Par exemple:

[[FIRCrashlytics crashlytics] log:@"Simple string message"];

[[FIRCrashlytics crashlytics] logWithFormat:@"Higgs-Boson detected! Bailing out... %@", attributesDict ];

[[FIRCrashlytics crashlytics] logWithFormat:@"Logging a variable argument list %@" arguments: va_list_arg ];

Pour plus de détails sur l'utilisation de log et logWithFormat , reportez-vous à la documentation de référence des fonctions Crashlytics.

Définir les identifiants utilisateur

Pour diagnostiquer un problème, il est souvent utile de savoir lequel de vos utilisateurs a connu un crash donné. Crashlytics inclut un moyen d'identifier de manière anonyme les utilisateurs dans vos rapports d'erreur.

Pour ajouter des ID utilisateur à vos rapports, attribuez à chaque utilisateur un identifiant unique sous la forme d'un numéro d'identification, d'un jeton ou d'une valeur hachée:

Rapide
Crashlytics.crashlytics().setUserID("123456789")
Objectif c
[[FIRCrashlytics crashlytics] setUserID:@"123456789"];

Si jamais vous devez effacer un identifiant utilisateur après l'avoir défini, réinitialisez la valeur sur une chaîne vide. La suppression d'un identifiant utilisateur ne supprime pas les enregistrements Crashlytics existants. Si vous devez supprimer des enregistrements associés à un ID utilisateur, contactez le support Firebase .

Signaler les exceptions non fatales

En plus de signaler automatiquement les plantages de votre application, Crashlytics vous permet d'enregistrer les exceptions non fatales et de vous les envoyer au prochain lancement de votre application.

Vous pouvez enregistrer des exceptions non fatales en enregistrant des objets NSError avec la méthode recordError . recordError capture la pile d'appels du thread en appelant [NSThread callStackReturnAddresses] .

Rapide

Crashlytics.crashlytics().record(error: error )

Objectif c

[[FIRCrashlytics crashlytics] recordError: error ];

Lorsque vous utilisez la méthode recordError , il est important de comprendre la structure NSError et la façon dont Crashlytics utilise les données pour regrouper les plantages. Une utilisation incorrecte de la méthode recordError peut entraîner un comportement imprévisible et peut amener Crashlytics à limiter le signalement des erreurs enregistrées pour votre application.

Un objet NSError a trois arguments:

  • domain: String
  • code: Int
  • userInfo: [AnyHashable : Any]? = nil

Contrairement aux plantages fatals, qui sont regroupés via l'analyse de trace de pile, les erreurs consignées sont regroupées par domain et code . Il s'agit d'une distinction importante entre les plantages fatals et les erreurs consignées. Par exemple:

Rapide

let userInfo = [
  NSLocalizedDescriptionKey: NSLocalizedString("The request failed.", comment: ""),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString("The response returned a 404.", comment: ""),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString("Does this page exist?", comment: ""),
  "ProductID": "123456",
  "View": "MainView"
]

let error = NSError.init(domain: NSCocoaErrorDomain,
                         code: -1001,
                         userInfo: userInfo)

Objectif c

NSDictionary *userInfo = @{
  NSLocalizedDescriptionKey: NSLocalizedString(@"The request failed.", nil),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString(@"The response returned a 404.", nil),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString(@"Does this page exist?", nil),
  @"ProductID": @"123456",
  @"View": @"MainView",
};

NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain
                                     code:-1001
                                 userInfo:userInfo];

Lorsque vous enregistrez l'erreur ci-dessus, cela crée un nouveau problème qui est regroupé par NSSomeErrorDomain et -1001 . Les erreurs consignées supplémentaires qui utilisent le même domaine et les mêmes valeurs de code sont regroupées sous le même problème. Les données contenues dans l'objet userInfo sont converties en paires clé-valeur et affichées dans la section clés / journaux d'un problème individuel.

Avertissement: évitez d'utiliser des valeurs uniques, telles que l'ID utilisateur, l'ID produit et les horodatages dans les champs de domaine et de code. L'utilisation de valeurs uniques dans ces champs entraîne une cardinalité élevée de problèmes et peut obliger Crashlytics à limiter le signalement des erreurs enregistrées dans votre application. Des valeurs uniques doivent à la place être ajoutées à l'objet dictionnaire userInfo .

Journaux et clés personnalisées

Tout comme les rapports d' NSError , vous pouvez incorporer des journaux et des clés personnalisées pour ajouter du contexte à NSError . Cependant, il existe une différence entre les journaux attachés aux plantages et les erreurs consignées. Lorsqu'un crash se produit et que l'application est relancée, les journaux que Crashlytics récupère sur le disque sont ceux qui ont été écrits jusqu'au moment du crash. Lorsque vous enregistrez une NSError , l'application ne se termine pas immédiatement. Étant donné que Crashlytics n'envoie le rapport d'erreur journalisé qu'au prochain lancement de l'application et doit limiter la quantité d'espace alloué pour les journaux sur le disque, il est possible d'enregistrer suffisamment après qu'un NSError est enregistré afin que tous les journaux pertinents soient tournés au moment où Crashlytics envoie le rapport de l'appareil. Gardez cet équilibre à l'esprit lors de la journalisation de NSErrors et de l'utilisation de journaux et de clés personnalisées dans votre application.

Considérations relatives aux performances

Gardez à l'esprit que la journalisation d'une NSError peut être assez coûteuse. Au moment où vous effectuez l'appel, Crashlytics capture la pile d'appels du thread actuel à l'aide d'un processus appelé déroulement de pile. Ce processus peut être gourmand en CPU et en E / S, en particulier sur les architectures prenant en charge le déroulement DWARF (arm64 et x86). Une fois le déroulement terminé, les informations sont écrites sur le disque de manière synchrone. Cela évite la perte de données si la ligne suivante tombe en panne.

Bien qu'il soit sûr d'appeler cette API sur un thread d'arrière-plan, n'oubliez pas que la distribution de cet appel à une autre file d'attente perd le contexte de la trace de pile actuelle.

Qu'en est-il de NSExceptions?

Crashlytics ne propose pas de fonction de journalisation et d'enregistrement des instances NSException directement. De manière générale, les API Cocoa et Cocoa Touch ne sont pas protégées contre les exceptions. Cela signifie que l'utilisation de @catch peut avoir des effets secondaires involontaires très graves dans votre processus, même lorsqu'il est utilisé avec un soin extrême. Vous ne devez jamais utiliser d'instructions @catch dans votre code. Veuillez vous référer à la documentation d' Apple sur le sujet.

Personnaliser les traces de pile

Si votre application s'exécute dans un environnement non natif (tel que C ++ ou Unity), vous pouvez utiliser l'API du modèle d'exception pour signaler les métadonnées de panne au format d'exception natif de votre application. Les exceptions signalées sont marquées comme non fatales.

Rapide

 var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame.init(symbol:"makeError" fileName:"handler.js" lineNumber:495),
  StackFrame.init(symbol:"then" fileName:"routes.js" lineNumber:102),
  StackFrame.init(symbol:"main" fileName:"app.js" lineNumber:12),
]

crashlytics.record(exceptionModel:ex)
 

Objectif c

 FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithSymbol:@"makeError" fileName:@"handler.js" lineNumber:495],
  [FIRStackFrame stackFrameWithSymbol:@"then" fileName:@"routes.js" lineNumber:102],
  [FIRStackFrame stackFrameWithSymbol:@"main" fileName:@"app.js" lineNumber:12],
];
 

Activer les rapports d'activation

Par défaut, Crashlytics collecte automatiquement les rapports d'erreur pour tous les utilisateurs de votre application. Pour donner aux utilisateurs plus de contrôle sur les données qu'ils envoient, vous pouvez activer les rapports d'acceptation pour vos utilisateurs en désactivant la collecte automatique et en initialisant Crashlytics uniquement pour les utilisateurs sélectionnés:

  1. Désactivez la collecte automatique en ajoutant une nouvelle clé à votre fichier Info.plist :

    • Clé: FirebaseCrashlyticsCollectionEnabled
    • Valeur: false
  2. Activez la collecte pour certains utilisateurs en appelant le remplacement de collecte de données Crashlytics lors de l'exécution. La valeur de remplacement persiste lors des lancements de votre application afin que Crashlytics puisse collecter automatiquement des rapports. Pour désactiver le rapport automatique des plantages, indiquez false comme valeur de remplacement. Lorsqu'elle est définie sur false , la nouvelle valeur ne s'applique qu'à la prochaine exécution de l'application.

    Rapide
    Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)
    Objectif c
    [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

Gérer les données Crash Insights

Crash Insights vous aide à résoudre les problèmes en comparant vos traces de pile anonymisées aux traces d'autres applications Firebase et en vous indiquant si votre problème fait partie d'une tendance plus large. Pour de nombreux problèmes, Crash Insights fournit même des ressources pour vous aider à déboguer le plantage.

Crash Insights utilise des données de crash agrégées pour identifier les tendances de stabilité communes. Si vous préférez ne pas partager les données de votre application, vous pouvez désactiver Crash Insights dans le menu Crash Insights en haut de votre liste de problèmes Crashlytics dans la console Firebase .