Настройте отчеты о сбоях Firebase Crashlytics

iOS+ Android Flutter Unity

На панели управления Crashlytics вы можете нажать на проблему и получить подробный отчет о событии. Вы можете настроить эти отчеты, чтобы лучше понимать, что происходит в вашем приложении, и обстоятельства событий, о которых сообщается в Crashlytics .

• Настройте свое приложение для регистрации пользовательских ключей , пользовательских сообщений журнала и идентификаторов пользователей .

• Сообщайте об исключениях в Crashlytics .

• Автоматически получайте навигационные журналы, если ваше приложение использует Firebase SDK для Google Analytics . Эти журналы дают вам представление о действиях пользователей, которые привели к событию, собранному Crashlytics , в вашем приложении.

• Отключите автоматические отчеты о сбоях и включите возможность включения отчетов для своих пользователей. Обратите внимание, что по умолчанию Crashlytics автоматически собирает отчеты о сбоях для всех пользователей вашего приложения.

Добавить пользовательские ключи

Пользовательские ключи помогают вам получить конкретное состояние вашего приложения, приводящее к сбою. Вы можете связать произвольные пары ключ/значение с отчетами о сбоях, а затем использовать пользовательские ключи для поиска и фильтрации отчетов о сбоях в консоли Firebase .

• На панели управления Crashlytics вы можете искать проблемы, соответствующие пользовательскому ключу.
• Просматривая конкретную проблему в консоли, вы можете просмотреть связанные пользовательские ключи для каждого события (подвкладка «Ключи» ) и даже отфильтровать события по настраиваемым ключам (меню «Фильтр» вверху страницы).

Примечание. Crashlytics поддерживает максимум 64 пары ключ/значение. После достижения этого порога дополнительные значения не сохраняются. Каждая пара ключ/значение может иметь размер до 1 КБ.

Используйте метод setCustomValue для установки пар ключ/значение. Например:

Быстрый

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

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

Цель-C

При установке целых чисел, логических значений или чисел с плавающей запятой укажите значение в виде @( 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"];

Вы также можете изменить значение существующего ключа, вызвав ключ и установив для него другое значение. Например:

Быстрый

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

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

Цель-C

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

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

Добавляйте пары ключ/значение массово, используя метод setCustomKeysAndValues ​​с NSDictionary в качестве единственного параметра:

Быстрый

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)

Цель-C

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

Добавить пользовательские сообщения журнала

Чтобы получить больше контекста для событий, приведших к сбою, вы можете добавить в свое приложение собственные журналы Crashlytics . Crashlytics связывает журналы с данными о сбоях и отображает их на странице Crashlytics консоли Firebase на вкладке Журналы .

Примечание. Чтобы избежать замедления работы приложения, Crashlytics ограничивает размер журналов 64 КБ и удаляет старые записи журнала, когда журналы сеанса превышают этот предел.

Быстрый

Используйте log() или log(format:, arguments:) , чтобы выявить проблемы. Если вы хотите получить полезный вывод журнала с сообщениями, объект, который вы передаете в log() должен соответствовать свойству CustomStringConvertible . log() возвращает свойство описания, определенное вами для объекта. Например:

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

.log(format:, arguments:) форматирует значения, возвращаемые при вызове getVaList() . Например:

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

Более подробную информацию о том, как использовать log() или log(format:, arguments:) , можно найти в справочной документации Crashlytics .

Цель-C

Используйте log или logWithFormat , чтобы выявить проблемы. Обратите внимание: если вы хотите получить полезные выходные данные журнала с сообщениями, объект, который вы передаете любому методу, должен переопределить свойство экземпляра description . Например:

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

Более подробную информацию о том, как использовать log и logWithFormat , можно найти в справочной документации Crashlytics .

Установить идентификаторы пользователей

Для диагностики проблемы часто полезно знать, у кого из ваших пользователей произошел данный сбой. Crashlytics включает в себя способ анонимной идентификации пользователей в отчетах о сбоях.

Чтобы добавить идентификаторы пользователей в отчеты, назначьте каждому пользователю уникальный идентификатор в форме идентификационного номера, токена или хеш-значения:

Быстрый

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

Цель-C

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

