Merge pull request #192663 from JimacoMS4/improve-linkage-and-info-for-tracking-device-connections

Add better linkage and queries to detect device connectivity

Author: laurabren

articles/iot-hub/TOC.yml

@@ -388,7 +388,7 @@
           href: iot-hub-monitoring-notifications-with-azure-logic-apps.md     
     - name: Troubleshoot and problem solution
       items:
-        - name: Device disconnects
+        - name: Troubleshoot device connectivity
           href: iot-hub-troubleshoot-connectivity.md
         - name: Troubleshoot message routing
           href: troubleshoot-message-routing.md

articles/iot-hub/iot-hub-devguide-identity-registry.md

@@ -80,7 +80,7 @@ The IoT Hub identity registry contains a field called **connectionState**. Only
 If your IoT solution needs to know if a device is connected, you can implement the *heartbeat pattern*.
 In the heartbeat pattern, the device sends device-to-cloud messages at least once every fixed amount of time (for example, at least once every hour). Therefore, even if a device does not have any data to send, it still sends an empty device-to-cloud message (usually with a property that identifies it as a heartbeat). On the service side, the solution maintains a map with the last heartbeat received for each device. If the solution does not receive a heartbeat message within the expected time from the device, it assumes that there is a problem with the device.
 
-A more complex implementation could include the information from [Azure Monitor](../azure-monitor/index.yml) and [Azure Resource Health](../service-health/resource-health-overview.md) to identify devices that are trying to connect or communicate but failing. To learn more, see [Monitor IoT Hub](monitor-iot-hub.md) and [Check IoT Hub resource health](iot-hub-azure-service-health-integration.md#check-health-of-an-iot-hub-with-azure-resource-health). When you implement the heartbeat pattern, make sure to check [IoT Hub Quotas and Throttles](iot-hub-devguide-quotas-throttling.md).
+A more complex implementation could include the information from [Azure Monitor](../azure-monitor/index.yml) and [Azure Resource Health](../service-health/resource-health-overview.md) to identify devices that are trying to connect or communicate but failing. To learn more about using these services with IoT Hub, see [Monitor IoT Hub](monitor-iot-hub.md) and [Check IoT Hub resource health](iot-hub-azure-service-health-integration.md#check-health-of-an-iot-hub-with-azure-resource-health). For more specific information about using Azure Monitor or Event Grid to monitor device connectivity, see [Monitor, diagnose, and troubleshoot device connectivity](iot-hub-troubleshoot-connectivity.md). When you implement the heartbeat pattern, make sure to check [IoT Hub Quotas and Throttles](iot-hub-devguide-quotas-throttling.md).
 
 > [!NOTE]
 > If an IoT solution uses the connection state solely to determine whether to send cloud-to-device messages, and messages are not broadcast to large sets of devices, consider using the simpler *short expiry time* pattern. This pattern achieves the same result as maintaining a device connection state registry using the heartbeat pattern, while being more efficient. If you request message acknowledgements, IoT Hub can notify you about which devices are able to receive messages and which are not.

articles/iot-hub/iot-hub-event-grid.md

@@ -211,3 +211,5 @@ Applications that handle IoT Hub events should follow these suggested practices:
 * [Compare the differences between routing IoT Hub events and messages](iot-hub-event-grid-routing-comparison.md)
 
 * [Learn how to use IoT telemetry events to implement IoT spatial analytics using Azure Maps](../azure-maps/tutorial-iot-hub-maps.md)
+
+* [Learn more about how to use Event Grid and Azure Monitor to monitor, diagnose, and troubleshoot device connectivity to IoT Hub](iot-hub-troubleshoot-connectivity.md)

articles/iot-hub/iot-hub-how-to-order-connection-state-events.md

@@ -364,4 +364,6 @@ To remove an Azure Cosmos DB account from the Azure portal, right-click the acco
 
 * [Try the IoT Hub events tutorial](../event-grid/publish-iot-hub-events-to-logic-apps.md)
 
-* Learn about what else you can do with [Event Grid](../event-grid/overview.md)
+* Learn about what else you can do with [Event Grid](../event-grid/overview.md)
+
+* Learn how to use Event Grid and Azure Monitor to [Monitor, diagnose, and troubleshoot device connectivity to IoT Hub](iot-hub-troubleshoot-connectivity.md)

articles/iot-hub/iot-hub-troubleshoot-connectivity.md

@@ -1,5 +1,5 @@
 ---
-title: Monitor and troubleshoot disconnects with Azure IoT Hub
+title: Monitor and troubleshoot device connectivity to Azure IoT Hub
 description: Learn to monitor and troubleshoot common errors with device connectivity for Azure IoT Hub 
 author: kgremban
 manager: briz
@@ -13,7 +13,7 @@ ms.custom: [mqtt, 'Role: Cloud Development', 'Role: IoT Device', 'Role: Technica
 #Customer intent: As an operator for Azure IoT Hub, I need to know how to find out when devices are disconnecting unexpectedly and troubleshoot resolve those issues right away.
 ---
 
-# Monitor, diagnose, and troubleshoot Azure IoT Hub disconnects 
+# Monitor, diagnose, and troubleshoot Azure IoT Hub device connectivity
 
 Connectivity issues for IoT devices can be difficult to troubleshoot because there are many possible points of failure. Application logic, physical networks, protocols, hardware, IoT Hub, and other cloud services can all cause problems. The ability to detect and pinpoint the source of an issue is critical. However, an IoT solution at scale could have thousands of devices, so it's not practical to check individual devices manually. IoT Hub integrates with two Azure services to help you:
 
@@ -114,6 +114,22 @@ Use the following problem resolution guides for help with the most common errors
 
 * [500008 GenericTimeout](iot-hub-troubleshoot-error-500xxx-internal-errors.md)
 
+## Azure Monitor: Use logs to monitor connectivity for a specific device
+
+There may be situations when you want to use Azure Monitor to see connectivity errors and information for a specific device. To isolate connectivity events for a device, you can follow the same steps as in the preceding section, but enter the following query. Replace *test-device* with the name of your device.
+
+```kusto
+AzureDiagnostics
+| where ResourceProvider == "MICROSOFT.DEVICES" and ResourceType == "IOTHUBS"
+| where Category == "Connections"
+| extend DeviceId = tostring(parse_json(properties_s).deviceId)
+| where DeviceId == "test-device"
+```
+
+The query returns both error and informational events for your target device. The following example output shows an informational **deviceConnect** event:
+
+:::image type="content" source="media/iot-hub-troubleshoot-connectivity/device-connect-event.png" alt-text="Screenshot of deviceConnect event in logs.":::
+
 ## MQTT device disconnect behavior with Azure IoT SDKs
 
 Azure IoT device SDKs disconnect from IoT Hub and then reconnect when they renew SAS tokens over the MQTT (and MQTT over WebSockets) protocol. In logs, this shows up as informational device disconnect and connect events sometimes accompanied by error events.

articles/iot-hub/media/iot-hub-troubleshoot-connectivity/device-connect-event.png

@@ -271,6 +271,8 @@ The connections category tracks device connect and disconnect events from an IoT
 }
 ```
 
+For detailed information about using connections logs to monitor device connectivity, see [Monitor, diagnose, and troubleshoot device connectivity to Azure IoT Hub](iot-hub-troubleshoot-connectivity.md).
+
 ### Device telemetry
 
 The device telemetry category tracks errors that occur at the IoT hub and are related to the telemetry pipeline. This category includes errors that occur when sending telemetry events (such as throttling) and receiving telemetry events (such as unauthorized reader). This category cannot catch errors caused by code running on the device itself.

articles/iot-hub/monitor-iot-hub-reference.md

@@ -203,6 +203,16 @@ Following are queries that you can use to help you monitor your IoT hub.
     | summarize max(TimeGenerated) by DeviceId, _ResourceId
     ```
 
+- Connection events for a specific device: All connection events logged for a specific device (*test-device*).
+
+    ```kusto
+    AzureDiagnostics
+    | where ResourceProvider == "MICROSOFT.DEVICES" and ResourceType == "IOTHUBS"
+    | where Category == "Connections"
+    | extend DeviceId = tostring(parse_json(properties_s).deviceId)
+    | where DeviceId == "test-device"
+    ```
+
 - SDK version of devices: List of devices and their SDK versions for device connections or device to cloud twin operations.
 
     ```kusto
@@ -291,14 +301,16 @@ When creating an alert rule based on platform metrics, be aware that for IoT Hub
 
 ## Monitor per-device disconnects with Event Grid
 
-Azure Monitor provides a metric, *Connected devices*, that you can use to monitor the number of devices connected to your IoT Hub and trigger an alert when number of connected devices drops below a threshold value. While this may be sufficient for some scenarios, [Azure Event Grid](../event-grid/index.yml) provides a low-latency, per-device monitoring solution that you can use to track device connections for critical devices and infrastructure.
+Azure Monitor provides a metric, *Connected devices*, that you can use to monitor the number of devices connected to your IoT Hub and trigger an alert when number of connected devices drops below a threshold value. Azure Monitor also emits events in the [connections category](monitor-iot-hub-reference.md#connections) that you can use to monitor device connects, disconnects, and connection errors. While these may be sufficient for some scenarios, [Azure Event Grid](../event-grid/index.yml) provides a low-latency, per-device monitoring solution that you can use to track device connections for critical devices and infrastructure.
 
 With Event Grid, you can subscribe to the IoT Hub [**DeviceConnected** and **DeviceDisconnected** events](iot-hub-event-grid.md#event-types) to trigger alerts and monitor device connection state. Event Grid provides much lower event latency than Azure Monitor, and you can monitor on a per-device basis, rather than for the total number of connected devices. These factors make Event Grid the preferred method for monitoring connections for critical devices and infrastructure. We highly recommend using Event Grid to monitor device connections in production environments.
 
-For more detailed information about monitoring device connections with Event Grid and Azure Monitor, see [Monitor, diagnose, and troubleshoot disconnects with Azure IoT Hub](iot-hub-troubleshoot-connectivity.md).
+For more detailed information about monitoring device connectivity with Event Grid and Azure Monitor, see [Monitor, diagnose, and troubleshoot device connectivity to Azure IoT Hub](iot-hub-troubleshoot-connectivity.md).
 
 ## Next steps
 
 - See [Monitoring Azure IoT Hub data reference](monitor-iot-hub-reference.md) for a reference of the metrics, logs, and other important values created by [service name].
 
 - See [Monitoring Azure resources with Azure Monitor](../azure-monitor/essentials/monitor-azure-resource.md) for details on monitoring Azure resources.
+
+- See [Monitor, diagnose, and troubleshoot device connectivity to Azure IoT Hub](iot-hub-troubleshoot-connectivity.md) for details on monitoring device connectivity.