Dostosowywanie raportów o awariach na platformach Apple

Możesz kliknąć problem i uzyskać szczegółowy raport o zdarzeniu w sekcji DevOps i zaangażowanie > Crashlytics panel w konsoli Firebase. Możesz dostosowywać te raporty, aby lepiej rozumieć, co się dzieje w Twojej aplikacji, i okoliczności zdarzeń zgłaszanych do Crashlytics.

• Zintegruj aplikację, aby rejestrować klucze niestandardowe, niestandardowe komunikaty logu i identyfikatory użytkowników.

• Zgłaszaj wyjątki do Crashlytics.

• Automatycznie otrzymuj logi ścieżki, jeśli Twoja aplikacja korzysta z pakietu SDK Firebase na potrzeby Google Analytics. Te logi zapewniają wgląd w działania użytkowników prowadzące do zdarzenia zebranego przez Crashlytics w aplikacji.

• Wyłącz automatyczne raportowanie awarii i włącz raportowanie za zgodą użytkowników. Pamiętaj, że domyślnie Crashlytics automatycznie zbiera raporty o awariach od wszystkich użytkowników Twojej aplikacji.

Dodawanie kluczy niestandardowych

Klucze niestandardowe pomagają uzyskać konkretny stan aplikacji przed awarią. Z raportami o awariach możesz powiązać dowolne pary klucz-wartość, a potem używać kluczy niestandardowych do wyszukiwania i filtrowania raportów o awariach na panelu DevOps i zaangażowanie > Crashlytics w Firebase konsoli.

• Możesz wyszukiwać problemy pasujące do klucza niestandardowego.

• Podczas sprawdzania konkretnego problemu w konsoli możesz wyświetlić powiązane klucze niestandardowe dla każdego zdarzenia (karta Klucze), a nawet filtrować zdarzenia według kluczy niestandardowych (menu Filtr u góry strony).

Aby ustawić pary klucz-wartość, użyj metody setCustomValue. Przykład:

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

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

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

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

Możesz też zmodyfikować wartość istniejącego klucza, wywołując go i ustawiając inną wartość. Przykład:

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

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

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

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

Dodaj pary klucz-wartość zbiorczo, używając metody setCustomKeysAndValues z obiektem NSDictionary jako jedynym parametrem:

let keysAndValues = [
                 "string key" : "string value",
                 "string key 2" : "string value 2",
                 "boolean key" : true,
                 "boolean key 2" : false,
                 "float key" : 1.01,
                 "float key 2" : 2.02
                ] as [String : Any]

Crashlytics.crashlytics().setCustomKeysAndValues(keysAndValues)

NSDictionary *keysAndValues =
    @{@"string key" : @"string value",
      @"string key 2" : @"string value 2",
      @"boolean key" : @(YES),
      @"boolean key 2" : @(NO),
      @"float key" : @(1.01),
      @"float key 2" : @(2.02)};

[[FIRCrashlytics crashlytics] setCustomKeysAndValues: keysAndValues];

Dodawanie niestandardowych wiadomości w dzienniku

Aby uzyskać więcej informacji o zdarzeniach, które doprowadziły do awarii, możesz dodać do aplikacji niestandardowe Crashlytics dzienniki. Crashlytics powiąże dzienniki z danymi o awarii i wyświetli je na karcie Dzienniki, gdy będziesz przeglądać szczegóły problemu (wszystkie problemy znajdziesz na panelu DevOps i zaangażowanie > Crashlytics w konsoli Firebase).

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

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

