Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Detect metrics export

With metrics export, you can export cloud-side, device-side, or custom metrics from Amazon IoT Device Defender and publish them to an MQTT topic that you configure. This feature supports the bulk export of Detect metrics, which not only allows for more efficient data reporting and analysis, but also helps control costs. You can choose your MQTT topic as an Amazon IoT Rules Basic Ingest Topic or create and subscribe to your own MQTT topic. Configure metrics export by using the Amazon IoT Device Defender console, API, or CLI. This feature is available in all Amazon Regions where Amazon IoT Device Defender is available.

The following illustration shows how you can configure Amazon IoT Device Defender to export metrics. The first diagram demonstrates how to configure export metrics on a Basic Ingest topic. You can then route the exported metrics to various destinations supported by Amazon IoT Rules. The second diagram shows how to configure Amazon IoT Device Defender to publish data to an MQTT topic. The MQTT client then subscribes to that topic. You can run an MQTT client in a container on Amazon Elastic Container Service, Lambda, or an Amazon EC2 instance that subscribes to the same MQTT topic. Whenever Amazon IoT Device Defender publishes data, the MQTT client receives and processes it. For more information, see MQTT topics.

How detect metric export works

When you set up a security profile, you choose the metrics for export and specify the MQTT topic. You also configure an IAM role that grants Amazon IoT Device Defender Detect the necessary permissions to publish messages to the configured MQTT topic. You can configure an Amazon IoT Rules Basic Ingest MQTT topic and send the exported metrics to Amazon IoT Rules supported destinations. For instructions on setting up and configuring Amazon IoT Rules, see Rules for Amazon IoT in the Amazon IoT Developer Guide.

Amazon IoT Device Defender Detect batches metric values for each configured metric and publishes them to a configured MQTT topic at regular intervals. Except for message byte size and total byte size, cloud-side metrics are aggregated by summing metric values for the batched duration. Custom and device-side metrics aren't aggregated. For message byte size, the export values are the minimum, maximum, and total byte size for the batched duration. For disconnect duration, the export value is the disconnect duration—in seconds— for all tracked devices. This occurs every one-hour interval and also for connection or a disconnection events. For connected devices or connection events, the value is zero. For more information on cloud-side metrics, device-side metrics, and custom metrics, see the following topics in the Amazon IoT Device Defender Developer Guide:

You can export batched metrics to different destinations with Amazon IoT Rules. For a list of supported destinations, see Amazon IoT rule actions. To send individual metrics within a batched export message to a supported destination, use the batchMode option for Amazon IoT rules actions. If your preferred Amazon IoT Rules destination lacks batchMode support, you can still send individual metrics within a batched message by using intermediary actions such as Lambda or Kinesis Data Streams.

Setting up Detect metrics export in the Amazon IoT console

Create, view, and edit a new security profile that includes metrics export in the console.

Prerequisites

Before you set up Detect metrics export, make sure you have the following prerequisites:

Creating a new security profile with metrics export (console)

To export metric behavior data, first configure a security profile to include metric exporting. The following procedure details how to set up a rule-based security profile that includes Detect metrics export.

Viewing and editing security profile details (console)

Creating a security profile to enable metrics export

Use the create-security-profile command to create your security profile and enable metrics export.

aws iot create-security-profile \
    --security-profile-name CreateSecurityProfileWithMetricsExport \
    --security-profile-description "create security profile with metrics export enabled"  \
    --behaviors "[{\"name\":\"BehaviorNumAuthz\",\"metric\":\"aws:num-authorization-failures\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":5}, \"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1,\"durationSeconds\":300},\"exportMetric\":true}]" \
    --metrics-export-config "{\"mqttTopic\":\"\$aws/rules/metricsExportRule\",\"roleArn\":\"arn:aws:iam::123456789012:role/iot-test-role\"}" \
    --region us-east-1

Output:

{
    "securityProfileName": "CreateSecurityProfileWithMetricsExport",
    "securityProfileArn": "arn:aws:iot:us-east-1:123456789012:securityprofile/CreateSecurityProfileWithMetricsExport"
}

Updating a security profile to enable metrics export (CLI)

Use the update-security-profile command to update an existing security profile and enable metrics export.

aws iot update-security-profile \
    --security-profile-name UpdateSecurityProfileWithMetricsExport \
    --security-profile-description "update an existing security profile to enable metrics export"  \
    --behaviors "[{\"name\":\"BehaviorNumAuthz\",\"metric\":\"aws:num-authorization-failures\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":5}, \"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1,\"durationSeconds\":300},\"exportMetric\":true}]" \
    --metrics-export-config "{\"mqttTopic\":\"\$aws/rules/metricsExportRule\",\"roleArn\":\"arn:aws:iam::123456789012:role/iot-test-role\"}" \
    --region us-east-1

Output:

{
    "securityProfileName": "UpdateSecurityProfileWithMetricsExport",
    "securityProfileArn": "arn:aws:iot:us-east-1:123456789012:securityprofile/UpdateSecurityProfileWithMetricsExport",
    "securityProfileDescription": "update an existing security profile to enable metrics export",
    "behaviors": [
        {
            "name": "BehaviorNumAuthz",
            "metric": "aws:num-authorization-failures",
            "criteria": {
                "comparisonOperator": "less-than",
                "value": {
                    "count": 5
                },
                "durationSeconds": 300,
                "consecutiveDatapointsToAlarm": 1,
                "consecutiveDatapointsToClear": 1
            },
            "exportMetric": true
        }
    ],
    "version": 2,
    "creationDate": "2023-11-09T16:18:37.183000-08:00",
    "lastModifiedDate": "2023-11-09T16:20:15.486000-08:00",
    "metricsExportConfig": {
        "mqttTopic": "$aws/rules/metricsExportRule",
        "roleArn": "arn:aws:iam::123456789012:role/iot-test-role"
    }
}

Updating a security profile to turn off metrics export (CLI)

Use the update-security-profile command to update an existing security profile and turn off metrics export.

aws iot update-security-profile \
    --security-profile-name UpdateSecurityProfileToDisableMetricsExport \
    --security-profile-description "update an existing security profile to disable metrics export"  \
    --behaviors "[{\"name\":\"BehaviorNumAuthz\",\"metric\":\"aws:num-authorization-failures\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":5}, \"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1,\"durationSeconds\":300}}]" \
    --delete-metrics-export-config \
    --region us-east-1

Output:

{
    "securityProfileName": "UpdateSecurityProfileToDisableMetricsExport",
    "securityProfileArn": "arn:aws:iot:us-east-1:123456789012:securityprofile/UpdateSecurityProfileWithMetricsExport",
    "securityProfileDescription": "update an existing security profile to disable metrics export",
    "behaviors": [
        {
            "name": "BehaviorNumAuthz",
            "metric": "aws:num-authorization-failures",
            "criteria": {
                "comparisonOperator": "less-than",
                "value": {
                    "count": 5
                },
                "durationSeconds": 300,
                "consecutiveDatapointsToAlarm": 1,
                "consecutiveDatapointsToClear": 1
            }
        }
    ],
    "version": 2,
    "creationDate": "2023-11-09T16:18:37.183000-08:00",
    "lastModifiedDate": "2023-11-09T16:31:16.265000-08:00"
}

For more information, see Detect Commands in the Amazon IoT Developer Guide.

Metrics export CLI commands

You can use the following CLI commands to create and manage Detect metrics export.

Metrics export API operations

You can use the following API operations to create and manage Detect metrics export.