Если вам когда-нибудь понадобится очистить идентификатор пользователя после его установки, сбросьте значение на пустую строку. Очистка идентификатора пользователя не удаляет существующие записи Crashlytics . Если вам нужно удалить записи, связанные с идентификатором пользователя, обратитесь в службу поддержки Firebase .

Сообщать о нефатальных исключениях

Помимо автоматического сообщения о сбоях вашего приложения, Crashlytics позволяет вам записывать нефатальные исключения и отправлять их вам при следующем запуске вашего приложения.

Примечание. Crashlytics сохраняет только последние восемь исключений в данном сеансе приложения. Если ваше приложение выдает более восьми исключений за сеанс, более старые исключения теряются.

Вы можете записывать нефатальные исключения, записывая объекты NSError с помощью метода recordError . recordError захватывает стек вызовов потока, вызывая [NSThread callStackReturnAddresses] .

Быстрый

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

Цель-C

[[FIRCrashlytics crashlytics] recordError:error];

При использовании метода recordError важно понимать структуру NSError и то, как Crashlytics использует данные для группировки сбоев. Неправильное использование метода recordError может привести к непредсказуемому поведению и привести к тому, что Crashlytics ограничит отчеты о зарегистрированных ошибках для вашего приложения.

Объект NSError имеет три аргумента:

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

В отличие от фатальных сбоев, которые группируются с помощью анализа трассировки стека, зарегистрированные ошибки группируются по domain и code . Это важное различие между фатальными сбоями и зарегистрированными ошибками. Например:

Быстрый

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)

Цель-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];

Когда вы регистрируете ошибку выше, она создает новую проблему, сгруппированную по NSSomeErrorDomain и -1001 . Дополнительные зарегистрированные ошибки, использующие тот же домен и значения кода, сгруппированы в одной проблеме. Данные, содержащиеся в объекте userInfo , преобразуются в пары «ключ-значение» и отображаются в разделе «ключи/журналы» в рамках отдельной задачи.

Внимание: избегайте использования уникальных значений, таких как идентификатор пользователя, идентификатор продукта и метки времени, в полях домена и кода. Использование уникальных значений в этих полях приводит к большому количеству проблем и может привести к тому, что Crashlytics придется ограничить отчеты о зарегистрированных ошибках в вашем приложении. Вместо этого уникальные значения следует добавлять в объект словаря userInfo .

Журналы и пользовательские ключи

Как и в случае с отчетами о сбоях, вы можете встраивать журналы и пользовательские ключи для добавления контекста в NSError . Однако существует разница в том, какие журналы прикрепляются к сбоям и зарегистрированным ошибкам. Когда происходит сбой и приложение перезапускается, Crashlytics извлекает с диска журналы, которые были записаны вплоть до момента сбоя. Когда вы регистрируете NSError , приложение не завершает работу немедленно. Поскольку Crashlytics отправляет зарегистрированный отчет об ошибках только при следующем запуске приложения и должен ограничивать объем места, выделенного для журналов на диске, после записи NSError можно записать достаточное количество журналов, чтобы все соответствующие журналы были заменены к тому времени, когда Crashlytics отправит отчет с устройства. Помните об этом балансе при регистрации NSErrors и использовании журналов и пользовательских ключей в своем приложении.

Вопросы производительности

Имейте в виду, что регистрация NSError может оказаться довольно дорогостоящей. В момент выполнения вызова Crashlytics фиксирует стек вызовов текущего потока, используя процесс, называемый раскручиванием стека. Этот процесс может требовать интенсивного использования ЦП и операций ввода-вывода, особенно на архитектурах, поддерживающих размотку DWARF (arm64 и x86). После завершения раскрутки информация синхронно записывается на диск. Это предотвращает потерю данных в случае сбоя следующей строки.

Хотя вызов этого API в фоновом потоке безопасен, помните, что при отправке этого вызова в другую очередь теряется контекст текущей трассировки стека.

А как насчет NSExceptions?

Crashlytics не предлагает возможности для непосредственной регистрации и записи экземпляров NSException . Вообще говоря, API-интерфейсы Cocoa и Cocoa Touch не защищены от исключений. Это означает, что использование @catch может иметь очень серьезные непредвиденные побочные эффекты в вашем процессе, даже если использовать его с особой осторожностью. Никогда не следует использовать операторы @catch в своем коде. Пожалуйста, обратитесь к документации Apple по этой теме.

