Azure - Troubleshooting
Troubleshooting of Azure IoT Hub instances and items
Table of Contents
Troubleshooting in AzureAnalyzing telemetry metricsMonitor IoT Hub events & messagesError messagesSporadic "No network connection"Incorrect JSON responseThis article will describe how to troubleshoot if data is not streaming into Azure IoT Hub from SIA and how to validate the data and connection.
Troubleshooting in Azure
If there are not errors on SIA but you cannot figure out whether or not the data is arriving in Azure we should start troubleshooting in Azure.
Often this is due to Azure is not recognizing the message (e.g. JSON format being wrong) or you might have forgot to set up a job that processes and forwards the data in Azure.
First thing, lets check we are receiving data.
Analyzing telemetry metrics
Caution
Viewing the metrics is not suitable if you have multiple devices as they will also appear on the metric
In Azure IoT Hub you have metrics available for the given hub. This metrics can show you valuable information such as telemetry messages being sent.
Viewing the amount of telemetry messages sent to the IoT Hub is a really basic way of validating it works and cannot give you further information than data is coming in. Please keep in mind if you have multiple devices which are receiving data on the Hub this metrics might not be suitable to use as their telemetry messages will also appear.
- In Azure Portal go to IoT Hub and select the Hub where your IoT device belongs to
- In the left menu go to Monitoring ➡ Metrics
- Add new metric
- Metric: Telemtry messages sent
- Aggregation: Sum (you can use any of those available)
- Select a suitable time range in in the top right of the metric
- Analyze the metric and validate the data graph
Info
It can take a few minutes before the metrics start to update
Monitor IoT Hub events & messages
Monitoring the events and messages that are streaming into IoT Hub is a great way of debugging the data is coming in but also to validate the format of the message is correct.
To monitor the events and messages you will have to use the built-in Azure Cloud Shell or install Azure CLI tools on your desktop. We recommend for starters to use the built-in Azure Cloud Shell in the portal.
For further information of Azure CLI on your desktop and the Azure Cloud Shell check these articles:
Info
Using the Azure Cloud Shell you might need to add storage to your account and install azure-iot extensions
To monitor the events and messages do the following if you are using the Azure Cloud Shell:
- Click the terminal icon in the portals upper right corner next to your username.
- When the Cloud Shell is ready use one of the following command to monitor all messages arriving into the IoT Hub
az iot hub monitor-events --hub-name HubName az iot hub monitor-events --login "ConnectionString"
- Or to monitor for a specific Device, which is very useful if you have many devices and are getting a lot of messages
az iot hub monitor-events --hub-name HubName --device-id DeviceID az iot hub monitor-events --login "ConnectionString" --device-id DeviceID
- To get a full list of parameters and help use
az iot hub monitor-events -h
- HubName and DeviceID can be located in IoT Hub ➡ IoT Devices
- HubName is your IoT Hub name
- DeviceID is the ID of the Device
- ConnectionString is the connection string of your IoT Hub or device. Learn how to find ConnectionString here
The following video demonstrates how to monitor all the messages received in the IoT Hub.
Error messages
This section will describe most of the common errors and faults encountered using the Azure IoT Hub Connector.
Instance
Caution
If the SharedAccessKey in the Connection String is invalid this is not returning any error. If no data is arriving to the IoT Hub and no errors are present at SIA then double check the Connection String and validate the SharedAccessKey inside it.
| Error message | Description | Solution |
|---|---|---|
| No network connection | No network connection or no route to the IoT Hub. |
|
| Failed to connect to IoT Hub. Check your connection string in the address field | The format of the Connection String is invalid. The expected format is: HostName=HubName.azure-devices.net;DeviceId=DeviceID;SharedAccessKey=Primary/SecondaryKey | Copy the Connection String from the IoT Hub device into the address field on the instance and validate the format is correct. |
| Failed to get handle | Azure IoT instances on the same installation cannot have different authentication types. For example, one instance using Symmetric Key (SAS) and another using x509 Certificate. | In case multiple Azure IoT Hub Instances are used on the same installation make sure they use same authentication type. |
Sporadic "No network connection"
- Symptom:
- Multiple identical messages are received
- Logs show multiple lines of "NO_NETWORK_CONNECTION" errors
- Issue:
- The network is not fast enough to handle the complete transmission and response of the package.
This might be further aggravated by using X2 ethernet port which does not have the same bandwidth as X1
- The network is not fast enough to handle the complete transmission and response of the package.
- Solution:
- Increase the timeout of the instance, this will allow for more time to get a response from the network
Incorrect JSON response
- Symptom:
- The returned body message is an array with numbers instead of a proper JSON response with strings
- Issue:
- The payload sent to the cloud is not properly formatted (for example, in JSON format)
- Solution:
- Make sure strings are properly wrapped in quotes ("), including SIA instance/item parameters (for example: "%DEVICE.NAME%", "%ITEM.VALUE%"), unless the content of the variable itself is wrapped in quotes (making it a valid string needed by the JSON format)
- Use an online JSON validator (for example: https://jsonlint.com/)