# 自定义指标
<a name="dd-detect-custom-metrics"></a>

借助 AWS IoT Device Defender 自定义指标，您可以定义和监控实例集或使用案例独有的指标，例如连接到 Wi-Fi 网关的设备数量、电池的充电量或智能插头的电源周期次数。自定义指标行为在安全配置文件中定义，其为设备组（事物组）或所有设备指定了预期行为。您可以通过设置告警来监控行为，该告警可用来检测和响应特定于设备的问题。

**Topics**
+ [

## 如何在控制台中使用自定义指标
](#dd-detect-custom-metrics-how-to-console)
+ [

## 如何使用 CLI 中的自定义指标
](#dd-detect-custom-metrics-how-to-cli)
+ [

## 自定义指标 CLI 命令
](#dd-detect-custom-metrics-cli-commands)
+ [

## 自定义指标 API
](#dd-detect-custom-metrics-apis)

## 如何在控制台中使用自定义指标
<a name="dd-detect-custom-metrics-how-to-console"></a>

**Topics**
+ [

### AWS IoT Device Defender 代理 SDK (Python)
](#dd-detect-custom-metrics-device-agent)
+ [

### 创建自定义指标并将其添加到安全配置文件
](#dd-detect-console-create)
+ [

### 查看自定义指标详细信息
](#dd-detect-console-read)
+ [

### 更新自定义指标
](#dd-detect-console-edit)
+ [

### 删除自定义指标
](#dd-detect-console-delete)

### AWS IoT Device Defender 代理 SDK (Python)
<a name="dd-detect-custom-metrics-device-agent"></a>

首先，请下载 AWS IoT Device Defender 代理 SDK (Python) 示例代理。代理将收集指标并发布报告。设备端指标发布后，您可以查看正在收集的指标并确定设置告警的阈值。有关设置设备代理的说明，请参阅 [AWS IoT Device Defender 代理 SDK (Python) 自述文件](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst)。有关更多信息，请参阅 [AWS IoT Device Defender 代理 SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python)。

### 创建自定义指标并将其添加到安全配置文件
<a name="dd-detect-console-create"></a>

以下流程介绍了如何使用控制台创建自定义指标。

1. 在 [AWS IoT 控制台](https://console.aws.amazon.com/iot)的导航窗格中，展开 **Defend**（防护），然后选择 **Detect**（检测）、**Metrics**（指标）。

1. 在 **Custom metrics**（自定义指标）页面上，选择 **Create**（创建）。

1. 在 **Create custom metric**（创建自定义指标）页面上，执行以下操作。

   1. 在 **Name**（名称）项下，输入自定义指标的名称。创建自定义指标之后，您无法修改此名称。

   1. 在 **Display name (optional)**（显示名称（可选））项下，您可以输入自定义指标的友好名称。它不需要是唯一的，并且可以在创建后进行修改。

   1. 在 **Type**（类型）中，选择要监控的指标类型。指标类型包括 **string-list**（字符串列表）、**ip-address-list**（IP 地址列表）、**number-list**（编号列表）和 **number**（编号）。创建后无法修改类型。
**注意**  
ML Detect 仅允许 **number**（数值）类型。

   1. 在 **Tags**（标签）项下，您可以选择要与资源关联的标签。

   完成后，选择 **Confirm**（确认）。

1. 创建自定义指标后，将会显示 **Custom metrics**（自定义指标）页面，您可以在其中查看新创建的自定义指标。

1. 接下来，您需要将自定义指标添加到安全配置文件。在 [AWS IoT 控制台](https://console.aws.amazon.com/iot)中的导航窗格中，展开 **Defend**（防护），然后选择 **Detect**（检测）、**Security profiles**（安全配置文件）。

1. 选择您要添加自定义指标的安全配置文件。

1. 选择 **Actions**（操作）和 **Edit**（编辑）。

1. 选择 **Addtional Metrics to retain**（要保留的其它指标），然后选择您的自定义指标。在以下页面选择 **Next**（下一步），直到您到达 **Confirm**（确认）页面。选择 **Save**（保存）和 **Continue**（继续）。成功添加自定义指标后，将会显示安全配置文件详细信息页面。
**注意**  
当任何指标值为负数时，百分位数统计数据不可用于指标。

### 查看自定义指标详细信息
<a name="dd-detect-console-read"></a>

以下流程介绍了如何在控制台中查看自定义指标的详细信息。

1. 在 [AWS IoT 控制台](https://console.aws.amazon.com/iot)的导航窗格中，展开 **Defend**（防护），然后选择 **Detect**（检测）、**Metrics**（指标）。

1. 选择您想要查看详细信息的自定义指标的 **Metric name**（指标名称）。

### 更新自定义指标
<a name="dd-detect-console-edit"></a>

以下流程说明如何使用控制台更新自定义指标。

1. 在 [AWS IoT 控制台](https://console.aws.amazon.com/iot)的导航窗格中，展开 **Defend**（防护），然后选择 **Detect**（检测）、**Metrics**（指标）。

1. 选择要更新的自定义指标旁边的选项按钮。然后，在 **Actions**（操作）中，选择 **Edit**（编辑）。

1. 在 **Update custom metrics**（更新自定义指标）页面上，您可以编辑显示名称及删除或添加标签。

1. 完成后，选择 **Update**（更新）。**Custom metrics**（自定义指标）页面。

### 删除自定义指标
<a name="dd-detect-console-delete"></a>

以下流程介绍了如何使用控制台删除自定义指标。

1. 首先，从引用的任何安全配置文件中删除您的自定义指标。您可以在自定义指标详细信息页面上查看哪些安全配置文件包含了您的自定义指标。在 [AWS IoT 控制台](https://console.aws.amazon.com/iot)的导航窗格中，展开 **Defend**（防护），然后选择 **Detect**（检测）、**Metrics**（指标）。

1. 选择您要删除的自定义指标。从自定义指标详细新页面上的 **Security Profiles**（安全配置文件）下列示的任何安全配置文件中删除自定义指标。

1. 在 [AWS IoT 控制台](https://console.aws.amazon.com/iot)的导航窗格中，展开 **Defend**（防护），然后选择 **Detect**（检测）、**Metrics**（指标）。

1. 选择要删除的自定义指标旁边的选项按钮。然后，对于 **Actions**（操作），选择 **Delete**（删除）。

1. 在 **Are you sure you want to delete custom metric?**（是否确定要删除自定义指标）消息上，选择 **Delete custom metric**（删除自定义指标）。
**警告**  
删除自定义指标后，将丢失与该指标关联的所有数据。此操作无法撤消。

## 如何使用 CLI 中的自定义指标
<a name="dd-detect-custom-metrics-how-to-cli"></a>

**Topics**
+ [

### AWS IoT Device Defender 代理 SDK (Python)
](#dd-detec-custom-metrics-cli-sdk)
+ [

### 创建自定义指标并将其添加到安全配置文件
](#dd-detect-custom-cli-create)
+ [

### 查看自定义指标详细信息
](#dd-detect-custom-cli-read)
+ [

### 更新自定义指标
](#dd-detect-custom-cli-edit)
+ [

### 删除自定义指标
](#dd-detect-custom-cli-delete)

### AWS IoT Device Defender 代理 SDK (Python)
<a name="dd-detec-custom-metrics-cli-sdk"></a>

首先，请下载 AWS IoT Device Defender 代理 SDK (Python) 示例代理。代理将收集指标并发布报告。发布设备端指标后，您可以查看正在收集的指标并确定设置告警的阈值。有关设置设备代理的说明，请参阅 [AWS IoT Device Defender 代理 SDK (Python) 自述文件](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst)。有关更多信息，请参阅 [AWS IoT Device Defender 代理 SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python)。

### 创建自定义指标并将其添加到安全配置文件
<a name="dd-detect-custom-cli-create"></a>

以下流程介绍如何从 CLI 创建自定义指标并将其添加到安全配置文件。

1. 使用 `[create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)` 命令创建自定义指标。以下示例创建用于测量电池百分比的自定义指标。

   ```
   aws iot create-custom-metric \
       --metric-name "batteryPercentage" \
       --metric-type "number" \
       --display-name "Remaining battery percentage." \
       --region us-east-1
       --client-request-token "02ccb92b-33e8-4dfa-a0c1-35b181ed26b0" \
   ```

   输出：

   ```
   {
       "metricName": "batteryPercentage",
       "metricArn": "arn:aws:iot:us-east-1:1234564789012:custommetric/batteryPercentage"
   }
   ```

1. 创建自定义量度指标后，您可以使用 `[update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)` 将自定义指标添加到现有配置文件或使用`[create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)` 创建新的配置文件以便添加自定义指标。在这里，我们新建一个名为 *batteryUsage* 的安全配置文件，以便将我们的新 *batteryPercentage* 自定义指标添加到其中。我们还添加了一个名为 *cellularBandwidth* 的 Rules Detect 指标。

   ```
   aws iot create-security-profile \
       --security-profile-name batteryUsage \
       --security-profile-description "Shows how much battery is left in percentile."  \
       --behaviors "[{\"name\":\"great-than-75\",\"metric\":\"batteryPercentage\",\"criteria\":{\"comparisonOperator\":\"greater-than\",\"value\":{\"number\":75},\"consecutiveDatapointsToAlarm\":5,\"consecutiveDatapointsToClear\":1}},{\"name\":\"cellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]" \
       --region us-east-1
   ```

   输出：

   ```
   {
       "securityProfileArn": "arn:aws:iot:us-east-1:1234564789012:securityprofile/batteryUsage",
       "securityProfileName": "batteryUsage"
   }
   ```

**注意**  
当任何指标值为负数时，百分位数统计数据不可用于指标。

### 查看自定义指标详细信息
<a name="dd-detect-custom-cli-read"></a>

以下流程介绍如何从 CLI 查看自定义指标的详细信息。
+ 使用 `[list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)` 命令查看所有自定义指标。

  ```
  aws iot list-custom-metrics \
      --region us-east-1
  ```

  此命令的输出如下所示。

  ```
  {
      "metricNames": [
          "batteryPercentage"
      ]
  }
  ```

### 更新自定义指标
<a name="dd-detect-custom-cli-edit"></a>

以下流程介绍如何从 CLI 更新自定义指标。
+ 使用 `[update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)` 命令更新自定义指标。以下示例将更新 `display-name`。

  ```
  aws iot update-custom-metric \
      --metric-name batteryPercentage \
      --display-name 'remaining battery percentage on device' \
      --region us-east-1
  ```

  此命令的输出如下所示。

  ```
  {
      "metricName": "batteryPercentage",
      "metricArn": "arn:aws:iot:us-east-1:1234564789012:custommetric/batteryPercentage",
      "metricType": "number",
      "displayName": "remaining battery percentage on device",
      "creationDate": "2020-11-17T23:01:35.110000-08:00",
      "lastModifiedDate": "2020-11-17T23:02:12.879000-08:00"
  }
  ```

### 删除自定义指标
<a name="dd-detect-custom-cli-delete"></a>

以下流程介绍如何从 CLI 中删除自定义指标。

1. 要删除自定义指标，请先将其从附加到的任何安全配置文件中删除。使用 `[list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)` 命令查看具有特定自定义指标的安全配置文件。

1. 要从安全配置文件中删除自定义指标，请使用 `[update-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profiles.html)` 命令。输入要保留的所有信息，但排除自定义指标。

   ```
   aws iot update-security-profile \
     --security-profile-name batteryUsage \
     --behaviors "[{\"name\":\"cellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}]"
   ```

   此命令的输出如下所示。

   ```
   {
     "behaviors": [{\"name\":\"cellularBandwidth\",\"metric\":\"aws:message-byte-size\",\"criteria\":{\"comparisonOperator\":\"less-than\",\"value\":{\"count\":128},\"consecutiveDatapointsToAlarm\":1,\"consecutiveDatapointsToClear\":1}}],
     "securityProfileName": "batteryUsage",
     "lastModifiedDate": 2020-11-17T23:02:12.879000-09:00,
     "securityProfileDescription": "Shows how much battery is left in percentile.",
     "version": 2,
     "securityProfileArn": "arn:aws:iot:us-east-1:1234564789012:securityprofile/batteryUsage",  
     "creationDate": 2020-11-17T23:02:12.879000-09:00
   }
   ```

1. 分离自定义指标后，使用 `[delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)` 命令删除自定义指标。

   ```
   aws iot delete-custom-metric  \
     --metric-name batteryPercentage \
     --region us-east-1
   ```

   此命令的输出如下所示

   ```
   HTTP 200
   ```

## 自定义指标 CLI 命令
<a name="dd-detect-custom-metrics-cli-commands"></a>

可以使用以下 CLI 命令来创建和管理自定义指标。
+ [create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)
+ [describe-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-custom-metric.html)
+ [list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)
+ [update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)
+ [delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)
+ [list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)

## 自定义指标 API
<a name="dd-detect-custom-metrics-apis"></a>

以下 API 可用于创建和管理自定义指标。
+ [CreateCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateCustomMetric.html)
+ [DescribeCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeCustomMetric.html)
+ [ListCustomMetrics](https://docs.aws.amazon.com/iot/latest/apireference/API_ListCustomMetrics.html)
+ [UpdateCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateCustomMetric.html)
+ [DeleteCustomMetric](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCustomMetric.html)
+ [ListSecurityProfiles](https://docs.aws.amazon.com/iot/latest/apireference/API_ListSecurityProfiles.html)