As falhas e ANRs no Android produzem um stack trace, que é um resumo da sequência de funções aninhadas chamadas no programa até o momento da falha. Esses resumos podem ajudar você a identificar e corrigir problemas na fonte.
Se o app ou jogo tiver sido desenvolvido com Java, e você usar o ProGuard para otimizar e ofuscar seu app, faça upload de um arquivo de mapeamento ProGuard para cada versão do app no Play Console. Se o app ou jogo for desenvolvido com código nativo, como C++, faça upload de um arquivo de símbolos de depuração para cada versão do app no Play Console. Isso facilita a análise e a correção de falhas e ANRs.
Importante: a desofuscação de apps compilados em Java só é possível com arquivos de mapeamento compatíveis com o ReTrace. Esse é o mesmo formato usado pelo ProGuard e R8.
Etapa 1: gerar um arquivo de desofuscação ou simbolização
Para desofuscar ou simbolizar falhas e ANRs em uma versão do app, primeiro é preciso gerar os arquivos necessários dessa versão. Gere e faça upload de um arquivo a cada nova versão do app para que os processos funcionem.
Java: gerar um arquivo de mapeamento ProGuardPara desofuscar stack traces do Java, primeiro é preciso gerar um arquivo de mapeamento ProGuard. Para saber como fazer isso, acesse o site do Google Developers.
Plug-in do Android para Gradle 4.1 e versões mais recentes
Se o projeto compilar um Android App Bundle, será possível incluir automaticamente o arquivo de símbolos de depuração. Para fazer isso, adicione o seguinte ao arquivo build.gradle do app:
android.defaultConfig.ndk.debugSymbolLevel = 'FULL'
Observação: o limite para o arquivo de símbolos de depuração é de 800 MB. Se o arquivo for muito grande, use SYMBOL_TABLE em vez de FULL para diminuir o tamanho dele.
Se o projeto compilar um APK, use a configuração de compilação do build.gradle acima para gerar o arquivo de símbolos de depuração separadamente. Faça upload manual do arquivo no Google Play Console, conforme descrito abaixo na Etapa 2: fazer upload de um arquivo de desofuscação ou simbolização. Como parte do processo de compilação, o Plug-in do Android para Gradle gera o arquivo no seguinte local do projeto:
app/build/outputs/native-debug-symbols/nome-da-variante/native-debug-symbols.zip
Plug-in do Android para Gradle 4.0 e versões anteriores (e outros sistemas de compilação)
Como parte do processo de compilação de um pacote de apps ou de um APK, o Plug-in do Android para Gradle mantém uma cópia das bibliotecas com símbolos de depuração em um diretório do projeto. O diretório segue uma estrutura semelhante a esta:
app/build/intermediates/cmake/universal/release/obj
├── armeabi-v7a/
│ ├── libgamenegine.so
│ ├── libothercode.so
│ └── libvideocodec.so
├── arm64-v8a/
│ ├── libgamenegine.so
│ ├── libothercode.so
│ └── libvideocodec.so
├── x86/
│ ├── libgamenegine.so
│ ├── libothercode.so
│ └── libvideocodec.so
└── x86_64/
├── libgameengine.so
├── libothercode.so
└── libvideocodec.so
Observação: se você usar outro sistema de compilação, poderá modificá-lo para armazenar bibliotecas com símbolos de depuração em um diretório com a estrutura necessária acima.
- Compacte o conteúdo do diretório:
$ cd app/build/intermediates/cmake/universal/release/obj$ zip -r symbols.zip .
- Faça upload manual do arquivo symbols.zip no Play Console, conforme descrito abaixo na Etapa 2: fazer upload de um arquivo de desofuscação ou simbolização.
O limite para o arquivo de símbolos de depuração é de 800 MB. Se o arquivo for muito grande, é provável que os arquivos .so tenham uma tabela de símbolos (nomes de função), além de informações de depuração DWARF (nomes de arquivos e linhas de código). Eles não são necessários para simbolizar o código e podem ser removidos com este comando:
$OBJCOPY --strip-debug lib.so lib.so.sym
Observação: o $OBJCOPY direciona para a versão específica da ABI que está passando pela remoção dos símbolos de depuração, por exemplo: ndk-bundle/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objcopy
Etapa 2: fazer upload de um arquivo de desofuscação ou simbolização
Para desofuscar ou simbolizar as falhas e os ANRs do app para uma versão dele, é preciso fazer upload dos arquivos de desofuscação ou simbolização para cada versão.
Importante: essa etapa é obrigatória somente para os desenvolvedores que usam APKs. Se você usa um pacote de apps e o Plug-in do Android para Gradle 4.1 ou versões mais recentes, não precisará fazer nada. Pegaremos automaticamente o arquivo de desofuscação do pacote, e você poderá pular para a Etapa 3: visualizar os stack traces de falhas desofuscados. Saiba mais sobre os pacotes de apps no site para desenvolvedores Android.
Fazer upload de arquivos usando o Play ConsolePara fazer upload de um arquivo de desofuscação ou simbolização, siga estas etapas:
- Abra o Play Console.
- Selecione um app.
- No menu à esquerda, selecione Testar e lançar > Pesquisador de pacotes de apps.
- Usando o seletor no canto superior direito, escolha o artefato relevante.
- Selecione a guia Downloads e role a tela para baixo até a seção "Recursos".
- Clique na seta de upload do arquivo de mapeamento ou símbolos de depuração, conforme aplicável, para fazer upload do arquivo de desofuscação ou simbolização da versão do app.
Para fazer upload de arquivos com a API Google Play Developer, acesse o site do Google Developers.
Etapa 3: visualizar os stack traces de falhas desofuscados
Ao fazer upload de um arquivo de mapeamento ProGuard ou de símbolos de depuração para uma versão do app, as falhas e os ANRs que ocorrerem depois disso serão desofuscados. Na página Falhas e ANRs do app, revise os stack traces desofuscados para identificar os problemas individuais.
- Abra o Play Console.
- Selecione um app.
- No menu à esquerda, selecione Monitorar e melhorar > Android vitals > Falhas e ANRs.
- Selecione uma falha.
- Na seção "Stack traces", você verá o que está desofuscado e simbolizado.
Importante: somente as falhas e ANRs posteriores ao upload do arquivo de mapeamento da versão do app serão desofuscados. As falhas e ANRs de uma versão do app que ocorreram antes do upload do respectivo arquivo de mapeamento não serão desofuscados.
Perguntas frequentes
Não quero usar a desofuscação nem a simbolização do Play Console. Posso fazer isso off-line?O Play Console usa o ndk-stack para simbolizar stack traces de apps nativos e o ReTrace para falhas do Java. Se você optar por não compartilhar os arquivos de desofuscação, poderá copiar as pilhas de falhas ofuscadas do Play Console e usar a ferramenta adequada off-line para simbolização. No entanto, esse processo precisa ser feito manualmente para cada pilha de falhas, o que o torna lento e demorado. Ao enviar os arquivos de desofuscação, o Play Console vai fazer isso por você.
Ao fazer upload de um arquivo de mapeamento ProGuard ou de símbolos de depuração para uma versão do app, somente as falhas e os ANRs que ocorrerem depois disso vão ser desofuscados. Será preciso aguardar que novos ANRs e falhas sejam informados pelos dispositivos dos usuários para que eles sejam desofuscados no Play Console.
Isso é causado pelo upload de um arquivo incompleto de desofuscação ou simbolização. Inclua os arquivos de simbolização para todo o app, especialmente se você usar um processo de compilação complexo ou de vários estágios. Um dos motivos mais comuns para a desofuscação parcial é o uso de uma biblioteca de terceiros. Nesse caso, talvez você consiga os arquivos de desofuscação do provedor da biblioteca.
Sem os arquivos de desofuscação, você verá a mesma falha ou ANR separadamente para dispositivos com diferentes arquiteturas (32 ou 64 bits) e processadores (ARM ou Intel). Com os arquivos, podemos agrupar esses erros e oferecer uma perspectiva melhor das falhas e ANRs mais impactantes para o app.
Caso você se esqueça de fazer upload do arquivo para uma nova versão do app, as falhas e os ANRs voltarão a ser ofuscados. Siga as instruções acima para fazer upload agora. Ao fazer upload de um arquivo de mapeamento ProGuard ou de símbolos de depuração para uma versão do app, somente as falhas e os ANRs que ocorrerem depois disso serão desofuscados. Será preciso que novas falhas e ANRs sejam informados pelos dispositivos dos usuários para vê-los desofuscados no Play Console.
Para evitar o risco de esquecer o upload do arquivo, mude o processo de compilação para usar os pacotes de apps com o Plug-in do Android para Gradle 4.1 ou versões mais recentes. Nesse caso, será possível incluir automaticamente o arquivo de símbolos de depuração no pacote de apps seguindo as instruções no site para desenvolvedores Android.
Se você fizer upload do arquivo errado para uma versão do app, as falhas e os ANRs voltarão a ser ofuscados. Para fazer upload de uma versão corrigida, siga estas etapas:
- Abra o Play Console.
- Selecione um app.
- No menu à esquerda, selecione Testar e lançar > Pesquisador de pacotes de apps.
- Usando o seletor no canto superior direito, escolha o artefato relevante.
- Selecione a guia Downloads e role a tela para baixo até a seção "Recursos".
- Clique no ícone de exclusão ao lado do arquivo incorreto.
- Após excluir a versão errada, clique no ícone de upload e envie o arquivo correto.
Ao fazer upload do arquivo correto de mapeamento ProGuard ou de símbolos de depuração para uma versão do app, somente as falhas e os ANRs que ocorrerem depois disso serão desofuscados. Será preciso que novas falhas e ANRs sejam informados pelos dispositivos dos usuários para vê-los desofuscados no Play Console.
Dica: para evitar o risco de fazer upload de uma versão incorreta do arquivo, passe a fazer o processo de compilação usando pacotes de apps com o Plug-in do Android para Gradle 4.1 ou versões mais recentes. Nesse caso, será possível incluir automaticamente o arquivo de símbolos de depuração no pacote de apps seguindo as instruções no site para desenvolvedores Android.
Acesse o site para desenvolvedores Android para ver como começar.
Sim.
Ocasionalmente, o sistema encontra um ANR, mas não consegue coletar o stack trace. Nesse caso, o ANR é exibido para dar a você uma visão mais completa da estabilidade do app, mas não é possível mostrar o stack trace. Os ANRs sem stack traces são agrupados por tipo e atividade. Revisar e corrigir ANRs semelhantes pode ajudar a reduzir o número mesmo sem esses dados.