监视模块孪生Monitor module twins

Azure IoT 中心中的模块孪生可以监视 IoT Edge 部署的连接性和运行状况。Module twins in Azure IoT Hub enable monitoring the connectivity and health of your IoT Edge deployments. 模块孪生用于存储 IoT 中心中的有用信息,这些信息与运行的模块的性能有关。Module twins store useful information in your IoT hub about the performance of your running modules. IoT Edge 代理IoT Edge 中心运行时模块分别维护它们的模块孪生 $edgeAgent$edgeHubThe IoT Edge agent and the IoT Edge hub runtime modules each maintain their module twins, $edgeAgent and $edgeHub, respectively:

  • $edgeAgent 包含有关 IoT Edge 代理和 IoT Edge 中心运行时模块以及自定义模块的运行状况和连接数据。$edgeAgent contains health and connectivity data about both the IoT Edge agent and IoT Edge hub runtime modules, and your custom modules. IoT Edge 代理负责部署模块,对其进行监视并向 Azure IoT 中心报告连接状态。The IoT Edge agent is responsible for deploying the modules, monitoring them, and reporting connection status to your Azure IoT hub.
  • $edgeHub 包含有关在设备上运行的 IoT Edge 中心与 Azure IoT 中心之间的通信数据。$edgeHub contains 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. IoT Edge 中心负责处理 Azure IoT 中心与 IoT Edge 设备和模块之间的通信。IoT Edge hub is responsible for processing the communications between the Azure IoT Hub and the IoT Edge devices and modules.

数据被组织为元数据、标记以及模块孪生的 JSON 结构中所需的和报告的属性集。The data is organized into metadata, tags, along with desired and reported property sets in the module twins' JSON structures. 在 deployment.json 文件中指定的所需属性将被复制到模块孪生。The desired properties you specified in your deployment.json file are copied to the module twins. IoT Edge 代理和 IoT Edge 中心各自更新其模块的报告属性。The IoT Edge agent and the IoT Edge hub each update the reported properties for their modules.

同样,deployment.json 中为自定义模块所指定的所需属性会复制到其模块孪生中,但你的解决方案负责提供其报告的属性值。Similarly, the desired properties specified for your custom modules in the deployment.json file are copied to its module twin, but your solution is responsible for providing its reported property values.

本文介绍如何在 Azure 门户、Azure CLI 和 Visual Studio Code 中查看模块孪生。This article describes how to review the module twins in the Azure portal, Azure CLI, and in Visual Studio Code. 有关监视设备接收部署的方式的信息,请参阅监视 IoT Edge 部署For information on monitoring how your devices receive the deployments, see Monitor IoT Edge deployments. 有关模块孪生概念的概述,请参阅在 IoT 中心内了解并使用模块孪生For an overview on the concept of module twins, see Understand and use module twins in IoT Hub.

提示

如果 IoT Edge 设备与其 IoT 中心断开连接,则运行时模块的报告的属性可能会过时。The reported properties of a runtime module could be stale if an IoT Edge device gets disconnected from its IoT hub. 可以对 $edgeAgent 模块使用 ping 方法来确定连接是否丢失。You can ping the $edgeAgent module to determine if the connection was lost.

监视运行时模块孪生Monitor runtime module twins

若要排查部署连接性问题,请查看 IoT Edge 代理和 IoT Edge 中心运行时模块孪生,然后深入到其他模块。To troubleshoot deployment connectivity issues, review the IoT Edge agent and IoT Edge hub runtime module twins and then drill down into other modules.

监视 IoT Edge 代理模块孪生Monitor IoT Edge agent module twin

以下 JSON 显示了 Visual Studio Code 中的 $edgeAgent 模块孪生,其中大部分 JSON 部分已折叠。The following JSON shows the $edgeAgent module twin in Visual Studio Code with most of the JSON 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
    }
  }
}

从顶部开始,可在以下部分中描述 JSON:The JSON can be described in the following sections, starting from the top:

  • Metadata - 包含连接性数据。Metadata - Contains connectivity data. 有趣的是,IoT Edge 代理的连接状态始终为断开连接状态:"connectionState": "Disconnected"Interestingly, the connection state for the IoT Edge agent is always in a disconnected state: "connectionState": "Disconnected". 这是因为连接状态与设备到云 (D2C) 消息有关,且 IoT Edge 代理不发送 D2C 消息。The reason being the connection state pertains to device-to-cloud (D2C) messages and the IoT Edge agent doesn't send D2C messages.
  • Properties - 包含 desiredreported 子节。Properties - Contains the desired and reported subsections.
  • Properties.desired -(显示为已折叠)运算符在 deployment.json 文件中设置的期望属性值。Properties.desired - (shown collapsed) Expected property values set by the operator in the deployment.json file.
  • Properties.reported - IoT Edge 代理报告的最新属性值。Properties.reported - Latest property values reported by IoT Edge agent.

