Mobile Platform as a Service:Diagnóstico de cliente Android

O serviço de diagnóstico do cliente permite extrair remotamente logs de diagnóstico de usuários ou dispositivos específicos para investigar falhas e exceções. O console mPaaS oferece dois canais de entrega: Message Push Service (MPS) e Mobile Sync Service (MSS).

Para diagnosticar um cliente Android, siga estas etapas em ordem:

1. Inicializar o serviço de diagnóstico

2. Gravar logs de diagnóstico

3. Extrair logs do console

Pré-requisitos

Antes de começar, verifique se você tem:

• O componente Mobile Analysis Service integrado, com o relatório de logs funcionando corretamente. Para mais informações, consulte Integrar o Mobile Analysis Service em um cliente Android.

• O componente Message Push Service ou Mobile Sync Service integrado.

  • Se utilizar o canal Message Push Service, siga as etapas em Guia de Introdução para Integrar o Message Push Service a um cliente Android.

  • Caso utilize o canal Mobile Sync Service, consulte Integração com Android Integrar o Mobile Sync Service em um cliente Android.

Inicializar o serviço de diagnóstico

O serviço de diagnóstico aceita dois canais para extração de logs: Mobile Sync Service e Message Push Service. As etapas de inicialização variam conforme o canal.

Usar o canal Message Push Service

Após iniciar o aplicativo, conclua as seguintes etapas:

• Inicialize o serviço de push para estabelecer uma conexão persistente entre o cliente e o gateway do Message Push Service. O kit de desenvolvimento de software (SDK) de push mantém este canal próprio. Inicializar o SDK de push

• Vincule um ID de usuário. Este ID é definido pelo desenvolvedor e pode ser uma identidade do seu sistema de usuários ou outro parâmetro mapeável a um usuário específico, como uma conta ou número de telefone. Reportar um ID de usuário

Usar o canal Mobile Sync Service

Depois que o aplicativo for iniciado, chame os métodos a seguir para inicializar o canal de sincronização. É obrigatório chamar MPLogger.setUserId antes de inicializar o canal. A inicialização falhará se nenhum ID de usuário estiver definido.

• Acionar tarefas de diagnóstico por ID de usuário:

  // Set the userId
  MPLogger.setUserId(String userId);
  // Initialize the Sync channel. You must set the userId first, or the initialization will fail.
  MPDiagnose.initSyncChannel(Context context);

• Acionar tarefas de diagnóstico por ID de dispositivo:

  Nota

  O acionamento de tarefas de diagnóstico por dispositivo é suportado apenas na baseline 10.2.3.73 e versões posteriores.

  // Set the userId
  MPLogger.setUserId(String userId);
  // Initialize the Sync channel. You must set the userId first, or the initialization will fail.
  MPDiagnose.initSyncDeviceChannel(Context context);

Gravar logs de diagnóstico

O serviço de diagnóstico envia apenas logs gravados com MPLogger. Logs gerados via android.util.Log não são coletados. Substitua todas as chamadas de log pelos métodos equivalentes do MPLogger, que espelham a API Log padrão:

void verbose(String tag, String msg);
void debug(String tag, String msg);
void info(String tag, String msg);
void warn(String tag, String msg);
void warn(String tag, Throwable t);
void warn(String tag, String msg, Throwable tr);
void error(String tag, String msg);
void error(String tag, Throwable t);
void error(String tag, String msg, Throwable t);
void print(String tag, String msg);
void print(String tag, Throwable t);

O MPLogger grava no logcat apenas em builds de depuração. Os logs são suprimidos em builds de release. Os logs de diagnóstico são armazenados no dispositivo nos seguintes caminhos:

• Build de depuração: /sdcard/[PackageName]/applog. Se este caminho não permitir gravação, o SDK usará o caminho da build de release como fallback.

  Importante

  Se o targetSdkVersion for 30 ou superior e o dispositivo executar o Android 11 ou superior, o caminho de armazenamento será: /storage/emulated/0/Android/data/com.mpaas.demo/cache/[PackageName]/applog/.

• Build de release: /data/data/[PackageName]/files/applog.

// Maximum size of log files in MB
<meta-data android:name="category_applog_max_size" android:value="15" />
// Log storage duration in days
<meta-data android:name="category_applog_expires_time" android:value="7" />

Extrair logs do console

Com o cliente gravando logs via MPLogger, extraia os logs pelo console para investigar falhas ou exceções em um modelo de dispositivo específico ou para um usuário determinado.

Etapa 1: Crie uma tarefa de extração de logs

1. Faça login no console mPaaS e selecione o aplicativo desejado.

