# Fleet metrics Fleet metrics Fleet metrics is a feature of [fleet indexing](iot-indexing.md), a managed service that allows you to index, search, and aggregate your devices' data in AWS IoT. You can use fleet metrics, to monitor your fleet devices' aggregate state in [CloudWatch](https://console.aws.amazon.com/cloudwatch/) over time, including reviewing your fleet devices' disconnection rate or average battery level changes of a specified period. Using fleet metrics, you can build [aggregation queries](index-aggregate.md) whose results are continually emitted to [CloudWatch](https://console.aws.amazon.com/cloudwatch/) as metrics for analyzing trends and creating alarms. For your monitoring tasks, you can specify the aggregation queries of different aggregation types (**Statistics**, **Cardinality**, and **Percentile**). You can save all of your aggregation queries to create fleet metrics for reuse in the future. # Getting started tutorial In this tutorial, you create a [fleet metric](iot-fleet-metrics.md) to monitor your sensors' temperatures to detect potential anomalies. When creating the fleet metric, you define an [aggregation query](index-aggregate.md) that detects the number of sensors with temperatures exceeding 80 degrees Fahrenheit. You specify the query to run every 60 seconds and the query results are emitted to CloudWatch, where you can view the number of sensors that have potential high-temperature risks, and set alarms. To complete this tutorial, you'll use [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html). In this tutorial, you'll learn how to: + [Set up](#fleet-metrics-tutorial-setup) + [Create fleet metrics](#fleet-metrics-tutorial-create) + [View metrics in CloudWatch](#fleet-metrics-tutorial-view-data) + [Clean up resources](#fleet-metrics-tutorial-delete-fleet-metrics) This tutorial takes about 15 minutes to complete. ## Prerequisites + Install the latest version of [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) + Familiarize yourself with [Querying for aggregate data](https://docs.aws.amazon.com/iot/latest/developerguide/index-aggregate.html) + Familiarize yourself with [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) ## Set up To use fleet metrics, enable fleet indexing. To enable fleet indexing for your things or thing groups with specified data sources and associated configurations, follow the instructions in [Managing thing indexing](managing-index.md#enable-index) and [Managing thing group indexing](thinggroup-index.md#enable-group-index). **To set up** 1. Run the following command to enable fleet indexing and specify the data sources to search from. ``` aws iot update-indexing-configuration \ --thing-indexing-configuration "thingIndexingMode=REGISTRY_AND_SHADOW,customFields=[{name=attributes.temperature,type=Number},{name=attributes.rackId,type=String},{name=attributes.stateNormal,type=Boolean}],thingConnectivityIndexingMode=STATUS" \ ``` The preceding example CLI command enables fleet indexing to support searching registry data, shadow data, and thing connectivity status using the `AWS_Things` index. The configuration change can take a few minutes to complete. Verify that your fleet indexing is enabled before you create fleet metrics. To check if your fleet indexing has been enabled, run the following CLI command: ``` aws --region us-east-1 iot describe-index --index-name "AWS_Things" ``` For more information, see [Enable thing indexing](managing-index.md#enable-index). 1. Run the following bash script to create ten things and describe them. ``` # Bash script. Type `bash` before running in other shells. Temperatures=(70 71 72 73 74 75 47 97 98 99) Racks=(Rack1 Rack1 Rack2 Rack2 Rack3 Rack4 Rack5 Rack6 Rack6 Rack6) IsNormal=(true true true true true true false false false false) for ((i=0; i < 10; i++)) do thing=$(aws iot create-thing --thing-name "TempSensor$i" --attribute-payload attributes="{temperature=${Temperatures[@]:$i:1},rackId=${Racks[@]:$i:1},stateNormal=${IsNormal[@]:$i:1}}") aws iot describe-thing --thing-name "TempSensor$i" done ``` This script creates ten things to represent ten sensors. Each thing has attributes of `temperature`, `rackId`, and `stateNormal` as described in the following table: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/fleet-metrics-get-started.html) The output of this script contains ten JSON files. One of the JSON file looks like the following: ``` { "version": 1, "thingName": "TempSensor0", "defaultClientId": "TempSensor0", "attributes": { "rackId": "Rack1", "stateNormal": "true", "temperature": "70" }, "thingArn": "arn:aws:iot:region:account:thing/TempSensor0", "thingId": "example-thing-id" } ``` For more information, see [Create a thing](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html#create-thing). ## Create fleet metrics **To create a fleet metric** 1. Run the following command to create a fleet metric named *high\$1temp\$1FM*. You create the fleet metric to monitor the number of sensors with temperatures exceeding 80 degrees Fahrenheit in CloudWatch. ``` aws iot create-fleet-metric --metric-name "high_temp_FM" --query-string "thingName:TempSensor* AND attributes.temperature >80" --period 60 --aggregation-field "attributes.temperature" --aggregation-type name=Statistics,values=count ``` --metric-name Data type: string. The `--metric-name` parameter specifies a fleet metric name. In this example, you're creating a fleet metric named *high\$1temp\$1FM*. --query-string Data type: string. The `--query-string` parameter specifies the query string. In this example, the query string means to query all the things with names starting with *TempSensor* and with temperatures higher than 80 degrees Fahrenheit. For more information, see [Query syntax](query-syntax.md). --period Data type: integer. The `--period` parameter specifies the time to retrieve the aggregated data in seconds. In this example, you specify that the fleet metric you're creating retrieves the aggregated data every 60 seconds. --aggregation-field Data type: string. The `--aggregation-field` parameter specifies the attribute to evaluate. In this example, the temperature attribute is to be evaluated. --aggregation-type The `--aggregation-type` parameter specifies the statistical summary to display in the fleet metric. For your monitoring tasks, you can customize the aggregation query properties for the different aggregation types (**Statistics**, **Cardinality**, and **Percentile**). In this example, you specify **count** for the aggregation type and **Statistics** to return the count of devices that have attributes that match the query, in other words, to return the count of the devices with names starting with *TempSensor* and with temperatures higher than 80 degrees Fahrenheit. For more information, see [Querying for aggregate data](index-aggregate.md). The output of this command looks like the following: ``` { "metricArn": "arn:aws:iot:region:111122223333:fleetmetric/high_temp_FM", "metricName": "high_temp_FM" } ``` **Note** It can take a moment for the data points to display in CloudWatch. To learn more about how to create a fleet metric, read [Managing fleet metrics](managing-fleet-metrics.md). If you can't create a fleet metric, read [Troubleshooting fleet metrics](fleet-indexing-troubleshooting.md#fleet-metrics-troubleshooting). 1. (Optional) Run the following command to describe your fleet metric named *high\$1temp\$1FM*: ``` aws iot describe-fleet-metric --metric-name "high_temp_FM" ``` The output of this command looks like the following: ``` { "queryVersion": "2017-09-30", "lastModifiedDate": 1625249775.834, "queryString": "*", "period": 60, "metricArn": "arn:aws:iot:region:111122223333:fleetmetric/high_temp_FM", "aggregationField": "registry.version", "version": 1, "aggregationType": { "values": [ "count" ], "name": "Statistics" }, "indexName": "AWS_Things", "creationDate": 1625249775.834, "metricName": "high_temp_FM" } ``` ## View fleet metrics in CloudWatch After creating the fleet metric, you can view the metric data in CloudWatch. In this tutorial, you will see the metric that shows the number of sensors with names starting with *TempSensor* and with temperatures higher than 80 degrees Fahrenheit. **To view data points in CloudWatch** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. On the CloudWatch menu on the left panel, choose **Metrics** to expand the submenu and then choose **All metrics**. This opens the page with the upper half to display the graph and the lower half containing four tabbed sections. 1. The first tabbed section **All metrics** lists all the metrics that you can view in groups, choose **IoTFleetMetrics**. This contains all of your fleet metrics. 1. On the **Aggregation type** section of the **All metrics** tab, choose **Aggregation type** to view all the fleet metrics you created. 1. Choose the fleet metric to display graph on the left of the **Aggregation type** section. You will see the value *count* to the left of your **Metric name**, and this is the value of the aggregation type that you specified in the [Create fleet metrics](#fleet-metrics-tutorial-create) section of this tutorial. 1. Choose the second tab named **Graphed metrics** to the right of the **All metrics** tab to view the fleet metric you chose from the previous step. You should be able to see a graph that displays the number of sensors with temperatures higher than 80 degrees Fahrenheit like the following: ![\[AWS IoT fleet metrics\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/fm-metric-in-cloudwatch.png) **Note** The **Period** attribute in CloudWatch defaults to 5 minutes. It's the time interval between data points displaying in CloudWatch. You can change the **Period** setting based on your needs. 1. (Optional) You can set a metric alarm. 1. On the CloudWatch menu on the left panel, choose **Alarms** to expand the submenu and then choose **All alarms**. 1. On the **Alarms** page, choose **Create alarm** on the upper right corner. Follow the **Create alarm** instructions in console to create an alarm as needed. For more information, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). To learn more, read [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html). If you can't see data points in CloudWatch, read [Troubleshooting fleet metrics](fleet-indexing-troubleshooting.md#fleet-metrics-troubleshooting). ## Clean up **To delete fleet metrics** You use the **delete-fleet-metric** CLI command to delete fleet metrics. To delete the fleet metric named *high\$1temp\$1FM*, run the following command. ``` aws iot delete-fleet-metric --metric-name "high_temp_FM" ``` **To clean up things** You use the **delete-thing** CLI command to delete things. To delete the ten things that you created, run the following script: ``` # Bash script. Type `bash` before running in other shells. for ((i=0; i < 10; i++)) do thing=$(aws iot delete-thing --thing-name "TempSensor$i") done ``` **To clean up metrics in CloudWatch** CloudWatch doesn't support metrics deletion. Metrics expire based on their retention schedules. To learn more, [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html). # Managing fleet metrics This topic shows how to use the AWS IoT console and AWS CLI to manage your fleet metrics. **Topics** + [ ## Managing fleet metrics (Console) ](#managing-fleet-metrics-console) + [ ## Managing fleet metrics (CLI) ](#managing-fleet-metrics-cli) + [ ## Authorize tagging of IoT resources ](#managing-fleet-metrics-policy) ## Managing fleet metrics (Console) The following sections show how to use the AWS IoT console to manage your fleet metrics. Make sure you've enabled fleet indexing with associated data sources and configurations before creating fleet metrics. ### Enable fleet indexing If you've already enabled fleet indexing, skip this section. If you haven't enabled fleet indexing, follow these instructions. 1. Open your AWS IoT console at [https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/). 1. On the AWS IoT menu, choose **Settings**. 1. To view the detailed settings, on the **Settings** page, scroll down to the **Fleet indexing** section. 1. To update your fleet indexing settings, to the right of the **Fleet indexing** section, select **Manage indexing**. 1. On the **Manage fleet indexing** page, update your fleet indexing settings based on your needs. + **Configuration** To turn on thing indexing, toggle **Thing indexing** on, and then select the data sources you want to index from. To turn on thing group indexing, toggle **Thing group indexing** on. + **Custom fields for aggregation - *optional*** Custom fields are a list of field name and field type pairs. To add a custom field pair, choose **Add new field**. Enter a custom field name such as `attributes.temperature`, then select a field type from the **Field type** menu. Note that a custom field name begins with `attributes.` and will be saved as an attribute to run [thing aggregations queries](https://docs.aws.amazon.com/iot/latest/developerguide/index-aggregate.html). To update and save the setting, choose **Update**. ### Create a fleet metric 1. Open your AWS IoT console at [https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/). 1. On the AWS IoT menu, choose **Manage**, and then choose **Fleet metrics**. 1. On the **Fleet metrics** page, choose **Create fleet metric** and complete the creation steps. 1. In step 1 **Configure fleet metrics** + In **Query** section, enter a query string to specify the things or thing groups you want to perform the aggregate search. The query string consists of an attribute and a value. For **Properties**, choose the attribute you want, or, if it doesn't appear in the list, enter the attribute in the field. Enter the value after `:`. An example query string can be `thingName:TempSensor*`. For each query string you enter, press **enter** in your keyboard. If you enter multiple query strings, specify their relationship by selecting **and**, **or**, **and not**, or **or not** between them. + In **Report properties**, choose **Index name**, **Aggregation type**, and **Aggregation field** from their respective lists. Next, select the data you want to aggregate in **Select data**, where you can select multiple data values. + Choose **Next**. 1. In step 2 **Specify fleet metric properties** + In **Fleet metric name** field, enter a name for the fleet metric you're creating. + In **Description - *optional*** field, enter a description for the fleet metric you're creating. This field is optional. + In **Hours** and **Minutes** fields, enter the time (how often) you want the fleet metric to emit data to CloudWatch. + Choose **Next**. 1. In step 3 **Review and create** + Review the settings of step 1 and step 2. To edit the settings, choose **Edit**. + Choose **Create fleet metric**. After successful creation, the fleet metric is listed on the **Fleet metric** page. ### Update a fleet metric 1. On the **Fleet metric** page, choose the fleet metric that you want to update. 1. On the fleet metric **Details** page, choose **Edit**. This opens the creation steps where you can update your fleet metric in any of the three steps. 1. After you finish updating the fleet metric, choose **Update fleet metric**. ### Delete a fleet metric 1. On the **Fleet metric** page, choose the fleet metric that you want to delete. 1. On the next page that shows details of your fleet metric, choose **Delete**. 1. In the dialog box, enter the name of your fleet metric to confirm deletion. 1. Choose **Delete**. This step deletes your fleet metric permanently. ## Managing fleet metrics (CLI) The following sections show how to use the AWS CLI to manage your fleet metrics. Make sure you've enabled fleet indexing with associated data sources and configurations before creating fleet metrics. To enable fleet indexing for your things or thing groups, follow the instructions in [Managing thing indexing](managing-index.md#enable-index) or [Managing thing group indexing](thinggroup-index.md#enable-group-index). ### Create a fleet metric You can use the create-fleet-metric CLI command to create a fleet metric. ``` aws iot create-fleet-metric --metric-name "YourFleetMetricName" --query-string "*" --period 60 --aggregation-field "registry.version" --aggregation-type name=Statistics,values=sum ``` The output of this command contains the name and Amazon Resource Name (ARN) of your fleet metric. The output looks like the following: ``` { "metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetricName", "metricName": "YourFleetMetricName" } ``` ### List fleet metrics You can use the list-fleet-metric CLI command to list all the fleet metrics in your account. ``` aws iot list-fleet-metrics ``` The output of this command contains all your fleet metrics. The output looks like the following: ``` { "fleetMetrics": [ { "metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetric1", "metricName": "YourFleetMetric1" }, { "metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetric2", "metricName": "YourFleetMetric2" } ] } ``` ### Describe a fleet metric You can use the describe-fleet-metric CLI command to display more detailed information about a fleet metric. ``` aws iot describe-fleet-metric --metric-name "YourFleetMetricName" ``` The output of command contains the detailed information about the specified fleet metric. The output looks like the following: ``` { "queryVersion": "2017-09-30", "lastModifiedDate": 1625790642.355, "queryString": "*", "period": 60, "metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetricName", "aggregationField": "registry.version", "version": 1, "aggregationType": { "values": [ "sum" ], "name": "Statistics" }, "indexName": "AWS_Things", "creationDate": 1625790642.355, "metricName": "YourFleetMetricName" } ``` ### Update a fleet metric You can use the update-fleet-metric CLI command to update a fleet metric. ``` aws iot update-fleet-metric --metric-name "YourFleetMetricName" --query-string "*" --period 120 --aggregation-field "registry.version" --aggregation-type name=Statistics,values=sum,count --index-name AWS_Things ``` The update-fleet-metric command doesn't produce any output. You can use the describe-fleet-metric CLI command to see the result. ``` { "queryVersion": "2017-09-30", "lastModifiedDate": 1625792300.881, "queryString": "*", "period": 120, "metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetricName", "aggregationField": "registry.version", "version": 2, "aggregationType": { "values": [ "sum", "count" ], "name": "Statistics" }, "indexName": "AWS_Things", "creationDate": 1625792300.881, "metricName": "YourFleetMetricName" } ``` ### Delete a fleet metric Use the delete-fleet-metric CLI command to delete a fleet metric. ``` aws iot delete-fleet-metric --metric-name "YourFleetMetricName" ``` This command doesn't produce any output if the deletion is successful or if you specify a fleet metric that doesn't exist. For more information, see [Troubleshooting fleet metrics](fleet-indexing-troubleshooting.md#fleet-metrics-troubleshooting). ## Authorize tagging of IoT resources For better control over fleet metrics that you can create, modify, or use, you can attach tags to the fleet metrics. To tag fleet metrics that you create by using AWS Management Console or AWS CLI, you must include the `iot:TagResource` action in your IAM policy to grant the user permissions. If your IAM policy doesn't include `iot:TagResource`, any actions to create a fleet metric with a tag will return an `AccessDeniedException` error. For general information about tagging your resources, see [Tagging your AWS IoT resources](https://docs.aws.amazon.com//iot/latest/developerguide/tagging-iot.html). ### IAM policy example Refer to the following IAM policy example granting tagging permissions when you create a fleet metric: **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "iot:TagResource" ], "Effect": "Allow", "Resource": [ "arn:aws:iot:*:*:fleetmetric/*" ] }, { "Action": [ "iot:CreateFleetMetric" ], "Effect": "Allow", "Resource": [ "arn:aws:iot:*:*:index/*", "arn:aws:iot:*:*:fleetmetric/*" ] } ] } ``` For more information, see [Actions, resources, and condition keys for AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html).