properties.desiredproperties.reported 部分都具有类似的结构,且都包含架构、版本和运行时信息的其他元数据。Both the properties.desired and properties.reported sections have a similar structure and contain additional metadata for schema, version, and runtime information. 此外,任何自定义模块(如 SimulatedTemperatureSensor)的 modules 部分以及 $edgeAgent$edgeHub 运行时模块的 systemModules 部分也包含在内。Also included is the modules section for any custom modules (such as SimulatedTemperatureSensor), and the systemModules section for $edgeAgent and the $edgeHub runtime modules.

通过将报告的属性值与所需值进行比较,可以确定差异并标识断开连接,以帮助排查问题。By comparing the reported property values against the desired values, you can determine discrepancies and identify disconnections that can help you troubleshoot issues. 执行这些比较时,请检查所调查属性的 metadata 部分中 $lastUpdated 报告的值。In doing these comparisons, check the $lastUpdated reported value in the metadata section for the property you're investigating.

若要进行故障排除,则检查以下属性很有必要:The following properties are important to examine for troubleshooting:

  • exitcode - 零以外的任何其他值都表示模块因失败而停止。exitcode - Any value other than zero indicates that the module stopped with a failure. 但是,如果有意将模块设置为已停止状态,则使用错误代码 137 或 143。However, error codes 137 or 143 are used if a module was intentionally set to a stopped status.

  • lastStartTimeUtc - 显示上次启动容器的日期/时间。lastStartTimeUtc - Shows the DateTime that the container was last started. 如果未启动容器,则此值为 0001-01-01T00:00:00Z。This value is 0001-01-01T00:00:00Z if the container wasn't started.

  • lastExitTimeUtc - 显示容器最近完成的日期/时间。lastExitTimeUtc - Shows the DateTime that the container last finished. 如果容器正在运行且从未停止过,则此值为 0001-01-01T00:00:00Z。This value is 0001-01-01T00:00:00Z if the container is running and was never stopped.

  • runtimeStatus - 可以是以下值之一:runtimeStatus - Can be one of the following values:

    ValueValue 说明Description
    未知unknown 默认状态,直到部署创建完成。Default state until deployment is created.
    回退backoff 该模块已计划启动,但当前未运行。The module is scheduled to start but isn't currently running. 此值对于在重启时经历状态更改的模块很有用。This value is useful for a module undergoing state changes in restarting. 当失败模块在冷却期间等待重启时,该模块将处于回退状态。When a failing module is awaiting restart during the cool-off period, the module will be in a backoff state.
    “正在运行”running 指示模块当前正在运行。Indicates that the module is currently running.
    不正常unhealthy 指示运行状况探测检查失败或超时。Indicates a health-probe check failed or timed out.
    已停止stopped 指示已成功退出该模块(退出代码为零)。Indicates that the module exited successfully (with a zero exit code).
    “失败”failed 指示已退出该模块,并显示失败退出代码(非零)。Indicates that the module exited with a failure exit code (non-zero). 根据生效的重启策略,模块可以从此状态转换回回退状态。The module can transition back to backoff from this state depending on the restart policy in effect. 此状态可能表示该模块发生了不可恢复的错误。This state can indicate that the module has experienced an unrecoverable error. 如果 Microsoft Monitoring Agent (MMA) 无法再恢复模块,则会发生失败,并需要新的部署。Failure occurs when the Microsoft Monitoring Agent (MMA) can no longer resuscitate the module, requiring a new deployment.

有关详细信息,请参阅 EdgeAgent 报告的属性See EdgeAgent reported properties for details.

监视 IoT Edge 中心模块孪生Monitor IoT Edge hub module twin

以下 JSON 显示了 Visual Studio Code 中的 $edgeHub 模块孪生,其中大部分 JSON 部分已折叠。The following JSON shows the $edgeHub module twin in Visual Studio Code with most of the JSON 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
    }
  }
}

从顶部开始,可在以下部分中描述 JSON:The JSON can be described in the following sections, starting from the top:

  • Metadata - 包含连接性数据。Metadata - Contains connectivity data.

  • Properties - 包含 desiredreported 子节。Properties - Contains the desired and reported subsections.

  • Properties.desired -(显示为已折叠)运算符在 deployment.json 文件中设置的期望属性值。Properties.desired - (shown collapsed) Expected property values set by the operator in the deployment.json file.

  • Properties.reported - IoT Edge 中心报告的最新属性值。Properties.reported - Latest property values reported by IoT Edge hub.

如果你的下游设备遇到问题,则检查此数据是一个不错的开端。If you're experiencing issues with your downstream devices, examining this data would be a good place to start.

监视自定义模块孪生Monitor custom module twins

有关自定义模块连接性的信息在 IoT Edge 代理模块孪生中进行维护。The information about the connectivity of your custom modules is maintained in the IoT Edge agent module twin. 自定义模块的模块孪生主要用于维护解决方案的数据。The module twin for your custom module is used primarily for maintaining data for your solution. 你在 deployment.json 文件中定义的所需属性将反映在模块孪生中,模块可根据需要更新报告的属性值。The desired properties you defined in your deployment.json file are reflected in the module twin, and your module can update reported property values as needed.