[[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];

Ustawianie identyfikatorów użytkowników

Aby zdiagnozować problem, często warto wiedzieć, u których użytkowników wystąpiło dane awaryjne zamknięcie aplikacji. Crashlytics umożliwia anonimową identyfikację użytkowników w raportach o awariach.

Aby dodać do raportów identyfikatory użytkowników, przypisz każdemu użytkownikowi unikalny identyfikator w postaci numeru identyfikacyjnego, tokena lub zaszyfrowanej wartości:

Crashlytics.crashlytics().setUserID("123456789")

[[FIRCrashlytics crashlytics] setUserID:@"123456789"];

Jeśli po ustawieniu identyfikatora użytkownika chcesz go wyczyścić, zresetuj wartość do pustego ciągu znaków. Wyczyszczenie identyfikatora użytkownika nie powoduje usunięcia istniejących rekordów.Crashlytics Jeśli chcesz usunąć rekordy powiązane z identyfikatorem użytkownika, skontaktuj się z zespołem pomocy Firebase.

Zgłaszanie błędów niekrytycznych

Oprócz automatycznego zgłaszania awarii aplikacji Crashlytics umożliwia rejestrowanie niekrytycznych wyjątków i przesyłanie ich do Ciebie przy następnym uruchomieniu aplikacji.

Możesz rejestrować wyjątki niekrytyczne, rejestrując obiekty NSError za pomocą metody recordError. recordError przechwytuje stos wywołań wątku, wywołując [NSThread callStackReturnAddresses].

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

[[FIRCrashlytics crashlytics] recordError:error];

Podczas korzystania z metody recordError ważne jest, aby zrozumieć NSErrorstrukturę i sposób, w jaki Crashlytics używa danych do grupowania awarii. Nieprawidłowe użycie metody recordError może powodować nieprzewidywalne zachowanie i sprawić, że Crashlytics ograniczy raportowanie zarejestrowanych błędów w Twojej aplikacji.

Obiekt NSError ma 3 argumenty:

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

W przeciwieństwie do awarii krytycznych, które są grupowane na podstawie analizy zrzutu stosu, zalogowane błędy są grupowane według domain i code. To ważna różnica między awariami krytycznymi a zarejestrowanymi błędami. Przykład:

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)

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];

Gdy zarejestrujesz powyższy błąd, utworzysz nowy problem, który zostanie pogrupowany według NSSomeErrorDomain i -1001. Dodatkowe zarejestrowane błędy, które używają tych samych wartości domeny i kodu, są grupowane w ramach tego samego problemu. Dane zawarte w obiekcie userInfo są przekształcane w pary klucz-wartość i wyświetlane w sekcji kluczy/logów w ramach poszczególnych problemów.

Logi i klucze niestandardowe

Podobnie jak w przypadku raportów o awariach możesz osadzać logi i klucze niestandardowe, aby dodać kontekst do NSError. Istnieje jednak różnica w tym, jakie dzienniki są dołączane do awarii, a jakie do zarejestrowanych błędów. Gdy dojdzie do awarii i aplikacja zostanie ponownie uruchomiona, Crashlyticspobrane z dysku logiCrashlytics będą zawierać informacje zapisane do momentu awarii. Gdy zarejestrujesz NSError, aplikacja nie zostanie natychmiast zamknięta. Ponieważ Crashlytics wysyła zarejestrowany raport o błędzie dopiero przy następnym uruchomieniu aplikacji i musi ograniczyć ilość miejsca na dysku przeznaczonego na dzienniki, może się zdarzyć, że po zarejestrowaniu błędu NSError zostanie zarejestrowana wystarczająca liczba dzienników, aby wszystkie istotne dzienniki zostały usunięte, zanim Crashlytics wyśle raport z urządzenia. Pamiętaj o tym, rejestrując NSErrors i używając w aplikacji logów oraz kluczy niestandardowych.

Możliwe spowolnienie działania witryny

Pamiętaj, że rejestrowanie NSError może być dość kosztowne. W momencie nawiązania połączenia Crashlytics rejestruje bieżący stos wywołań wątku za pomocą procesu zwanego rozwijaniem stosu. Ten proces może być wymagający pod względem procesora i operacji wejścia/wyjścia, szczególnie w przypadku architektur obsługujących odwijanie DWARF (arm64 i x86). Po zakończeniu wycofywania informacje są zapisywane na dysku synchronicznie. Zapobiega to utracie danych w przypadku awarii następnej linii.

Wywoływanie tego interfejsu API w wątku w tle jest bezpieczne, ale pamiętaj, że wysyłanie tego wywołania do innej kolejki powoduje utratę kontekstu bieżącego śladu stosu.

A co z NSException?

Crashlytics nie oferuje funkcji rejestrowania i zapisywania NSException wystąpień bezpośrednio. Ogólnie rzecz biorąc, interfejsy API Cocoa i Cocoa Touch nie są bezpieczne w przypadku wyjątków. Oznacza to, że użycie @catch może mieć bardzo poważne niezamierzone skutki uboczne w procesie, nawet jeśli jest używane z największą starannością. Nigdy nie należy używać instrukcji @catch w kodzie. Więcej informacji na ten temat znajdziesz w dokumentacji Apple.

Dostosowywanie śladów stosu

Jeśli Twoja aplikacja działa w środowisku innym niż natywne (np. C++ lub Unity), możesz użyć interfejsu Exception Model API, aby zgłaszać metadane o awariach w natywnym formacie wyjątków aplikacji. Zgłoszone wyjątki są oznaczane jako niekrytyczne.

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

crashlytics.record(exceptionModel:ex)

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

