Learn about built-in features you can use to remotely diagnose IoT Edge deployments. The capabilities described in this lab are implemented by the edgeAgent module as remotely invokable direct methods. edgeAgent is part of the IoT Edge runtime and guaranteed to be on every IoT Edge device.

You'll explore both existing and pre-release functionality which will soon be generally available.

You'll be performing lab steps in Azure Cloud Shell against the IoT Edge VM you created in Deploy an IoT Edge VM lab as the edge device.

Perform these steps in Azure Cloud Shell.

Determining if a device is connected or not is common (remote) diagnostic first step. The edgeAgent module's ping direct method provides exactly this service. Invoke it on your IoT Edge device like so:

az iot hub invoke-module-method \
  -n iotlab-hub-$UNIQUESTRING \
  -d edge-device-$UNIQUESTRING \
  -m \$edgeAgent \
  --mn ping

If the method call returns "status": 200 with a null payload, it means there is connectivity between the agent and the IoT Hub.

Any other status indicates the module could not reached which most likely means the device is not connected to IoT Hub. The request might also time out if the edgeAgent is upgrading or otherwise down, but that is not very common.

Perform these steps in Azure Cloud Shell.

Sometimes, to fix something, you just have to turn if off and on again 😄. As the name suggests, you can restart any edge module by invoking this direct method on the edgeAgent. For example, restart the edgeHub module on your IoT Edge VM using:

az iot hub invoke-module-method \
  -n iotlab-hub-$UNIQUESTRING \
  -d edge-device-$UNIQUESTRING \
  -m \$edgeAgent \
  --mn RestartModule \
  --mp \
'
    {
        "schemaVersion": "1.0",
        "id": "edgeHub"
    }
'  

"status": 200 indicates restart succeeded, you can confirm this by SSH'ing into the VM and doing iotedge list. The Description column for edgeHub should indicate it recently restarted.

Perform these steps in Azure Cloud Shell.

The ability to remotely pull application logs from any connected IoT Edge device, on-demand, is very convenient for quick diagnostics. There are two methods in the edgeAgent that provide this service - UploadLogs and GetLogs. The former uploads logs to a specified Azure Blob Storage location while the latter returns the logs inline as part of the direct method response.

Rich filtering is supported via the direct method request schema to help efficiently retrieve logs of interest. Find more details in the feature documentation.

Let's use GetLogs to retrieve the recent logs from the tempSensor module in your IoT Edge VM:

az iot hub invoke-module-method \
  -n iotlab-hub-$UNIQUESTRING \
  -d edge-device-$UNIQUESTRING \
  -m \$edgeAgent \
  --mn GetLogs \
  --mp \
'
    {
        "schemaVersion": "1.0",
        "items": [
            {
                "id": "tempSensor",
                "filter": {
                    "tail": 10
                }
            }
        ],
        "encoding": "none",
        "contentType": "json"
    }
' | jq '.payload[].payload | fromjson | .[].text'  

Next, get recent logs from both edgeAgent and edgeHub:

az iot hub invoke-module-method \
  -n iotlab-hub-$UNIQUESTRING \
  -d edge-device-$UNIQUESTRING \
  -m \$edgeAgent \
  --mn GetLogs \
  --mp \
'
    {
        "schemaVersion": "1.0",
        "items": [
            {
                "id": "edge*",
                "filter": {
                    "tail": 10 
                }
            }
        ],
        "encoding": "none",
        "contentType": "json"
    }
' | jq '.payload[].payload | fromjson | .[].text'  

Now isn't that convenient!

Another one down! In this lab you worked with powerful new remote diagnostics features IoT Edge provides out of the box.