Logboeken ophalen uit IoT Edge-implementaties

  • Artikel

Van toepassing op:IoT Edge 1.5-vinkje IoT Edge 1.5 Vinkje voor IoT Edge 1.4 IoT Edge 1.4

Belangrijk

IoT Edge 1.5 LTS en IoT Edge 1.4 LTS worden ondersteund releases. IoT Edge 1.4 LTS eindigt op 12 november 2024. Raadpleeg IoT Edge bijwerken als u een eerdere versie hebt.

Haal logboeken op uit uw IoT Edge-implementaties zonder fysieke of SSH-toegang tot het apparaat nodig te hebben met behulp van de directe methoden die zijn opgenomen in de IoT Edge-agentmodule. Directe methoden worden geïmplementeerd op het apparaat en kunnen vervolgens vanuit de cloud worden aangeroepen. De IoT Edge-agent bevat directe methoden waarmee u uw IoT Edge-apparaten op afstand kunt bewaken en beheren. De directe methoden die in dit artikel worden besproken, zijn algemeen beschikbaar met de release 1.0.10.

Zie Directe methoden begrijpen en aanroepen vanuit IoT Hub voor meer informatie over directe methoden, hoe u deze kunt gebruiken en hoe u deze implementeert in uw eigen modules.

De namen van deze directe methoden worden hoofdlettergevoelig verwerkt.

Hoewel dit niet vereist is, is de aanbevolen indeling voor logboekregistratie voor de beste compatibiliteit met deze functie:

<{Log Level}> {Timestamp} {Message Text}

{Timestamp} moet worden opgemaakt als yyyy-MM-dd HH:mm:ss.fff zzz, en {Log Level} moet de onderstaande tabel volgen, die de ernstniveaus afleidt van de ernstcode in de Syslog-standaard.

Weergegeven als Ernst
0 Noodgeval
1 Waarschuwing
2 Kritiek
3 Error
4 Waarschuwing
5 Opmerking
6 Informatief
7 Fouten opsporen

De Logger-klasse in IoT Edge fungeert als canonieke implementatie.

Modulelogboeken ophalen

Gebruik de directe methode GetModuleLogs om de logboeken van een IoT Edge-module op te halen.

Tip

Gebruik de since en until filteropties om het bereik van opgehaalde logboeken te beperken. Als u deze directe methode aanroept zonder grenzen, worden alle logboeken opgehaald die groot, tijdrovend of kostbaar kunnen zijn.

De pagina voor het oplossen van problemen met IoT Edge in Azure Portal biedt een vereenvoudigde ervaring voor het weergeven van modulelogboeken. Zie IoT Edge-apparaten bewaken en problemen oplossen vanuit Azure Portal voor meer informatie.

Deze methode accepteert een JSON-nettolading met het volgende schema:

    {
       "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" 
    }
Name Type Description
schemaVersion tekenreeks Ingesteld op 1.0
items JSON-matrix Een matrix met id en filter tuples.
id tekenreeks Een reguliere expressie die de modulenaam levert. Het kan overeenkomen met meerdere modules op een edge-apparaat. De .NET Regular Expressions-indeling wordt verwacht. Als er meerdere items zijn waarvan de id overeenkomt met dezelfde module, worden alleen de filteropties van de eerste overeenkomende id op die module toegepast.
filter JSON-sectie Logboekfilters die van toepassing zijn op de modules die overeenkomen met de id reguliere expressie in de tuple.
Staart geheel getal Het aantal logboekregels in het verleden dat moet worden opgehaald vanaf de meest recente versie. OPTIONELE.
Sinds tekenreeks Alleen logboeken retourneren sinds deze tijd, als een rfc3339-tijdstempel, UNIX-tijdstempel of een duur (dagen (d) uren (h) minuten (m)). Een duur voor één dag, 12 uur en 30 minuten kan bijvoorbeeld worden opgegeven als 1 dag 12 uur 30 minuten of 1d 12u 30m. Als beide tail en since zijn opgegeven, worden de logboeken opgehaald met de since waarde eerst. Vervolgens wordt de tail waarde toegepast op het resultaat en wordt het uiteindelijke resultaat geretourneerd. OPTIONELE.
Tot tekenreeks Retourneer alleen logboeken vóór de opgegeven tijd, als rfc3339-tijdstempel, UNIX-tijdstempel of duur (dagen (d) uren (h) minuten (m)). Een duur van 90 minuten kan bijvoorbeeld worden opgegeven als 90 minuten of 90 min. Als beide tail en since zijn opgegeven, worden de logboeken opgehaald met de since waarde eerst. Vervolgens wordt de tail waarde toegepast op het resultaat en wordt het uiteindelijke resultaat geretourneerd. OPTIONELE.
Loglevel geheel getal Filterlogboeklijnen die gelijk zijn aan het opgegeven logboekniveau. Logboeklijnen moeten de aanbevolen indeling voor logboekregistratie volgen en de standaard voor het ernstniveau syslog gebruiken. Als u wilt filteren op meerdere ernstwaarden op logboekniveau, moet u vervolgens afhankelijk zijn van regex-overeenkomsten, mits de module een consistente indeling volgt bij het vastleggen van verschillende ernstniveaus. OPTIONELE.
Regex tekenreeks Filter logboeklijnen die inhoud bevatten die overeenkomt met de opgegeven reguliere expressie met de .NET Regular Expressions-indeling . OPTIONELE.
Codering tekenreeks gzip of none. Standaard is none.
Contenttype tekenreeks json of text. Standaard is text.

