Настройте отчеты о сбоях 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")

Objective-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")

Objective-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)

Objective-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() возвращает свойство description, которое вы определили для объекта. Например:

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 .

Objective-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")

Objective-C

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

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

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

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

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

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

Быстрый

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

Objective-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)

Objective-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)

Objective-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)

Objective-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 может автоматически собирать отчёты для этого пользователя.

   Быстрый

   Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

   Objective-C

   [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

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

Примечание: Если сбор данных для пользователя отключен, Crashlytics будет хранить информацию о сбоях локально на устройстве. Если сбор данных будет впоследствии включен, вся информация о сбоях, хранящаяся на устройстве, будет отправлена ​​в Crashlytics для обработки.

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

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

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

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