可以将首选的编程语言与 Azure IoT 中心设备 SDK 结合使用,以基于模块的应用程序代码来更新模块孪生中报告的属性值。You can 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. 以下过程使用适用于 .NET 的 Azure SDK 完成此操作,方法是使用来自 SimulatedTemperatureSensor 模块的代码:The following procedure uses the Azure SDK for .NET to do this, using code from the SimulatedTemperatureSensor module:

  1. 使用 CreateFromEnvironmentAysnc 方法创建 ModuleClient 的实例。Create an instance of the ModuleClient with the CreateFromEnvironmentAysnc method.

  2. 使用 GetTwinAsync 方法获取模块克隆属性的集合。Get a collection of the module twin's properties with the GetTwinAsync method.

  3. 使用 SetDesiredPropertyUpdateCallbackAsync 方法创建侦听程序(用于传递回调)来捕获对所需属性的更改。Create a listener (passing a callback) to catch changes to desired properties with the SetDesiredPropertyUpdateCallbackAsync method.

  4. 在回调方法中,使用 UpdateReportedPropertiesAsync 方法更新模块孪生中报告的属性,传递要设置的 TwinCollection 属性值。In your callback method, update the reported properties in the module twin with the UpdateReportedPropertiesAsync method, passing a TwinCollection of the property values that you want to set.

访问模块孪生Access the module twins

可在 Azure IoT 中心和 Visual Studio Code 中以及使用 Azure CLI 查看模块孪生的 JSON。You can review the JSON for module twins in the Azure IoT Hub, in Visual Studio Code, and with Azure CLI.

在 Azure IoT 中心中进行监视Monitor in Azure IoT Hub

查看模块孪生的 JSON,方法如下:To view the JSON for the module twin:

  1. 登录 Azure 门户,导航到 IoT 中心。Sign in to the Azure portal and navigate to your IoT hub.
  2. 从左窗格菜单中选择“IoT Edge”。Select IoT Edge from the left pane menu.
  3. 在“IoT Edge 设备”选项卡上,选择包含要监视模块的设备的“设备 ID” 。On the IoT Edge devices tab, select the Device ID of the device with the modules you want to monitor.
  4. 从“模块”选项卡中选择模块名称,然后从上部菜单栏中选择“模块标识孪生” 。Select the module name from the Modules tab and then select Module Identity Twin from the upper menu bar.

选择要在 Azure 门户中查看的模块孪生

如果看到消息“此模块不存在模块标识”,则此错误表示最初创建该标识的后端解决方案不再可用。If you see the message "A module identity doesn't exist for this module", this error indicates that the back-end solution is no longer available that originally created the identity.

在 Visual Studio Code 中监视模块孪生Monitor module twins in Visual Studio Code

查看并编辑模块孪生,方法如下:To review and edit a module twin:

  1. 安装适用于 Visual Studio Code 的 Azure IoT 工具扩展(如果尚未安装)。If not already installed, install the Azure IoT Tools Extension for Visual Studio Code.
  2. 在资源管理器中,展开“Azure IoT 中心”,然后使用要监视的模块来展开设备 。In the Explorer, expand the Azure IoT Hub, and then expand the device with the module you want to monitor.
  3. 右键单击该模块,然后选择“编辑模块孪生”。Right-click the module and select Edit Module Twin. 模块孪生的临时文件会下载到计算机并显示在 Visual Studio Code 中。A temporary file of the module twin is downloaded to your computer and displayed in Visual Studio Code.

获取模块孪生以在 Visual Studio Code 中进行编辑

如果进行了更改,请在编辑器中的代码上方选择“更新模块孪生”,以将更改保存到 IoT 中心。If you make changes, select Update Module Twin above the code in the editor to save changes to your IoT hub.

在 Visual Studio Code 中更新模块孪生

在 Azure CLI 中监视模块孪生Monitor module twins in Azure CLI

若要查看 IoT Edge 是否正在运行,请使用 az iot hub invoke-module-method 来对 IoT Edge 代理使用 ping 方法。To see if IoT Edge is running, use the az iot hub invoke-module-method to ping the IoT Edge agent.

az iot hub module-twin 结构提供以下命令:The az iot hub module-twin structure provides these commands:

  • az iot hub module-twin show - 显示模块孪生定义。az iot hub module-twin show - Show a module twin definition.
  • az iot hub module-twin update - 更新模块孪生定义。az iot hub module-twin update - Update a module twin definition.
  • az iot hub module-twin replace - 将模块孪生定义替换为目标 JSON。az iot hub module-twin replace - Replace a module twin definition with a target JSON.

后续步骤Next steps

了解如何使用内置直接方法与 EdgeAgent 通信Learn how to communicate with EdgeAgent using built-in direct methods.