Recupere logs de implantações do Azure IoT Edge
Aplica-se a:
IoT Edge 1.5 IoT Edge 1.4
Importante
O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.
Recupere logs de suas implantações do IoT Edge sem precisar de acesso físico ou por SSH ao dispositivo, usando os métodos diretos incluídos no módulo do agente do IoT Edge. Os métodos diretos são implementados no dispositivo e depois podem ser invocados na nuvem. O agente do IoT Edge inclui métodos diretos que ajudam você a monitorar e gerenciar seus dispositivos do IoT Edge remotamente. Os métodos diretos discutidos neste artigo, em geral, estão disponíveis com a versão 1.0.10.
Para obter mais informações sobre os métodos diretos, como usá-los e como implementá-los nos seus módulos, confira Entender e invocar métodos diretos do Hub IoT.
Os nomes desses métodos diretos são tratados com diferenciação de maiúsculas e minúsculas.
Formato de log recomendado
Embora não seja necessário, para obter a melhor compatibilidade com esse recurso, o formato de log recomendado é:
<{Log Level}> {Timestamp} {Message Text}
A {Timestamp} deve ser formatada como yyyy-MM-dd HH:mm:ss.fff zzz, e o {Log Level} deve seguir a tabela abaixo, que deriva seus níveis de severidade do código de severidade no padrão do Syslog.
| Valor | Severidade |
|---|---|
| 0 | Emergência |
| 1 | Alerta |
| 2 | Crítico |
| 3 | Erro |
| 4 | Aviso |
| 5 | Notificação |
| 6 | Informativo |
| 7 | Depurar |
A classe de agente no Azure IoT Edge serve como implementação canônica.
Recuperar logs de módulo
Use o método direto GetModuleLogs para recuperar os logs de um módulo do Azure IoT Edge.
Dica
Use as opções since e until filtre as opções para limitar o intervalo de logs recuperados. Chamar esse método direto sem limites recupera todos os logs que podem ser grandes, demorados ou caros.
A página de solução de problemas do IoT Edge no portal do Azure fornece uma experiência simplificada para exibir logs de módulo. Para saber mais, consulte Monitorar e solucionar problemas de dispositivos IoT Edge no portal do Azure.
Esse método aceita uma carga JSON com o esquema a seguir:
{
"schemaVersion": "1.0",
"items": [
{
"id": "regex string",
"filter": {
"tail": "int",
"since": "string",
"until": "string",
"loglevel": "int",
"regex": "regex string"
}
}
],
"encoding": "gzip/none",
"contentType": "json/text"
}
| Nome | Tipo | Descrição |
|---|---|---|
| schemaVersion | string | Definida como 1.0 |
| itens | Matriz JSON | Uma matriz com tuplas id e filter. |
| ID | string | Uma expressão regular que fornece o nome do módulo. Ele pode corresponder a vários módulos em um dispositivo de borda. O formato de expressões regulares .NET é esperado. Caso haja vários itens cuja ID corresponda ao mesmo módulo, somente as opções de filtro da primeira correspondência de ID serão aplicadas a esse módulo. |
| filtro | Seção JSON | Filtros de log a serem aplicados aos módulos que correspondem à expressão id regular na tupla. |
| tail | Número inteiro | Número de linhas de log no passado para recuperar a partir da versão mais recente. OPCIONAL. |
| since | string | Retorne apenas logs desde esse momento, como um carimbo de data/hora rfc3339, um carimbo de data/hora UNIX ou uma duração de dias (d), horas (h) e minutos (m). Por exemplo, uma duração de um dia, 12 horas e 30 minutos pode ser especificada como 1 dia 12 horas 30 minutos ou 1d 12h 30m. Se ambos tail e since forem especificados, os logs serão recuperados usando o valor de since primeiro. Em seguida, o valor de tail é aplicado ao resultado e o resultado final é retornado. OPCIONAL. |
| until | string | Somente retorne logs antes do horário especificado, como um carimbo de data/hora rfc3339, um carimbo de data/hora UNIX ou uma duração de dias (d), horas (h) e minutos (m). Por exemplo, uma duração de 90 minutos pode ser especificada como 90 minutos ou 90m. Se ambos tail e since forem especificados, os logs serão recuperados usando o valor de since primeiro. Em seguida, o valor de tail é aplicado ao resultado e o resultado final é retornado. OPCIONAL. |
| nível de registro | Número inteiro | Filtre linhas de log iguais ao nível do log especificado. As linhas de log devem seguir o formato recomendado e usar o padrão de nível de severidade do Syslog. Caso você precise filtrar o conteúdo por vários valores de gravidade de nível de log, dependa da correspondência regex, desde que o módulo siga um formato consistente ao registrar diferentes níveis de gravidade em log. OPCIONAL. |
| regex | string | Filtre linhas de log que têm conteúdo correspondente à expressão regular especificada usando o formato de expressões regulares .NET. OPCIONAL. |
| encoding | string | gzip ou none. O padrão é none. |
| contentType | string | json ou text. O padrão é text. |
Observação
Se o conteúdo dos logs exceder o limite de tamanho de resposta dos métodos diretos, que atualmente é de 128 KB, a resposta retornará um erro.
Uma recuperação bem-sucedida de logs retorna um "status": 200 seguido por um conteúdo que contém os logs recuperados do módulo, filtrados pelas configurações especificadas na solicitação.
Por exemplo:
az iot hub invoke-module-method --method-name 'GetModuleLogs' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
'
No portal do Azure, invoque o método de nome GetModuleLogs e o seguinte conteúdo JSON:
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
Você também usar um pipe na saída da CLI para utilitários do Linux, como gzip, para processar uma resposta compactada. Por exemplo:
az iot hub invoke-module-method \
--method-name 'GetModuleLogs' \
-n <hub name> \
-d <device id> \
-m '$edgeAgent' \
--method-payload '{"contentType": "text","schemaVersion": "1.0","encoding": "gzip","items": [{"id": "edgeHub","filter": {"since": "2d","tail": 1000}}],}' \
-o tsv --query 'payload[0].payloadBytes' \
| base64 --decode \
| gzip -d
Carregar logs de módulo
Use o método direto UploadModuleLogs para enviar os logs solicitados para um contêiner de Armazenamento de Blobs do Azure especificado.
Observação
Use as opções since e until filtre as opções para limitar o intervalo de logs recuperados. Chamar esse método direto sem limites recupera todos os logs que podem ser grandes, demorados ou caros.
Se você quiser carregar logs a partir de um dispositivo por trás de um dispositivo de gateway, precisará ter o proxy da API e os módulos de armazenamento de blob configurados no dispositivo de camada superior. Esses módulos roteiam os logs do seu dispositivo de camada inferior por meio do dispositivo de gateway para o armazenamento na nuvem.
Esse método aceita um payload JSON semelhante a GetModuleLogs, com a adição da chave "sasURL":
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS URL",
"items": [
{
"id": "regex string",
"filter": {
"tail": "int",
"since": "string",
"until": "string",
"loglevel": "int",
"regex": "regex string"
}
}
],
"encoding": "gzip/none",
"contentType": "json/text"
}
| Nome | Tipo | Descrição |
|---|---|---|
| sasURL | cadeia de caracteres(URI) | URL de Assinatura de Acesso Compartilhado com acesso de gravação ao contêiner do Armazenamento de Blobs do Azure. |
Uma solicitação bem-sucedida para carregar logs retorna um "status": 200 seguido por um payload com o seguinte esquema:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nome | Tipo | Descrição |
|---|---|---|
| status | string | Um de NotStarted, Running, Completed, Failed ou Unknown. |
| message | string | Mensagem em caso de erro; caso contrário, cadeia de caracteres vazia. |
| correlationId | string | ID para consultar o status da solicitação de upload. |
Por exemplo:
A invocação a seguir carrega as últimas 100 linhas de log de todos os módulos no formato JSON compactado:
az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": ".*",
"filter": {
"tail": 100
}
}
],
"encoding": "gzip",
"contentType": "json"
}
'
A seguinte invocação carrega as últimas 100 linhas de log do edgeAgent e edgeHub com as últimas 1000 linhas de log do módulo tempSensor no formato de texto descompactado:
az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edge",
"filter": {
"tail": 100
}
},
{
"id": "tempSensor",
"filter": {
"tail": 1000
}
}
],
"encoding": "none",
"contentType": "text"
}
'
Na portal do Azure, invoque o método com o nome do método UploadModuleLogs e o seguinte conteúdo JSON, depois de preencher o sasURL com suas informações:
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
Carregue o diagnóstico do Pacote de Suporte
Use o método direto UploadSupportBundle para agrupar e carregar um arquivo zip de logs do módulo do Azure IoT Edge para um contêiner de Armazenamento de Blobs do Azure disponível. Esse método direto executa o comando iotedge support-bundle em seu dispositivo do IoT Edge para obter os logs.
Observação
Se você quiser carregar logs a partir de um dispositivo por trás de um dispositivo de gateway, precisará ter o proxy da API e os módulos de armazenamento de blob configurados no dispositivo de camada superior. Esses módulos roteiam os logs do seu dispositivo de camada inferior por meio do dispositivo de gateway para o armazenamento na nuvem.
Esse método aceita uma carga JSON com o esquema a seguir:
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| Nome | Tipo | Descrição |
|---|---|---|
| schemaVersion | string | Definida como 1.0 |
| sasURL | cadeia de caracteres(URI) | URL da Assinatura de Acesso Compartilhado com acesso de gravação ao contêiner do Armazenamento de Blobs do Azure |
| since | string | Retorne apenas logs desde esse momento, como um carimbo de data/hora rfc3339, um carimbo de data/hora UNIX ou uma duração de dias (d), horas (h) e minutos (m). Por exemplo, uma duração de um dia, 12 horas e 30 minutos pode ser especificada como 1 dia 12 horas 30 minutos ou 1d 12h 30m. OPCIONAL. |
| until | string | Somente retorne logs antes do horário especificado, como um carimbo de data/hora rfc3339, um carimbo de data/hora UNIX ou uma duração de dias (d), horas (h) e minutos (m). Por exemplo, uma duração de 90 minutos pode ser especificada como 90 minutos ou 90m. OPCIONAL. |
| edgeRuntimeOnly | boolean | Se verdadeiro, retorna apenas logs do Agente do Edge, Hub do Edge e o daemon de segurança do Edge. Padrão: falso. OPCIONAL. |
Importante
O pacote de suporte do IoT Edge pode conter informações de identificação pessoal.
Uma solicitação bem-sucedida para carregar logs retorna um "status": 200 seguido por um payload com o mesmo esquema que a resposta UploadModuleLogs:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nome | Tipo | Descrição |
|---|---|---|
| status | string | Um de NotStarted, Running, Completed, Failed ou Unknown. |
| message | string | Mensagem em caso de erro; caso contrário, cadeia de caracteres vazia. |
| correlationId | string | ID para consultar o status da solicitação de upload. |
Por exemplo:
az iot hub invoke-module-method --method-name 'UploadSupportBundle' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
'
Na portal do Azure, invoque o método com o nome do método UploadSupportBundle e o seguinte conteúdo JSON, depois de preencher o sasURL com suas informações:
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
Obter status da solicitação de carregamento
Use o método direto GetTaskStatus para consultar o status de uma solicitação de logs de upload. O payload da solicitação GetTaskStatus usa a correlationId da solicitação para carregar logs, para obter o status da tarefa. A correlationId é retornada em resposta à chamada de método direto UploadModuleLogs.
Esse método aceita uma carga JSON com o esquema a seguir:
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Uma solicitação bem-sucedida para carregar logs retorna um "status": 200 seguido por um payload com o mesmo esquema que a resposta UploadModuleLogs:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nome | Tipo | Descrição |
|---|---|---|
| status | string | Um entre NotStarted, Running, Completed, Failed, 'Cancelado' ou Unknown. |
| message | string | Mensagem em caso de erro; caso contrário, cadeia de caracteres vazia. |
| correlationId | string | ID para consultar o status da solicitação de upload. |
Por exemplo:
az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
'
Na portal do Azure, invoque o método com o nome do método GetTaskStatus e o seguinte conteúdo JSON, depois de preencher o GUID com suas informações:
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Próximas etapas
Propriedades do agente do IoT Edge e dos gêmeos de módulo do hub do IoT Edge