The real-world is messy, we can all use some help. This lab introduces you to IoT Edge's built-in troubleshooting tooling designed to help you uncover potential problem areas around connectivity and configuration. When all else fails, there's also functionality to provide an expert with all the information they'll need to root cause the problem, with one command.

You'll be using the IoT Edge VM you created in Deploy an IoT Edge VM lab.

Perform these steps on the IoT Edge device or VM.

‘iotedge check' is the first thing you should reach for in your toolbox when trying to figure out if your edge device is healthy. It is invoked simply by doing:

sudo iotedge check \
--diagnostics-image-name mcr.microsoft.com/azureiotedge-diagnostics:1.0.9-rc4

Now trying running it with --verbose

sudo iotedge check \
--diagnostics-image-name mcr.microsoft.com/azureiotedge-diagnostics:1.0.9-rc4 \
--verbose

Note, how it gives you hints about why a check didn't pass in the "caused by:" sections if you're curious about what the tool is looking for.

There are 3 board categories of checks performed:

• Configuration - These look for any errors in IoT Edge's primary configuration file which lives in /etc/iotedge/config.yaml by default (wait, wasn't yaml supposed to be human-friendly?). Additionally, it checks for other common mis-configurations in host components like DNS settings or time drift that can cause issues with cloud communication.
• Production readiness - Recommended settings for making your installation more resilient when running unsupervised for long periods.
• Connectivity - Checks to determine connectivity to the device's backing IoT Hub. Useful for finding issues like blocked ports and restrictive firewalls when operating in locked down environments with constrained internet access.

sudo iotedge check --help gives you a full listing of supported parameters.

Perform these steps on the IoT Edge device or VM.

If you want to see the most complete information ‘iotedge check' provides, run it with --output json (will take about 20-30 seconds, hit ‘q' to quit and return to terminal)

sudo iotedge check \
--diagnostics-image-name mcr.microsoft.com/azureiotedge-diagnostics:1.0.9-rc4 \
--output json | jq . | less

IoT Hub Device Provisioning Service (DPS) enables IoT Edge devices to provision at-scale with zero-touch.

In this configuration the devices's backing Hub is not specified in the edge's config.yaml. Therefore, at this time (Feb 2020), ‘iotedge check' is unable to discover the backing hub's host name to perform connectivity checks on DPS devices with its default run parameters.

Perform these steps on the IoT Edge device or VM.

Sometimes the error is in the module application layer or due to complex interactions between modules. This is when module developer or the experts in Azure Support are best suited to find the root cause. Since IoT Edge is essentially a collection of inter-connected microservices at the edge, it can be challenging to get a wholistic snapshot of all the moving parts. This is sometimes crucial to solve the problem.

Here is where iotedge support-bundle comes to rescue, enabling one to get all the relevant information from a number of different processes, in a single package with one simple command. Here's how to use it on your edge device to capture all relevant IoT Edge debug information since the last hour:

sudo iotedge support-bundle --since 1h

Examine the support-bundle package:

unzip ./support_bundle.zip -d sb
tree sb

As you can see, it includes ‘iotedge check' JSON output, module logs, iotedge and docker daemon logs as well as docker inspect and network information. More often than not, this information should be sufficient to debug even the thorniest of issues!

sudo iotedge support-bundle --help shows you the full set of supported command parameters.

And that's a wrap for this lab, where you learned about IoT Edge's essential local troubleshooting tools that help you get your device back in top condition! Next, you should explore the IoT Edge Remote Diagnostics and Logs lab.