[[FIRCrashlytics crashlytics] recordExceptionModel:model];

Niestandardowe ramki stosu można też inicjować tylko za pomocą adresów:

var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(address:0xfa12123),
  StackFrame(address:12412412),
  StackFrame(address:194129124),
]

crashlytics.record(exceptionModel:ex)

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithAddress:0xfa12123],
  [FIRStackFrame stackFrameWithAddress:12412412],
  [FIRStackFrame stackFrameWithAddress:194129124],
];


[[FIRCrashlytics crashlytics] recordExceptionModel:model];

Pobieranie dzienników elementów menu nawigacyjnego

Dzienniki ścieżki pozwalają lepiej poznać interakcje użytkownika z aplikacją, które doprowadziły do awarii, błędu niekrytycznego lub błędu ANR. Te dzienniki mogą być przydatne podczas odtwarzania i debugowania problemu.

Dzienniki ścieżki są obsługiwane przez Google Analytics, więc aby je uzyskać, musisz włączyć Google Analytics w projekcie Firebase i dodać do aplikacji pakiet SDK Firebase na platformę Google Analytics. Gdy spełnisz te wymagania, dzienniki ścieżki będą automatycznie dołączane do danych zdarzenia na karcie Dzienniki, gdy wyświetlasz szczegóły problemu (wszystkie problemy znajdziesz na panelu DevOps i zaangażowanie > Crashlytics w konsoli Firebase).

Pakiet Analytics SDKautomatycznie rejestruje screen_view zdarzenie, dzięki czemu logi ścieżki mogą wyświetlać listę ekranów wyświetlonych przed awarią, błędem niekrytycznym lub zdarzeniem ANR. Dziennik ścieżki screen_view zawiera parametr firebase_screen_class.

Dzienniki ścieżki są też wypełniane zdarzeniami niestandardowymi, które rejestrujesz ręcznie w sesji użytkownika, w tym danymi parametrów zdarzenia. Te dane mogą pokazywać serię działań użytkownika, które doprowadziły do awarii, błędu niekrytycznego lub błędu ANR.

Pamiętaj, że możesz kontrolować zbieranie i wykorzystywanie danych Google Analytics, w tym danych, które wypełniają logi ścieżki.

Włącz raportowanie na podstawie zgody użytkowników

Domyślnie Crashlytics automatycznie zbiera raporty o awariach wszystkich użytkowników Twojej aplikacji. Aby dać użytkownikom większą kontrolę nad wysyłanymi danymi, możesz włączyć raportowanie z możliwością rezygnacji, wyłączając automatyczne raportowanie i wysyłając dane do Crashlytics tylko wtedy, gdy zdecydujesz się na to w kodzie.

1. Wyłącz automatyczne zbieranie danych, dodając nowy klucz do pliku Info.plist:

   • Klucz: FirebaseCrashlyticsCollectionEnabled
   • Wartość: false

2. Włącz zbieranie danych w przypadku wybranych użytkowników, wywołując w czasie działania programu zastąpienie Crashlytics data collection. Wartość zastępowania jest zachowywana we wszystkich kolejnych uruchomieniach aplikacji, dzięki czemu Crashlytics może automatycznie zbierać raporty dotyczące tego użytkownika.

   Swift

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Objective-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

   Jeśli użytkownik później zrezygnuje ze zbierania danych, możesz przekazać wartość zastępczą false. Zostanie ona zastosowana przy następnym uruchomieniu aplikacji przez użytkownika i będzie obowiązywać przy wszystkich kolejnych uruchomieniach.

Zarządzanie danymi Crash Insights

Statystyki awarii pomagają rozwiązywać problemy, porównując anonimowe ślady stosu z innymi aplikacjami Firebase i informując, czy problem jest częścią większego trendu. W przypadku wielu problemów statystyki awarii udostępniają nawet zasoby, które pomagają w debugowaniu awarii.

Statystyki dotyczące awarii wykorzystują zagregowane dane o awariach do identyfikowania typowych trendów związanych ze stabilnością. Jeśli nie chcesz udostępniać danych aplikacji, możesz zrezygnować ze statystyk dotyczących awarii w menu Statystyki dotyczące awarii u góry listy problemów na panelu DevOps i zaangażowanie > Crashlytics w konsoli Firebase.

Dalsze kroki

• Eksportuj dane do BigQuery lub Cloud Logging, aby korzystać z zaawansowanych analiz i funkcji, takich jak wysyłanie zapytań dotyczących danych, tworzenie niestandardowych paneli i konfigurowanie niestandardowych alertów.