2. No painel de navegação à esquerda, clique em Mobile Analysis Service > Log Management.

3. Na aba Pull real-time logs, clique em Add.

4. Preencha os detalhes da tarefa. Defina o User ID com o identificador que seu app utiliza no sistema de login. Use o mesmo valor passado para MPLogger.setUserId(String userId) ou reportado via Message Push Service.

5. Clique em OK para criar a tarefa.

Etapa 2: Acionar a tarefa de extração de logs

1. Na lista de tarefas de extração de logs, localize a tarefa recém-criada, selecione um Trigger Channel e clique em Trigger na coluna Operations.

2. Atualize a página após alguns instantes para verificar o status da tarefa:

   • Task processed: Clique em View para baixe o log de diagnóstico.

   • Push/Sync service successfully called: A mensagem de upload foi enviada, mas o cliente ainda não recebeu ou enviou o log. Confirme se o processo do aplicativo continua em execução. Caso tenha parado, reinicie o app. Se o status não mudar após a reinicialização, consulte Solução de problemas.

Solução de problemas

Se a extração de logs falhar, siga as etapas correspondentes ao seu canal de entrega.

Usar o canal Message Push Service

1. No console mPaaS, acesse Message Push Service e envie uma mensagem comum para o ID de usuário alvo. Isso confirma se o canal Message Push Service está funcionando antes de depurar o fluxo de diagnóstico.

2. Se o canal estiver operacional, limpe o logcat, alterne para o processo de push e clique novamente em Trigger no console. Monitore o logcat buscando as tags a seguir.

3. Filtre por mPush14 para verificar se a mensagem de diagnóstico foi recebida. Se nenhuma mensagem aparecer, o canal de push pode estar desconectado.

4. Após confirmar o recebimento da mensagem, verifique no logcat se há evidências de encaminhamento ao MonitorService. Se um erro indicar que o ClientMonitorService não foi encontrado, atualize o SDK usando o plug-in mPaaS:

   • Para a baseline 10.1.32, faça upgrade para 10.1.68 e atualize o componente para a versão mais recente.

   • Para as baselines 10.1.60 ou 10.1.68, atualize o componente para a versão mais recente.

5. Depois de confirmar que o MonitorService iniciou, filtre por AlipayLogUploader para verificar a existência de um log de diagnóstico local. O log abaixo indica que há um log local disponível para upload.

   

   O log a seguir indica que não existe nenhum log de diagnóstico local.

   

   Caso não exista log local, verifique os dois pontos abaixo:

   • O intervalo de tempo definido na tarefa de extração deve ser de pelo menos 1 hora. Além disso, o aplicativo precisa estar em execução e gravando logs com MPLogger durante todo esse período.

   • O aplicativo deve declarar e solicitar dinamicamente esta permissão:

     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

6. Uma vez confirmada a existência do log local, filtre por HttpUpload para validar se o upload teve sucesso. Um responseCode igual a 200 confirma o êxito do envio.

Usar o canal Mobile Sync Service

1. Limpe o logcat, mude para o processo principal e inicialize o canal de sincronização. Filtre por isConnected para confirmar que a conexão do canal de sincronização foi estabelecida.

2. No console mPaaS, clique novamente em Trigger para a tarefa de diagnóstico. Filtre por MPDiagnose para verificar se a mensagem de diagnóstico foi recebida e se o MonitorService iniciou.

   Se nenhuma mensagem for recebida, confirme se o ID de usuário configurado no app corresponde ao ID inserido na tarefa de diagnóstico. Caso um erro informe que o ClientMonitorService não foi encontrado, atualize o SDK usando o plug-in mPaaS:

   • Para a baseline 10.1.32, faça upgrade para 10.1.68 e atualize o componente para a versão mais recente.

   • Para as baselines 10.1.60 ou 10.1.68, atualize o componente para a versão mais recente.

3. Após confirmar a inicialização do MonitorService, alterne para o processo de push e filtre por AlipayLogUploader para verificar a existência de um log de diagnóstico local. O log abaixo indica que há um log local disponível para upload. O log seguinte indica que não existe log de diagnóstico local.

   Se não houver log local, verifique os dois itens a seguir:

   • O intervalo de tempo definido na tarefa de extração deve ser de pelo menos 1 hora. Além disso, o aplicativo precisa estar em execução e gravando logs com MPLogger durante todo esse período.

   • O aplicativo deve declarar e solicitar dinamicamente esta permissão:

     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

4. Confirmada a existência do log local, filtre por HttpUpload para verificar se o upload foi bem-sucedido. Um responseCode igual a 200 confirma o sucesso do envio.