Collect and transport metrics

¹ Currently, using option 1 to directly transport metrics to Log Analytics from the IoT Edge device is the simpler path that requires minimal setup. The first option is preferred unless your specific scenario demands the option 2 approach so that the IoT Edge device communicates only with IoT Hub.

The metrics-collector module needs the Azure Resource Manager ID of the IoT hub that the IoT Edge device belongs to. Enter this ID as the value for the ResourceId environment variable. The collector stores it in the ordinary ResourceId column, preserving its case. Query the workspace and apply tolower() to both the stored and selected IDs before matching. This guide uses the pass-through schema described in Resource matching and query scope.

The resource ID uses the following format: /subscriptions/<subscription id>/resourceGroups/<resource group name>/providers/Microsoft.Devices/IoTHubs/<iot hub name>. You can find the resource ID in the Properties page of the IoT hub in the Azure portal.

Or, you can use the az resource show command to get the ID:

az resource show -g <resource group> -n <hub name> --resource-type "Microsoft.Devices/IoTHubs"

The metrics-collector module needs the Azure Resource Manager ID of the IoT Central application that the IoT Edge device belongs to. Enter this ID as the value for the ResourceId environment variable. The collector stores it in the ordinary ResourceId column, preserving its case. Query the workspace and apply tolower() to both the stored and selected IDs before matching. This guide uses the pass-through schema described in Resource matching and query scope.

The resource ID uses the following format: /subscriptions/<subscription id>/resourceGroups/<resource group name>/providers/Microsoft.IoTCentral/IoTApps/<iot central app name>. You can find the resource ID in the Properties page of the IoT Central application in the Azure portal.

Or, you can use the az resource show command to get the ID:

az resource show -g <resource group> -n <application name> --resource-type "Microsoft.IoTCentral/IoTApps"

The UploadTarget configuration option controls whether metrics are sent directly to Azure Monitor or to IoT Hub.

If you set UploadTarget to IotMessage, the module publishes your metrics as IoT messages. The endpoint /messages/modules/<metrics collector module name>/outputs/metricOutput emits these messages as UTF8-encoded JSON. For example, if your IoT Edge Metrics Collector module is named IoTEdgeMetricsCollector, the endpoint is /messages/modules/IoTEdgeMetricsCollector/outputs/metricOutput. The uncompressed message format is as follows:

[{
    "TimeGeneratedUtc": "<time generated>",
    "Name": "<prometheus metric name>",
    "Value": 1.0,
    "Labels": {
        "<label name>": "<label value>"
    }
}, {
    "TimeGeneratedUtc": "2020-07-28T20:00:43.2770247Z",
    "Name": "docker_container_disk_write_bytes",
    "Value": 0.0,
    "Labels": {
        "name": "AzureMonitorForIotEdgeModule"
    }
}]

The UploadTarget configuration option controls whether metrics are sent directly to Azure Monitor or to IoT Central.

If you set UploadTarget to IotMessage, the module publishes your metrics as IoT messages. The endpoint /messages/modules/<metrics collector module name>/outputs/metricOutput emits these messages as UTF8-encoded JSON. For example, if your IoT Edge Metrics Collector module is named IoTEdgeMetricsCollector, the endpoint is /messages/modules/IoTEdgeMetricsCollector/outputs/metricOutput. The uncompressed message format is as follows:

[{
    "TimeGeneratedUtc": "<time generated>",
    "Name": "<prometheus metric name>",
    "Value": 1.0,
    "Labels": {
        "<label name>": "<label value>"
    }
}, {
    "TimeGeneratedUtc": "2020-07-28T20:00:43.2770247Z",
    "Name": "docker_container_disk_write_bytes",
    "Value": 0.0,
    "Labels": {
        "name": "AzureMonitorForIotEdgeModule"
    }
}]

Sometimes you need to ingest metrics through IoT Hub instead of sending them directly to Log Analytics. For example, when monitoring IoT Edge devices in a nested configuration where child devices have access only to the IoT Edge hub of their parent device. Another example is deploying an IoT Edge device with outbound network access only to IoT Hub.

To enable monitoring in this scenario, configure the metrics-collector module to send metrics as device-to-cloud (D2C) messages via the edgeHub module. Turn on the capability by setting the UploadTarget environment variable to IotMessage in the collector configuration.

This option requires extra setup, a cloud workflow setup, to deliver metrics messages arriving at IoT Hub to the Log Analytics workspace. Without this setup, the other portions of the integration such as curated visualizations and alerts don't work.

Sometimes, you need to ingest metrics through IoT Central instead of sending them directly to Log Analytics. For example, when monitoring IoT Edge devices in a nested configuration where child devices have access only to the IoT Edge hub of their parent device. Another example is deploying an IoT Edge device with outbound network access only to IoT Central.

To enable monitoring in this scenario, configure the metrics-collector module to send metrics as device-to-cloud (D2C) messages via the edgeHub module. Turn on the capability by setting the UploadTarget environment variable to IotMessage in the collector configuration.

The following example shows the collector and routing configuration. Merge it into your deployment manifest and retain your complete system-module configuration:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.0",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {}
          }
        },
        "systemModules": {
          "edgeAgent": {
          },
          "edgeHub": {
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
          },
          "AzureMonitorForIotEdgeModule": {
            "settings": {
                "image": "mcr.microsoft.com/azureiotedge-metrics-collector:2.0.0",
                "createOptions": "{\"HostConfig\":{\"LogConfig\":{\"Type\":\"json-file\",\"Config\":{\"max-size\":\"4m\",\"max-file\":\"7\"}}}}"
            },
            "type": "docker",
            "env": {
              "UploadTarget": {
                "value": "IotMessage"
              },
              "ResourceId": {
                "value": "/subscriptions/{your subscription id}/resourceGroups/{your resource group}/providers/Microsoft.IoTCentral/IoTApps/{your app name}"
              },
              "MetricsEndpointsCSV": {
                "value": "http://edgeHub:9600/metrics,http://edgeAgent:9600/metrics"
              },
              "ScrapeFrequencyInSecs": {
                "value": "30"
              },
              "AllowedMetrics": {
                "value": ""
              },
              "BlockedMetrics": {
                "value": ""
              },
              "CompressForUpload": {
                "value": "false"
              },
              "TransformForIoTCentral": {
                "value": "true"
              }
            },
            "status": "running",
            "restartPolicy": "always",
            "version": "1.0"
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.0",
        "routes": {
          "temperatureupload": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO $upstream",
          "metricupload": "FROM /messages/modules/AzureMonitorForIotEdgeModule/outputs/metricOutput INTO $upstream"
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 7200
        }
      }
    },
    "SimulatedTemperatureSensor": {
    },
    "AzureMonitorForIotEdgeModule": {}
  }
}

To view the metrics from your IoT Edge device in your IoT Central application:

• Add the IoT Edge Metrics standard interface as an inherited interface to your device template:

  

• Use the telemetry values defined in the interface to build any dashboards you need to monitor your IoT Edge devices: