Загрузка и управление файлами символов для мобильных приложений

Материал из Документация Ключ-АСТРОМ

Загрузка и управление файлами символов для мобильных приложений в классическом Мониторинге реального пользователя

Android iOS tvOS

Подробную информацию о картах исходного кода для веб-приложений см. в разделе «Поддержка карт исходного кода для анализа ошибок JavaScript в классическом Мониторинге реального пользователя».

Деобфускация (Android) или символизация (iOS и tvOS) — это процесс придания классам и методам удобочитаемого вида в трассировке стека отчета о сбое.

В следующем примере представлен трассировочный стек Android до и после деобфускации:

Трассировка стека Android до и после деобфускации

Ключ-АСТРОМ позволяет управлять файлами сопоставления Android и файлами извлечения символов iOS или tvOS, необходимыми для интерпретации трассировок стека мобильных устройств, получаемых Ключ-АСТРОМ.

Ключ-АСТРОМ поддерживает несколько способов загрузки этих файлов:

  • С помощью службы символизации, известной как «Служба деобфускации и символизации» (DSS).
  • Через REST API Ключ-АСТРОМ.
  • Через плагин Fastlane Ключ-АСТРОМ.
  • Через веб-интерфейс Ключ-АСТРОМ.

В настоящее время Ключ-АСТРОМ поддерживает символизацию строк трассировки стека только из приложений и сторонних библиотек на iOS и tvOS, для которых предоставлены файлы dSYM. Символизация строк трассировки стека системных библиотек не поддерживается.

Ограничения

Вы можете загрузить файл с символами в любом поддерживаемом формате (сжатом или несжатом). Обратите внимание на следующие ограничения:

  • Загруженный файл не должен превышать 100 МиБ.
  • Несжатый файл — его размер после декомпрессии (если он сжат) не должен превышать 500 МиБ.
  • Если ваш файл слишком большой, попробуйте сжать его, чтобы он не превышал лимит загрузки в 100 МиБ.

Для загрузки исходных карт и файлов символов вам необходимы права на изменение настроек мониторинга на уровне среды.

Загрузка файлов сопоставления для Android

Для Android загрузите файлы сопоставления вашего приложения в их исходном виде. Предварительная обработка этих файлов не требуется.

Чтобы узнать больше о файлах сопоставления и о том, где их найти, ознакомьтесь с официальной документацией Android.

Загрузка файлов сопоставления через DSSClient

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

Шаг 1: Получите DSSClient

Вы можете загрузить DSSClient через веб-интерфейс Ключ-АСТРОМ.

  1. Перейти в мобильную версию.
  2. Выберите мобильное приложение, которое хотите настроить.
  3. Выберите Дополнительно (…) > Редактировать в правом верхнем углу плитки с названием вашего приложения.
  4. В настройках приложения выберите Файлы символов.
  5. Прокрутите страницу вниз и перейдите по ссылке DSSClient.
  6. Запустите DSSClient.

В macOS Catalina система запрещает запуск DSSClient при первом запуске и отображает предупреждающее диалоговое окно. Отмените предупреждение; перейдите в Системные настройки > Безопасность и конфиденциальность и выберите Открыть в любом случае, чтобы разрешить запуск DSSClient.

Такое поведение вызвано тем, что DSSClient ссылается на фреймворк LLDB Xcode, который не принимается Gatekeeper, независимо от того, заверен ли DSSClient.

Использовать DSSClient можно только на компьютерах под управлением macOS.

Шаг 2: Загрузка файлов сопоставления через DSSClient

Загрузите файл сопоставления вашего приложения в Ключ-АСТРОМ в исходном виде. Выполните следующую команду в DSSClient: 

DTXDssClient -upload appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=android bundleId=org.comp.app versionStr=1.0 version=1 file=/usr/local/mapping.txt server=https://server.com
Параметр Определение Где найти
-upload Флаг команды. –
appId Идентификатор приложения, который Ключ-АСТРОМ использует для идентификации приложения. Веб-интерфейс Ключ-АСТРОМ > Мобильное приложение > Настройки приложения > Мастер настройки измерительных приборов
apitoken Приватный токен, используемый для безопасной связи через REST API. Веб-интерфейс Ключ-АСТРОМ > Токены доступа
os Операционная система, которая должна быть обработана (android). –
bundleId Имя пакета приложения, например com.yourcompany.app. –
versionStr Название версии приложения. Файл build.gradle
version Код версии приложения. Файл build.gradle
file Путь к файлу сопоставления, который вы хотите загрузить. build/outputs/mapping/release/mapping.txt
server URL-адрес сервера Ключ-АСТРОМ, например, xyz.astromkey.com. –

Для получения подробного обзора всех возможных параметров запустите исполняемый файл DTXDssClient с помощью команды -h.

Если вам потребуется удалить файлы сопоставления, используйте следующую команду: 

DTXDssClient -delete appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=android bundleId=org.comp.app versionStr=1.0 version=1 server=https://server.com

Загрузка файлов сопоставления через REST API

API мобильной символизации позволяет автоматизировать загрузку картографических файлов для Android.

Для загрузки файлов сопоставления вашего приложения в Ключ-АСТРОМ используйте метод PUT upload file for an app version.

Загрузка файлов карт через плагин Fastlane

Вы можете использовать плагин Fastlane Ключ-АСТРОМ для автоматизации всего процесса передачи файлов картографирования Android в Ключ-АСТРОМ.

Для получения более подробной информации и инструкций ознакомьтесь с документацией плагина на GitHub.

Загрузка файлов сопоставления через веб-интерфейс

Вы также можете использовать веб-интерфейс Ключ-АСТРОМ для загрузки файлов сопоставления вашего приложения либо через настройки среды, либо через настройки приложения.

Через настройки среды

  1. В Ключ-АСТРОМ перейдите в Настройки > Веб- и мобильный мониторинг > Карты исходных данных и файлы символов.
  2. В разделе Android выберите Загрузить файлы.
  3. Выберите приложение из выпадающего списка.
  4. Укажите имя пакета — имя пакета приложения, например com.yourcompany.app.
  5. Введите код версии и название версии — вы найдете их в файле build.gradle.
  6. Выберите файл, который хотите загрузить, и укажите файл сопоставления.
  7. Выберите Загрузить.

Через настройки приложения

  1. Перейти в мобильную версию.
  2. Выберите мобильное приложение, которое хотите настроить.
  3. Выберите Дополнительно (…) > Редактировать в правом верхнем углу плитки с названием вашего приложения.
  4. В настройках приложения выберите Файлы символов.
  5. В разделе Android выберите Загрузить файлы.
  6. Укажите имя пакета, код версии и название версии.
  7. Выберите файл сопоставления и нажмите Загрузить.

Загрузка файлов символов для iOS и tvOS

Для символизации файлов iOS или tvOS необходимо предварительно обработать файлы dSYM с помощью DSSClient, прежде чем загружать их в Ключ-АСТРОМ.

Шаг 1: Получить файлы dSYM

Используйте файлы dSYM из каталога приложения .xcarchive или сборки.

Для загрузки файлов dSYM с помощью архива приложений Xcode:

  1. В меню Xcode выберите Window > Organizer > Archives > ваше мобильное приложение.
  2. Выберите архив с необходимой версией приложения и номером сборки.
  3. Выберите Загрузить отладочные символы.
  4. Щелкните правой кнопкой мыши по загруженному архиву и выберите Показать в Finder. Используйте отобразившийся файл .xcarchive в качестве входных данных в DSSClient (см. следующий шаг).

Шаг 2: Получите DSSClient

Вы можете загрузить DSSClient через веб-интерфейс Ключ-АСТРОМ.

  1. Перейти в мобильную версию.
  2. Выберите мобильное приложение, которое хотите настроить.
  3. Выберите Дополнительно (…) > Редактировать в правом верхнем углу плитки с названием вашего приложения.
  4. В настройках приложения выберите Файлы символов.
  5. Прокрутите страницу вниз и перейдите по ссылке DSSClient.
  6. Запустите DSSClient.

В macOS Catalina система запрещает запуск DSSClient при первом запуске и отображает предупреждающее диалоговое окно. Отмените предупреждение; перейдите в Системные настройки > Безопасность и конфиденциальность и выберите Открыть в любом случае, чтобы разрешить запуск DSSClient.

Использовать DSSClient можно только на компьютерах под управлением macOS.

Шаг 3: Предварительная обработка файлов dSYM

Перед загрузкой файлов dSYM в Ключ-АСТРОМ выполните предварительную обработку. Запустите одну из следующих команд в DSSClient: 

# Для файлов dSYM, загруженных с помощью архива приложений Xcode
DTXDssClient -decode symbolsfile=easyTravelApp.xcarchive

# Для файлов dSYM из App Store Connect
DTXDssClient -decode symbolsfile=appDsyms.zip

Шаг 4: Загрузка файлов с извлеченными символами

Загрузка через DSSClient

Загрузите обработанные файлы в Ключ-АСТРОМ с помощью DSSClient. 

DTXDssClient -upload appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=ios bundleId=org.comp.app bundleName=App versionStr=1.0 version=1 symbolsfile=/usr/local/app.xcarchive/dSYMs server=https://server.com
Параметр Определение Где найти
-upload Флаг команды. –
appId Идентификатор приложения, который Ключ-АСТРОМ использует для идентификации приложения. Веб-интерфейс Ключ-АСТРОМ > Мобильное приложение > Настройки приложения > Мастер настройки измерительных приборов
apitoken Приватный токен, используемый для безопасной связи через REST API. Веб-интерфейс Ключ-АСТРОМ > Токены доступа
os Операционная система — ios или tvos. –
bundleId Идентификатор пакета приложения. Цель приложения > Общие > Идентификатор пакета
bundleName Название пакета приложения. Цель приложения > Общие > Отображаемое имя
versionStr Строка версии приложения. Целевая страница приложения > Общие > Версия
version Версия приложения. Цель приложения > Общие > Сборка
symbolsFile Путь к папке, содержащей файлы dSYM приложения. your_app_name.xcarchive/dSYMs
server URL-адрес сервера Ключ-АСТРОМ, например, xyz.astromkey.com. –

Если вам потребуется удалить файлы символов, используйте следующую команду: 

DTXDssClient -delete appid=aa-bb-cc-dd-ee apitoken=Z-123aefc os=ios bundleId=org.comp.app versionStr=1.0 version=1 server=https://server.com

Загрузка через REST API

API мобильной символизации позволяет автоматизировать загрузку файлов символов.

Для загрузки обработанных файлов символов используйте метод PUT upload file for an app version.

Загрузка через плагин Fastlane

Вы можете использовать плагин Fastlane Ключ-АСТРОМ для автоматизации всего процесса, включая получение файлов dSYM из App Store Connect, предварительную обработку файлов и их загрузку в Ключ-АСТРОМ.

Для получения более подробной информации и инструкций ознакомьтесь с документацией плагина на GitHub.

Загрузка через веб-интерфейс

Через настройки среды

  1. В Ключ-АСТРОМ перейдите в Настройки > Веб- и мобильный мониторинг > Карты исходных данных и файлы символов.
  2. В разделе iOS или tvOS выберите Загрузить файлы.
  3. Выберите приложение из выпадающего списка.
  4. Укажите идентификатор пакета (bundleId), который можно найти в разделе Цель приложения > Общие > Идентификатор пакета.
  5. Введите версию пакета из раздела Цель приложения > Общие > Версия и строку версии пакета из раздела Цель приложения > Общие > Сборка.
  6. Выберите файл с символами и нажмите Загрузить.

Через настройки приложения

  1. Перейти в мобильную версию.
  2. Выберите мобильное приложение, которое хотите настроить.
  3. Выберите Дополнительно (…) > Редактировать в правом верхнем углу плитки с названием вашего приложения.
  4. В настройках приложения выберите Файлы символов.
  5. В разделе iOS или tvOS выберите Загрузить файлы.
  6. Укажите идентификатор пакета, версию пакета и строку версии.
  7. Выберите файл с символами и нажмите Загрузить.

Управление загруженными файлами символов

С помощью веб-интерфейса Ключ-АСТРОМ вы можете управлять ранее загруженными файлами сопоставления Android и файлами извлечения символов iOS или tvOS.

Просмотр файлов для конкретного приложения

  1. Перейти в мобильную версию.
  2. Выберите мобильное приложение, которое хотите настроить.
  3. Выберите Дополнительно (…) > Редактировать в правом верхнем углу плитки с названием вашего приложения.
  4. В настройках приложения выберите Файлы символов.

Просмотр всех загруженных файлов

  1. Перейдите в Настройки.
  2. Выберите Мониторинг веб-сайтов и мобильных устройств > Исходные карты и файлы символов.

На странице отображается текущий объем используемого хранилища и лимит хранилища. При достижении лимита хранилища Ключ-АСТРОМ начинает удаление исходных карт и файлов символов, начиная с самых старых.

Максимальный размер хранилища для исходных карт и файлов символов составляет 1 ГиБ.

Чтобы освободить место, вы можете вручную удалить ненужные файлы. Выберите Удалить в строке файла, который хотите удалить.

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

В качестве альтернативы вы можете использовать API мобильной символизации для просмотра, закрепления или удаления файлов символов.

Источник — https://doc.ruscomtech.ru/index.php?title=Загрузка_и_управление_файлами_символов_для_мобильных_приложений&oldid=6551