Notitie

Als de inhoud van de logboeken groter is dan de limiet voor de antwoordgrootte van directe methoden, wat momenteel 128 kB is, retourneert het antwoord een fout.

Een geslaagd ophalen van logboeken retourneert een 'status': 200 gevolgd door een nettolading met de logboeken die zijn opgehaald uit de module, gefilterd op de instellingen die u in uw aanvraag opgeeft.

Voorbeeld:

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"
    }
'

Roep in Azure Portal de methode aan met de methodenaam GetModuleLogs en de volgende JSON-nettolading:

    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }

Schermopname van het aanroepen van directe methode GetModuleLogs in Azure Portal.

U kunt de CLI-uitvoer ook doorsluisen naar Linux-hulpprogramma's, zoals gzip, om een gecomprimeerd antwoord te verwerken. Voorbeeld:

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

Modulelogboeken uploaden

Gebruik de directe methode UploadModuleLogs om de aangevraagde logboeken te verzenden naar een opgegeven Azure Blob Storage-container.

Notitie

Gebruik de since en until filteropties om het bereik van opgehaalde logboeken te beperken. Als u deze directe methode aanroept zonder grenzen, worden alle logboeken opgehaald die groot, tijdrovend of kostbaar kunnen zijn.

Als u logboeken van een apparaat achter een gatewayapparaat wilt uploaden, moet u de API-proxy- en blobopslagmodules configureren op het apparaat in de bovenste laag. Deze modules routeren de logboeken van uw apparaat in de onderste laag via uw gatewayapparaat naar uw opslag in de cloud.

Deze methode accepteert een JSON-nettolading die vergelijkbaar is met GetModuleLogs, met de toevoeging van de sasUrl-sleutel:

    {
       "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" 
    }
Name Type Description
sasURL tekenreeks (URI) Shared Access Signature-URL met schrijftoegang tot Azure Blob Storage-container.

Een geslaagde aanvraag voor het uploaden van logboeken retourneert een 'status': 200 gevolgd door een nettolading met het volgende schema:

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Name Type Description
status tekenreeks Een vanNotStarted, Running, Completed, of FailedUnknown.
bericht tekenreeks Bericht als fout, lege tekenreeks anders.
correlationId tekenreeks Id om een query uit te voeren op de status van de uploadaanvraag.

Voorbeeld:

Met de volgende aanroep worden de laatste 100 logboekregels van alle modules geüpload, in gecomprimeerde JSON-indeling:

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"
    }
'

Met de volgende aanroep worden de laatste 100 logboeklijnen van edgeAgent en edgeHub geüpload met de laatste 1000 logboeklijnen van de tempSensor-module in niet-gecomprimeerde tekstindeling:

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"
    }
'

Roep in Azure Portal de methode aan met de methodenaam UploadModuleLogs en de volgende JSON-nettolading nadat u de sasURL hebt ingevuld met uw gegevens:

    {
       "schemaVersion": "1.0",
       "sasUrl": "<sasUrl>",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }

Schermopname van het aanroepen van directe methode UploadModuleLogs in Azure Portal.

Diagnostische gegevens van ondersteuningsbundel uploaden

Gebruik de directe methode UploadSupportBundle om een zip-bestand van IoT Edge-modulelogboeken te bundelen en te uploaden naar een beschikbare Azure Blob Storage-container. Met deze directe methode wordt de iotedge support-bundle opdracht op uw IoT Edge-apparaat uitgevoerd om de logboeken te verkrijgen.

Notitie

Als u logboeken van een apparaat achter een gatewayapparaat wilt uploaden, moet u de API-proxy- en blobopslagmodules configureren op het apparaat in de bovenste laag. Deze modules routeren de logboeken van uw apparaat in de onderste laag via uw gatewayapparaat naar uw opslag in de cloud.

Deze methode accepteert een JSON-nettolading met het volgende schema:

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }
Name Type Description
schemaVersion tekenreeks Ingesteld op 1.0
sasURL tekenreeks (URI) Shared Access Signature-URL met schrijftoegang tot Azure Blob Storage-container
Sinds tekenreeks Alleen logboeken retourneren sinds deze tijd, als een rfc3339-tijdstempel, UNIX-tijdstempel of een duur (dagen (d) uren (h) minuten (m)). Een duur voor één dag, 12 uur en 30 minuten kan bijvoorbeeld worden opgegeven als 1 dag 12 uur 30 minuten of 1d 12u 30m. OPTIONELE.
Tot tekenreeks Retourneer alleen logboeken vóór de opgegeven tijd, als rfc3339-tijdstempel, UNIX-tijdstempel of duur (dagen (d) uren (h) minuten (m)). Een duur van 90 minuten kan bijvoorbeeld worden opgegeven als 90 minuten of 90 min. OPTIONELE.
edgeRuntimeOnly boolean Indien waar, retourneert u alleen logboeken van de Edge-agent, Edge Hub en de Edge-beveiligingsdaemon. Standaard: onwaar. OPTIONELE.

Belangrijk

IoT Edge-ondersteuningsbundel kan persoonsgegevens bevatten.

Een geslaagde aanvraag voor het uploaden van logboeken retourneert een 'status': 200 gevolgd door een nettolading met hetzelfde schema als het antwoord UploadModuleLogs :

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Name Type Description
status tekenreeks Een vanNotStarted, Running, Completed, of FailedUnknown.
bericht tekenreeks Bericht als fout, lege tekenreeks anders.
correlationId tekenreeks Id om een query uit te voeren op de status van de uploadaanvraag.

Voorbeeld:

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
    }
'

Roep in Azure Portal de methode aan met de methodenaam UploadSupportBundle en de volgende JSON-nettolading nadat u de sasURL hebt ingevuld met uw gegevens:

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }

Schermopname die laat zien hoe u de directe methode UploadSupportBundle aanroept in Azure Portal.

Status van uploadaanvraag ophalen

Gebruik de directe methode GetTaskStatus om een query uit te voeren op de status van een aanvraag voor uploadlogboeken. De nettolading van de GetTaskStatus-aanvraag maakt gebruik van de correlationId aanvraag voor het uploaden van logboeken om de status van de taak op te halen. De correlationId waarde wordt geretourneerd als reactie op de aanroep van de directe methode UploadModuleLogs .

Deze methode accepteert een JSON-nettolading met het volgende schema:

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

Een geslaagde aanvraag voor het uploaden van logboeken retourneert een 'status': 200 gevolgd door een nettolading met hetzelfde schema als het antwoord UploadModuleLogs :

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Name Type Description
status tekenreeks Een van NotStarted, Running, Completed, , Failed'Geannuleerd' of Unknown.
bericht tekenreeks Bericht als fout, lege tekenreeks anders.
correlationId tekenreeks Id om een query uit te voeren op de status van de uploadaanvraag.

Voorbeeld:

az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }
'

Roep in Azure Portal de methode aan met de methodenaam GetTaskStatus en de volgende JSON-nettolading nadat u de GUID hebt ingevuld met uw gegevens:

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

Schermopname van het aanroepen van directe methode GetTaskStatus in Azure Portal.

Volgende stappen

Eigenschappen van de IoT Edge-agent en ioT Edge-hubmoduledubbels