Настройка трассировки стека

Если ваше приложение работает в неродной среде (например, C++ или Unity), вы можете использовать API модели исключений, чтобы сообщать метаданные о сбое в собственном формате исключений вашего приложения. Сообщенные исключения помечаются как нефатальные.

Быстрый

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)

Цель-C

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

Пользовательские кадры стека также могут быть инициализированы только с помощью адресов:

Быстрый

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)

Цель-C

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

Получить навигационные журналы

Журналы навигации позволяют лучше понять взаимодействие пользователя с вашим приложением, которое привело к сбою, несмертельному событию или событию ANR. Эти журналы могут быть полезны при попытке воспроизвести и отладить проблему.

Журналы навигации основаны на Google Analytics, поэтому для получения журналов навигации вам необходимо включить Google Analytics для вашего проекта Firebase и добавить Firebase SDK для Google Analytics в свое приложение. Как только эти требования будут выполнены, навигационные журналы автоматически включаются в данные о событии на вкладке «Журналы» , когда вы просматриваете подробности проблемы.

Analytics SDK автоматически регистрирует событие screen_view , которое позволяет в журналах навигации отображать список экранов, просмотренных до сбоя, нефатального события или события ANR. Хлебный журнал screen_view содержит параметр firebase_screen_class .

Журналы навигации также заполняются любыми пользовательскими событиями , которые вы вручную регистрируете в сеансе пользователя, включая данные параметров событий. Эти данные могут помочь показать серию действий пользователя, приведших к сбою, нефатальному событию или событию ANR.

Обратите внимание, что вы можете контролировать сбор и использование данных Google Analytics , включая данные, заполняющие журналы навигации.

Включить подписку на получение отчетов

По умолчанию Crashlytics автоматически собирает отчеты о сбоях для всех пользователей вашего приложения. Чтобы предоставить пользователям больше контроля над отправляемыми ими данными, вы можете включить возможность включения отчетов, отключив автоматические отчеты и отправляя данные в Crashlytics только тогда, когда вы решите это сделать в своем коде:

1. Отключите автоматический сбор, добавив новый ключ в файл Info.plist :

   • Ключ: FirebaseCrashlyticsCollectionEnabled
   • Значение: false

2. Включите сбор для избранных пользователей, вызвав переопределение сбора данных Crashlytics во время выполнения. Значение переопределения сохраняется при запуске вашего приложения, поэтому Crashlytics может автоматически собирать отчеты.

   Чтобы отказаться от автоматического сообщения о сбоях, передайте false в качестве значения переопределения. Если установлено значение false , новое значение не применяется до следующего запуска приложения.

   Быстрый

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Цель-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

Примечание . Если вы отключите автоматические отчеты, имейте в виду следующее:

• Если для пользователя отключен сбор данных, Crashlytics будет хранить информацию о сбоях локально на устройстве. Если впоследствии сбор данных будет включен, любая информация о сбоях, хранящаяся на устройстве, будет отправлена ​​в Crashlytics для обработки.
• Когда вы включаете возможность создания отчетов, информация о сбоях может быть собрана только от пользователей, которые явно согласились на сбор данных. Таким образом, это повлияет на точность показателей без сбоев (таких как пользователи без сбоев и сеансы без сбоев), поскольку Crashlytics собирает информацию о сбоях только от этих согласившихся пользователей (а не от всех ваших пользователей). Это означает, что ваши показатели отсутствия сбоев могут быть менее надежными и менее отражающими общую стабильность вашего приложения.

Управление данными Crash Insights

Crash Insights помогает вам решать проблемы, сравнивая анонимные трассировки стека со трассировками из других приложений Firebase и сообщая вам, является ли ваша проблема частью более широкой тенденции. Для многих проблем Crash Insights даже предоставляет ресурсы, которые помогут вам устранить сбой.

Crash Insights использует агрегированные данные о сбоях для выявления общих тенденций стабильности. Если вы предпочитаете не делиться данными своего приложения, вы можете отказаться от Crash Insights в меню Crash Insights в верхней части списка проблем Crashlytics в консоли Firebase .

Примечание. Отключение совместного использования данных также приведет к удалению информации о ваших проблемах. Изменения вступят в силу в течение 24 часов.