Desofuscar ou simbolizar stack traces de falhas

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 foi desenvolvido com Java, e você usa o ProGuard para otimizar e ofuscar os arquivos APK, faça upload de um arquivo de mapeamento ProGuard para cada versão do app no Play Console. Se o app ou jogo foi 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 ProGuard

Para desofuscar stack traces do Java, primeiro é preciso gerar um arquivo de mapeamento ProGuard. Para saber como fazer isso, acesse o site do Google Developers.

Código nativo: gerar um arquivo de símbolos de depuração

Plug-in do Android para Gradle 4.1 e versões posteriores

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 300 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/variant-name/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 APK ou Android App Bundle, o Plug-in do Android para Gradle mantém uma cópia das bibliotecas sem 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 sem símbolos de depuração em um diretório com a estrutura necessária acima.

  1. Compacte o conteúdo do diretório:
    • $ cd app/build/intermediates/cmake/universal/release/obj
    • $ zip -r symbols.zip .
  2. 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 300 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 o Android App Bundle ou o Plug-in do Android para Gradle 4.1 ou versões posteriores, 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 com o Play Console

Para fazer upload de um arquivo de desofuscação ou simbolização, siga estas etapas:

  1. Abra o Play Console.
  2. Selecione um app.
  3. No menu à esquerda, selecione Versão > Dispositivos e versões > Explorador de app bundle.
  4. Usando o seletor no canto superior direito, escolha o artefato relevante.
  5. Selecione a guia Downloads e role para baixo até a seção "Recursos".
  6. 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.
Fazer upload de arquivos com a API Google Play Developer

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.

  1. Abra o Play Console.
  2. Selecione um app.
  3. No menu à esquerda, selecione Qualidade > Android vitals > Falhas e ANRs.
  4. Selecione uma falha.
  5. 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 os stacks de falhas ofuscados do Play Console e usar a ferramenta apropriada off-line para simbolizá-las. No entanto, esse processo precisa ser feito manualmente para cada stack de falhas, tornando-o lento e demorado. Ao fornecer os arquivos de desofuscação, o Play Console fará isso por você.

Fiz upload do arquivo de desofuscação ou simbolização. Por que minhas falhas e ANRs ainda estão ofuscados?

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 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.

Após fazer upload do arquivo de desofuscação ou simbolização, por que minhas falhas e ANRs só estão parcialmente desofuscados?

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.

Após fazer upload do arquivo de desofuscação ou simbolização, por que parece haver menos falhas e ANRs, mas os que aparecem são mais graves?

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.

O que acontecerá se eu me esquecer de fazer upload do arquivo?

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 ANRs que ocorrerem depois disso serão desofuscados. Será preciso que novos ANRs e falhas sejam informados pelos dispositivos dos usuários para ver esses problemas desofuscados no 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.

O que acontecerá se eu enviar o arquivo errado?

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:

  1. Abra o Play Console.
  2. Selecione um app.
  3. No menu à esquerda, selecione Versão > Dispositivos e versões > Explorador de app bundle.
  4. Usando o seletor no canto superior direito, escolha o artefato relevante.
  5. Selecione a guia Downloads e role para baixo até a seção "Recursos".
  6. Clique no ícone de exclusão ao lado do arquivo incorreto.
  7. 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 novos ANRs e falhas sejam informados pelos dispositivos dos usuários para ver esses problemas desofuscados no Console.

Dica: para evitar o risco de fazer upload de uma versão incorreta 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.

Estou usando APKs no momento. Como mudar para pacotes de apps?

Acesse o site para desenvolvedores Android para ver como começar.

Meu app tem código nativo e Java. Posso fazer upload de um arquivo de simbolização nativo e de um arquivo de desofuscação Java?

Sim.

Isso foi útil?
Como podemos melhorá-lo?

Precisa de mais ajuda?

Faça login e veja mais opções de suporte para resolver o problema rapidamente.