Coletar e interpretar dados de erro
Importante
Esta é a documentação do Azure Sphere (Legado). O Azure Sphere (Legado) será desativado em 27 de setembro de 2027 e os usuários devem migrar para o Azure Sphere (Integrado) até esse momento. Use o seletor de versão localizado acima do sumário para exibir a documentação do Azure Sphere (Integrado).
Os dados de erros e eventos são carregados diariamente no Serviço de Segurança do Azure Sphere. Qualquer pessoa que tenha acesso a um determinado locatário pode baixar os dados desse locatário. O relatório abrange todos os dispositivos no locatário.
Cada relatório contém um máximo de 1.000 eventos ou 14 dias de dados, o que for alcançado primeiro. Os dados podem ser gravados em um arquivo ou canalizados para um script ou aplicativo. A CLI pode retornar apenas 1.000 eventos. Use a API Pública do Azure Sphere para especificar o número máximo de eventos retornados na página.
Pode transferir dados sobre os erros e outros eventos que afetam os seus dispositivos das seguintes formas:
Usando o comando azsphere tenant download-error-report. Um arquivo CSV contendo informações sobre erros e eventos relatados por dispositivos dentro do locatário atual é baixado.
Usando a API Pública do Azure Sphere para relatórios de erros. O ponto de extremidade da API retorna um objeto JSON que você pode analisar de acordo com suas necessidades.
Nenhum dado de relatório de erros é coletado do RTApps. Se você quiser registrar erros do RTApps, precisará implementar comunicações entre os núcleos para comunicar erros do RTApps para o aplicativo de alto nível, a partir do qual os dados de erro podem ser registrados em serviços de rede. Consulte Comunicar com uma aplicação de alto nível e Comunicar com uma aplicação com capacidade em tempo real para obter detalhes.
Tipos de dados disponíveis
Os dados retornados para cada erro ou evento incluem o seguinte:
| Dados | Description |
|---|---|
| ID do Dispositivo | ID do dispositivo que encontrou o evento. |
| Tipo de Evento | Se o evento foi planejado ou não. As atualizações do sistema operacional e do aplicativo são consideradas eventos planejados, enquanto os erros são eventos não planejados. |
| Classe do evento | Componente de software que encontrou o evento: SO ou aplicativo. |
| Contagem de Eventos | Número de vezes que o evento ocorreu dentro do período delimitado por StartTime e EndTime. |
| Description | Informações sobre o evento. Este campo é genérico e varia consoante o evento e a sua origem. Para aplicações, ele pode conter o código de saída, status do sinal e código de sinal, mas o conteúdo exato do campo não é fixo. Isso contém informações sobre o evento e é a partir da primeira ocorrência do evento na janela de tempo. |
| Hora de Início | Data e hora (em UTC) em que a janela do evento começou. |
| Hora de Fim | Data e hora (em UTC) em que a janela do evento terminou. |
A Hora de Início e a Hora de Término definem uma janela de tempo durante a qual os dados do evento são agregados. A janela para qualquer grupo agregado de eventos pode ser de até 24 horas e o máximo é de 8 ocorrências por janela de tempo.
Eventos da aplicação
Os eventos de aplicativos incluem atualizações de aplicativos carregadas na nuvem, juntamente com falhas, saídas e outros tipos de falhas de aplicativos.
As atualizações de aplicativos são eventos planejados. Para um evento AppUpdate, o campo Description contém AppUpdate.
Falhas de aplicativos, saídas, falhas de inicialização e eventos semelhantes são eventos não planejados. Para um evento não planejado, o conteúdo do campo Descrição depende do aplicativo que encontrou o evento. A tabela a seguir lista os campos que podem estar presentes no campo Descrição de um evento não planejado.
| Dados | Description |
|---|---|
| exit_status ou exit_code | Status ou código de saída relatado pelo aplicativo. |
| signal_status | Inteiro que descreve o motivo de alto nível para a falha, retornado pelo sistema operacional. Você pode encontrar uma lista de status na documentação do Man 7 ou em outros recursos do Linux. |
| signal_code | Inteiro que indica o status de falha detalhado dentro do status do sinal pai. Consulte a documentação do Man 7 ou outros recursos do Linux para obter detalhes. |
| component_id | GUID do componente de software que falhou. |
| image_id | GUID da imagem que estava sendo executada no momento do erro. |
As informações específicas em uma descrição do AppCrash dependem da origem da falha. Para a maioria das falhas, a descrição é semelhante à seguinte:
AppCrash (exit_status=11; signal_status=11; signal_code=3; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=7053e7b3-d2bb-431f-8d3a-173f52db9675)
Em alguns casos, uma falha dispara dados de erro adicionais, como os seguintes, que complementam os dados no exemplo anterior:
AppCrash (pc=BEEED2EE; lr=BEEED2E5; sp=BEFFDE58; signo=11; errno=0; code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; pc_modulename+offset=appname+80000; lr_modulename+offset=app+100CC)
| Dados | Description |
|---|---|
| Pc | Contador de Programas. Aponta para o endereço da instrução que desencadeou a falha. |
| LR | Registo de Ligações. Possivelmente aponta para o endereço de retorno na função de chamada. |
| sp | Ponteiro de pilha. Aponta para a parte superior da pilha de chamadas. |
| Signo | Sinal POSIX. Indica o tipo de erro. |
| Errno | POSIX errno. Indica um erro. |
| code | Indica o status detalhado da falha dentro do status do sinal pai. |
| component_id | GUID do componente de software que falhou. |
| pc_modulename+deslocamento | Nome do módulo e deslocamento para o módulo que contém o código onde ocorreu a falha. |
| lr_modulename+deslocamento | Nome do módulo e deslocamento para o módulo que pode ter sido a função de chamada. |
Interpretar AppCrashes
Você pode encontrar a maioria das informações sobre um AppCrash no signal_status e signal_code. Siga estes passos:
- Usando a documentação do Man 7 para signal_status, primeiro veja a tabela rotulada "Numeração de sinal para sinais padrão". Na coluna x86/ARM, procure o valor atribuído ao signal_status no relatório
csvde erros. Uma vez encontrado, anote o nome do sinal correspondente na coluna mais à esquerda. - Role para cima até a tabela rotulada "Sinais padrão". Corresponda ao nome do sinal previamente determinado e use a tabela para reunir mais informações sobre o que o sinal indica.
- Na documentação do Man 7 para signal_code e o nome do Signal que você encontrou anteriormente, localize a lista correspondente de si_codes.
- Use o valor atribuído ao signal_code no arquivo de relatório
csvde erros para determinar qual código corresponde à mensagem de erro.
Por exemplo, considere a seguinte descrição do AppCrash:
AppCrash (exit_status=11; signal_status=11; signal_code=3; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=7053e7b3-d2bb-431f-8d3a-173f52db9675)
Usando a documentação do Man 7, você pode descobrir as seguintes informações adicionais sobre o AppCrash:
- Os sinais são descritos na 10ª seção da descrição da página do manual do Signal. Um signal_status de valor 11 corresponde a um sinal SIGSEGV.
- SIGSEGV indica que ocorreu uma referência de memória inválida (muitas vezes pode ser um ponteiro nulo).
- SI_Codes são descritos na 3ª seção da descrição da página do manual SigAction para cada signal_status. Embora a página não liste um número de índice para cada si_code, você pode contar a partir de cada categoria signal_status começando no índice 1. Olhando para a lista de si_codes para SIGSEGV (começando no índice 1), você pode ver que o terceiro corresponde a um SEGV_BNDERR.
- SEGV_BNDERR indica que ocorreu uma verificação de associação de endereço com falha.
Nota
Um AppCrash comumente encontrado inclui um valor de signal_status de 9, que é um sinal SIGKILL, juntamente com o SEND_SIG_PRIV si_code. Esse status indica que o sistema operacional matou o aplicativo porque excedeu seu limite de uso de memória. Para saber mais sobre os limites de memória do aplicativo, consulte Uso de memória em aplicativos de alto nível.
Interpretar AppExits
Quando um aplicativo é encerrado sem erro, os campos signal_status e signal_code não estão presentes e, em vez de um exit_status, a Descrição contém um código de saída:
AppExit (exit_code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=0a7cc3a2-f7c2-4478-8b02-723c1c6a85cd)
O AppExits pode ocorrer por vários motivos, como uma atualização de aplicativo, um dispositivo sendo desconectado ou o uso da API de desligamento, entre outros. É importante implementar códigos de saída para que você possa obter informações sobre os motivos de um AppExit.
Para interpretar AppExits, use o valor exit_code no campo Descrição do relatório de erros. Se seu aplicativo retornar um código de saída, você poderá usar o valor do exit_code no relatório de erros para determinar onde ou quando o erro ocorreu. Usando esse valor, pesquise dentro do código do aplicativo para ver qual mensagem de código de saída corresponde ao valor fornecido no relatório de erros. Em seguida, procure encontrar qual função no aplicativo retornou a mensagem de código de saída e por que ele fez isso. Ao visualizar a instrução return e seu contexto, você poderá descobrir o motivo do erro.
Eventos do SO
Os dados de erro também incluem eventos subjacentes de SO e hardware que podem afetar seu aplicativo, fazendo com que ele falhe ou reinicie. Esses eventos podem incluir o seguinte:
- Reinicializações de dispositivos não planejadas causadas por erros do kernel
- Atualizações do Cloud OS
- Problemas de hardware transitórios
Os eventos do sistema operacional são incluídos nos dados para ajudá-lo a determinar se os erros do aplicativo são o resultado de um problema de sistema operacional ou hardware ou refletem problemas com o próprio aplicativo. Se os dados do evento mostrarem que um dispositivo foi inicializado no Modo de Segurança, talvez seus aplicativos não consigam ser iniciados.
Explorar dados de erro
Se você planeja desenvolver scripts ou ferramentas para analisar dados de erro, mas não tem um grande número de dispositivos disponíveis para relatar erros, pode usar os aplicativos de exemplo do Azure Sphere para gerar esses dados para teste. O exemplo Tutorials/ErrorReporting no repositório de exemplos do Azure Sphere explica como analisar os erros relatados quando o aplicativo falha. Siga as instruções no readme para criar o exemplo usando o Visual Studio, Visual Studio Code ou a linha de comando.
Quando você implanta o aplicativo a partir da linha de comando sem um depurador, o sistema operacional o reinicia sempre que ele falha. Eventos semelhantes são agregados para que um dispositivo com falha frequente não mascare erros de outros e o máximo é de oito ocorrências por janela de tempo. Você pode implantar o exemplo a partir da linha de comando sem depuração, da seguinte maneira:
azsphere device sideload deploy --image-package <path to image package for the app>
Gerar e baixar relatório de erros
Os dados de erros e eventos são carregados diariamente no Serviço de Segurança do Azure Sphere. Verifique se o dispositivo Azure Sphere está conectado à Internet usando Wi-Fi ou Ethernet para se comunicar com o Serviço de Segurança do Azure Sphere.
Execute o seguinte comando para baixar o relatório para um arquivo CSV:
azsphere tenant download-error-report --destination error.csvAbra o arquivo CSV baixado e procure o ID do componente. Você verá uma descrição de erro semelhante à seguinte:
AppExit (exit_code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=6d2646aa-c0ce-4e55-b7d6-7c206a7a6363)
Você também pode usar a API Pública do Azure Sphere para relatórios de erros.
Nota
Pode levar até 24 horas para que os eventos relatados recentemente estejam disponíveis para download.
Se ocorrer um evento ou erro antes de o dispositivo se conectar a um servidor NTP, o carimbo de data/hora para o evento contido na telemetria carregada no AS3 pode estar incorreto. Isso será refletido em uma entrada incorreta na coluna StartTime no relatório subsequente baixado do AS3. Nessa situação, use o campo EndTime do relatório para ajudar a estimar quando o evento ocorreu. Este campo contém a hora em que os serviços na nuvem receberam a telemetria carregada e terá sempre uma data válida.
Formatar dados de erro
Os carimbos de data/hora e as colunas de dados no arquivo de relatório de erros são formatados de forma diferente de um arquivo CSV típico. Se quiser ver os resultados no Excel, pode reformatar os dados criando novas colunas e adicionando fórmulas personalizadas.
Para formatar os carimbos de data/hora no arquivo CSV exportado para trabalhar com o Excel:
Crie uma nova coluna de carimbo de data/hora e crie um formato personalizado para ela:
yyyy/mm/dd hh:mm:ssAdicione a seguinte fórmula às células na nova coluna Carimbo de data/hora, alterando o valor da célula F2 para corresponder à sua coluna e linha:
=(DATEVALUE(LEFT(RawErrorReport!F2,10))+TIMEVALUE(RIGHT(RawErrorReport!F2,8)))
Para dividir o campo Descrição em colunas separadas, siga estas etapas, alterando o valor da célula F2 para corresponder à sua coluna e linha:
Crie uma nova coluna chamada Shortname ou algo semelhante e adicione a seguinte fórmula às células:
=TRIM(LEFT(F2,FIND("(",F2)-1))Crie colunas nas quais os cabeçalhos row1 tenham os mesmos nomes que os valores dos parâmetros e adicione a seguinte fórmula às células em cada uma das colunas:
=IF(ISERROR(FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; "))), "", MID($F2, FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; ")) + (LEN(H$1) + 2), FIND("; ", SUBSTITUTE($F2,")","; "), FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; "))) - FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; ")) - (LEN(H$1) + 2)))