As falhas de sistema e os ANRs no Android produzem um rastreio de pilha, que é um instantâneo da sequência das chamadas de funções aninhadas no seu programa até ao momento em que ocorreu uma falha. Estes instantâneos podem ajudar a identificar e corrigir quaisquer problemas na origem.
Se o seu jogo ou app foi desenvolvido com Java e usa o ProGuard para otimizar e ocultar a sua app, pode carregar um ficheiro de mapeamento ProGuard para cada versão da app na Play Console. Se o seu jogo ou app foi desenvolvido com código nativo, como o C++, pode carregar um ficheiro de símbolos de depuração para cada versão da app na Play Console. Deste modo, é mais fácil analisar e corrigir as falhas de sistema e os ANRs.
Importante: apenas os ficheiros de mapeamento compatíveis com ReTrace são suportados para desocultar apps compiladas em Java. Este é o mesmo formato utilizado pelo ProGuard ou R8.
Passo 1: gere um ficheiro de desocultação ou simbolização
Para desocultar ou simbolizar as falhas de sistema e os ANRs da sua app para uma versão da mesma, comece por gerar os ficheiros necessários para a mesma versão da app. Tem de gerar e carregar um ficheiro para cada nova versão da sua app para que a desocultação ou a simbolização funcionem.
Java: gere um ficheiro de mapeamento ProGuardPara desocultar os rastreios de pilhas Java, primeiro tem de gerar um ficheiro de mapeamento ProGuard. Para saber como o fazer, aceda ao site do Google Developers.
Versão 4.1 e posterior do plugin do Android para o Gradle
Se o seu projeto compilar um Android App Bundle, pode incluir automaticamente o ficheiro de símbolos de depuração no mesmo. Para incluir este ficheiro, adicione o seguinte ao ficheiro build.gradle da sua app:
android.defaultConfig.ndk.debugSymbolLevel = 'FULL'
Nota: o limite para o ficheiro de símbolos de depuração é de 800 MB. Se o rasto de símbolos de depuração for demasiado grande, use SYMBOL_TABLE em vez de FULL para reduzir o tamanho do ficheiro.
Se o seu projeto compilar um APK, utilize a definição de compilação build.gradle acima para gerar o ficheiro de símbolos de depuração separadamente. Carregue manualmente o ficheiro de símbolos de depuração para a Google Play Console conforme descrito abaixo no Passo 2: carregue um ficheiro de desocultação ou simbolização. Como parte do processo de compilação, o plugin do Android para o Gradle gera este ficheiro na seguinte localização do projeto:
app/build/outputs/native-debug-symbols/variant-name/native-debug-symbols.zip
Versão 4.0 e anterior do plugin do Android para o Gradle (e outros sistemas de compilação)
Como parte do processo de criação de um app bundle ou APK, o plugin do Android para o Gradle mantém uma cópia das bibliotecas com informações de depuração num diretório do projeto. Este diretório segue uma estrutura semelhante à seguinte:
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
Nota: se utilizar um sistema de compilação diferente, pode modificá-lo para armazenar as bibliotecas com informações de depuração num diretório com a estrutura necessária acima.
- Comprima o conteúdo deste diretório:
$ cd app/build/intermediates/cmake/universal/release/obj$ zip -r symbols.zip .
- Carregue manualmente o ficheiro symbols.zip para a Play Console conforme descrito abaixo no Passo 2: carregue um ficheiro de desocultação ou simbolização.
O limite para o ficheiro de símbolos de depuração é de 800 MB. Se o seu ficheiro for demasiado grande, é provável que os ficheiros .so contenham uma tabela de símbolos (nomes de funções), bem como informações de depuração DWARF (nomes de ficheiros e linhas de código). Estas não são necessárias para a simbolização do seu código e podem ser removidas através da execução do seguinte comando:
$OBJCOPY --strip-debug lib.so lib.so.sym
Nota: $OBJCOPY aponta para a versão específica da ABI cujas informações de depuração está a remover, por exemplo: ndk-bundle/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objcopy
Passo 2: carregue um ficheiro de desocultação ou simbolização
Para desocultar ou simbolizar as falhas de sistema e os ANRs da sua app para uma versão da mesma, tem de carregar os ficheiros de desocultação ou simbolização para cada versão da app.
Importante: este passo só é necessário para programadores que utilizem APKs. Se estiver a usar um app bundle e a versão 4.1 ou posterior do plugin do Android para o Gradle, não precisa de fazer nada. Iremos recolher automaticamente o ficheiro de desocultação a partir do pacote e pode avançar para o Passo 3: veja rastreios de pilhas de falhas de sistema desocultados. Pode saber mais acerca dos app bundles no site para programadores Android.
Carregue ficheiros através da Play ConsolePara carregar um ficheiro de desocultação ou simbolização:
- Abra a Play Console.
- Selecione uma app.
- No menu do lado esquerdo, selecione Lançamento > Explorador de app bundles.
- Com o selecionador no canto superior direito, escolha o artefacto relevante.
- Selecione o separador Transferências e desloque o ecrã para baixo até à secção "Recursos".
- Clique na seta de carregamento para o ficheiro de mapeamento ou os símbolos de depuração, conforme aplicável, para carregar o ficheiro de desocultação ou simbolização para a versão da sua app.
Para carregar ficheiros através da API para programadores do Google Play, aceda ao site Google Developers.
Passo 3: veja rastreios de pilhas de falhas de sistema desocultados
Depois de carregar um ficheiro de mapeamento ProGuard ou um ficheiro de símbolos de depuração para uma versão da sua app, as falhas de sistema e os ANRs que ocorrerem posteriormente serão desocultados. Pode rever os rastreios de pilhas desocultados de falhas de sistema e ANRs individuais na página Falhas de sistema e ANRs da app.
- Abra a Play Console.
- Selecione uma app.
- No menu do lado esquerdo, selecione Qualidade > Android vitals > Falhas de sistema e ANRs.
- Selecione uma falha de sistema.
- Na secção "Rastreios de pilha", verá os rastreios de pilhas desocultados e simbolizados.
Importante: depois de carregar um ficheiro de mapeamento para uma versão da sua app, apenas as falhas de sistema e os ANRs futuros dessa versão da app serão desocultados. As falhas de sistema e os ANRs de uma versão da sua app que ocorram antes de ter carregado o respetivo ficheiro de mapeamento não serão desocultados.
Perguntas frequentes
Não pretendo utilizar a desocultação/simbolização da Play Console. Posso simplesmente fazê-lo offline?A Play Console usa ndk-stack para simbolizar rastreios de pilhas para apps nativas e ReTrace para falhas de sistema Java. Se optar por não partilhar os seus ficheiros de desocultação, pode copiar as pilhas de falhas de sistema ocultas da Play Console e usar a ferramenta adequada offline para realizar a simbolização das mesmas. No entanto, este processo tem de ser realizado manualmente para cada pilha de falhas de sistema, o que o torna lento e demorado. Ao fornecer os seus ficheiros de desocultação, a Play Console trata disso por si.
Depois de carregar um ficheiro de mapeamento ProGuard ou um ficheiro de símbolos de depuração para uma versão da sua app, apenas as falhas de sistema e os ANRs que ocorrerem posteriormente são desocultados. Tem de dar tempo para que os novos ANRs e falhas de sistema sejam comunicados pelos dispositivos dos utilizadores antes de ver os ANRs e as falhas de sistema desocultados na Play Console.
Isto deve-se ao carregamento de um ficheiro de desocultação/simbolização incompleto. Certifique-se de que inclui os ficheiros de simbolização para toda a app, especialmente se utilizar um processo de compilação complexo ou de várias etapas. Um dos motivos mais comuns para a desocultação parcial é a utilização de uma biblioteca de terceiros. Neste caso, poderá obter os ficheiros de desocultação a partir do fornecedor da biblioteca.
Sem ficheiros de desocultação, o mesmo ANR ou falha de sistema num dispositivo de 32 bits e 64 bits ou num dispositivo ARM e Intel será apresentado separadamente. Ao fornecer ficheiros de desocultação, podemos agrupar estas falhas de sistema, fornecendo-lhe uma melhor perspetiva dos ANRs e falhas de sistema de maior impacto para a sua app.
Caso se esqueça de carregar o ficheiro para uma nova versão da sua app, as falhas de sistema e os ANRs voltam a ficar ocultos. Siga as instruções acima para o carregar agora. Depois de carregar um ficheiro de mapeamento ProGuard ou um ficheiro de símbolos de depuração para uma versão da sua app, apenas as falhas de sistema e os ANRs que ocorrerem posteriormente são desocultados. Tem de dar tempo para que os novos ANRs e falhas de sistema sejam comunicados pelos dispositivos dos utilizadores antes de ver os ANRs e as falhas de sistema desocultados na Play Console.
Para evitar o risco de se esquecer de carregar o ficheiro, considere alterar o processo de compilação para utilizar app bundles com a versão 4.1 ou posterior do plugin do Android para o Gradle. Neste caso, pode incluir automaticamente o ficheiro de símbolos de depuração no app bundle ao seguir as instruções no site para programadores Android.
Se carregar o ficheiro errado para uma versão da sua app, as falhas de sistema e os ANRs voltam a ficar ocultos. Para carregar uma versão corrigida:
- Abra a Play Console.
- Selecione uma app.
- No menu do lado esquerdo, selecione Lançamento > Explorador de app bundles.
- Com o selecionador no canto superior direito, escolha o artefacto relevante.
- Selecione o separador Transferências e desloque o ecrã para baixo até à secção "Recursos".
- Clique no ícone para eliminar junto ao ficheiro de desocultação ou simbolização incorreto.
- Assim que a versão incorreta for eliminada, clique no ícone de carregamento e carregue o ficheiro correto para a versão da sua app.
Depois de carregar o ficheiro de mapeamento ProGuard ou o ficheiro de símbolos de depuração correto para uma versão da sua app, apenas as falhas de sistema e os ANRs que ocorrerem posteriormente serão desocultados. Tem de dar tempo para que os novos ANRs e falhas de sistema sejam comunicados pelos dispositivos dos utilizadores antes de ver os ANRs e as falhas de sistema desocultados na Play Console.
Sugestão: para evitar o risco de carregar uma versão incorreta do ficheiro, considere alterar o processo de compilação para utilizar app bundles com a versão 4.1 ou posterior do plugin do Android para o Gradle. Neste caso, pode incluir automaticamente o ficheiro de símbolos de depuração no app bundle ao seguir as instruções no site para programadores Android.
Visite o site para programadores Android para começar.
Sim.
Ocasionalmente, o sistema encontra um ANR, mas não consegue recolher o rastreio de pilha. Neste caso, o ANR é apresentado para lhe proporcionar uma vista mais completa da estabilidade da sua app, mas não é possível apresentar o rastreio de pilha. Os ANRs sem rastreios de pilhas são agrupados por tipo e atividade, pelo que a análise e correção de ANRs semelhantes pode ajudar a reduzir o número sem rastreios de pilhas.