Monitor module twins

2025-06-09

Applies to: IoT Edge 1.5

Important

IoT Edge 1.5 LTS is the supported release. IoT Edge 1.4 LTS is end of life as of November 12, 2024. If you are on an earlier release, see Update IoT Edge.

Module twins in Azure IoT Hub let you monitor the connectivity and health of your IoT Edge deployments. Module twins store information in your IoT hub about the performance of your running modules. The IoT Edge agent and the IoT Edge hub runtime modules each maintain their own module twins: $edgeAgent and $edgeHub.

$edgeAgent has health and connectivity data about the IoT Edge agent, IoT Edge hub runtime modules, and your custom modules. The IoT Edge agent deploys the modules, monitors them, and reports connection status to your Azure IoT hub.
$edgeHub has data about communications between the IoT Edge hub running on a device and your Azure IoT hub. This includes processing incoming messages from downstream devices. The IoT Edge hub processes communications between Azure IoT Hub and IoT Edge devices and modules.

The data is organized into metadata, tags, and desired and reported property sets in the module twins' JSON structures. The desired properties you specify in your deployment.json file are copied to the module twins. The IoT Edge agent and the IoT Edge hub each update the reported properties for their modules.

Similarly, the desired properties you specify for your custom modules in the deployment.json file are copied to its module twin, but your solution provides its reported property values.

This article shows how to review the module twins in the Azure portal, Azure CLI, and Visual Studio Code. For information on monitoring how your devices receive the deployments, see Monitor IoT Edge deployments. For an overview of module twins, see Understand and use module twins in IoT Hub.

Tip

The reported properties of a runtime module can be stale if an IoT Edge device gets disconnected from its IoT hub. Ping the $edgeAgent module to check if the connection was lost.

Monitor runtime module twins

To troubleshoot deployment connectivity issues, review the IoT Edge agent and IoT Edge hub runtime module twins and then drill down into other modules.

Monitor IoT Edge agent module twin

This JSON shows the $edgeAgent module twin in Visual Studio Code with most sections collapsed.

{
  "deviceId": "Windows109",
  "moduleId": "$edgeAgent",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDUz",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Disconnected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 53,
  "properties": {
    "desired": { "···" },
    "reported": {
      "schemaVersion": "1.0",
      "version": { "···" },
      "lastDesiredStatus": { "···" },
      "runtime": { "···" },
      "systemModules": {
        "edgeAgent": { "···" },
        "edgeHub": { "···" }
      },
      "lastDesiredVersion": 5,
      "modules": {
        "SimulatedTemperatureSensor": { "···" }
      },
      "$metadata": { "···" },
      "$version": 48
    }
  }
}

This JSON has these sections:

Metadata - Has connectivity data. The connection state for the IoT Edge agent is always "Disconnected" because it applies to device-to-cloud (D2C) messages, and the IoT Edge agent doesn't send D2C messages.
Properties - Has the desired and reported subsections.
Properties.desired - (shown collapsed) Expected property values set in the deployment.json file.
Properties.reported - Latest property values reported by the IoT Edge agent.

Both the properties.desired and properties.reported sections have a similar structure and include metadata for schema, version, and runtime information. They also have a modules section for custom modules like SimulatedTemperatureSensor, and a systemModules section for $edgeAgent and $edgeHub runtime modules.

Compare the reported property values to the desired values to find discrepancies and identify disconnections that help you troubleshoot issues. When you compare values, check the $lastUpdated reported value in the metadata section for the property you're investigating.

Check these properties when you troubleshoot:

exitcode - Any value other than zero means the module stopped with a failure. Error codes 137 or 143 are used if a module is intentionally set to a stopped status.
lastStartTimeUtc - Shows the DateTime when the container last started. This value is 0001-01-01T00:00:00Z if the container isn't started.
lastExitTimeUtc - Shows the DateTime when the container last finished. This value is 0001-01-01T00:00:00Z if the container is running and was never stopped.

runtimeStatus - Has one of these values:

Value	Description
unknown	Default state until deployment is created.
backoff	The module is scheduled to start but isn't running. This value is useful for a module that's restarting. When a failing module is awaiting restart during the cool-off period, the module is in a backoff state.
running	The module is running.
unhealthy	A health-probe check failed or timed out.
stopped	The module exited successfully (with a zero exit code).
failed	The module exited with a failure exit code (non-zero). The module can go back to backoff from this state depending on the restart policy. This state means the module has an unrecoverable error. Failure happens when the Microsoft Monitoring Agent (MMA) can't restart the module, requiring a new deployment.

For details, see EdgeAgent reported properties.

Monitor IoT Edge hub module twin

The following JSON shows the $edgeHub module twin in Visual Studio Code with most sections collapsed.

{
  "deviceId": "Windows109",
  "moduleId": "$edgeHub",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDU2",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Connected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 102,
    "properties": {
      "desired": { "···" },
      "reported": {
        "schemaVersion": "1.0",
        "version": { "···" },
      "lastDesiredVersion": 5,
      "lastDesiredStatus": { "···" },
      "clients": {
        "Windows109/SimulatedTemperatureSensor": {
          "status": "Disconnected",
          "lastConnectedTimeUtc": "2020-04-08T21:42:42.1743956Z",
          "lastDisconnectedTimeUtc": "2020-04-09T07:02:42.1398325Z"
        }
      },
      "$metadata": { "···" },
      "$version": 97
    }
  }
}

The JSON can be described in the following sections, starting from the top:

Metadata - Contains connectivity data.
Properties - Contains the desired and reported subsections.
Properties.desired - (shown collapsed) Expected property values set by the operator in the deployment.json file.
Properties.reported - Latest property values reported by the IoT Edge hub.

If you're having issues with downstream devices, start by checking this data.

Monitor custom module twins

The IoT Edge agent module twin keeps information about the connectivity of your custom modules. The module twin for your custom module mainly stores data for your solution. The desired properties you define in your deployment.json file appear in the module twin, and your module can update reported property values as needed.

Use your preferred programming language with the Azure IoT Hub Device SDKs to update reported property values in the module twin based on your module's application code. The following procedure uses the Azure SDK for .NET and code from the SimulatedTemperatureSensor module:

Create an instance of the ModuleClient by using the CreateFromEnvironmentAsync method.
Get the module twin's properties by using the GetTwinAsync method.
Create a listener with a callback to catch changes to desired properties by using the SetDesiredPropertyUpdateCallbackAsync method.
In the callback method, update the reported properties in the module twin by using the UpdateReportedPropertiesAsync method, and pass a TwinCollection of the property values to set.

Access the module twins

Review the JSON for module twins in Azure IoT Hub, Visual Studio Code, or Azure CLI.

Monitor in Azure IoT Hub

View the JSON for the module twin:

Sign in to the Azure portal and navigate to your IoT hub.
Select Devices under the Device management menu.
Select the Device ID of the IoT Edge device with the modules you want to monitor.
Select the module name from the Modules tab and then select Module Identity Twin from the upper menu bar.

If you see the message "A module identity doesn't exist for this module", this error means the back-end solution that originally created the identity isn't available.