# Métricas personalizadas
<a name="dd-detect-custom-metrics"></a>

Com as métricas personalizadas do AWS IoT Device Defender, você pode definir e monitorar métricas exclusivas de sua frota ou caso de uso, como número de dispositivos conectados a gateways Wi-Fi, níveis de carga para baterias ou número de ciclos de energia para tomadas inteligentes. Os comportamentos das métricas personalizadas são definidos nos Perfis de segurança, que especificam os comportamentos esperados de um grupo de dispositivos (um grupo de objetos) ou para todos os dispositivos. Você pode monitorar os comportamentos configurando alarmes, que podem ser usados para detectar e responder a problemas específicos dos dispositivos.

**Topics**
+ [Como usar as métricas personalizadas no console](#dd-detect-custom-metrics-how-to-console)
+ [Como usar métricas personalizadas da CLI](#dd-detect-custom-metrics-how-to-cli)
+ [Comandos de métricas personalizadas da CLI](#dd-detect-custom-metrics-cli-commands)
+ [APIs de métricas personalizadas](#dd-detect-custom-metrics-apis)

## Como usar as métricas personalizadas no console
<a name="dd-detect-custom-metrics-how-to-console"></a>

**Topics**
+ [AWS IoT Device Defender Agent SDK (Python)](#dd-detect-custom-metrics-device-agent)
+ [Crie uma métrica personalizada e adicione-a a um Perfil de segurança](#dd-detect-console-create)
+ [Exibir detalhes da métrica personalizada](#dd-detect-console-read)
+ [Atualizar uma métrica personalizada](#dd-detect-console-edit)
+ [Excluir uma métrica personalizada](#dd-detect-console-delete)

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

Para começar, baixe o atendente de amostra do AWS IoT Device Defender Agent SDK (Python). O atendente reúne as métricas e publica relatórios. Depois que suas métricas do lado do dispositivo forem publicadas, será possível visualizar as métricas que estão sendo coletadas e determinar os limites para a configuração de alarmes. As instruções para configurar o atendente do dispositivo estão disponíveis no Readme do [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). Para obter mais informações, consulte [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).

### Crie uma métrica personalizada e adicione-a a um Perfil de segurança
<a name="dd-detect-console-create"></a>

O procedimento a seguir mostra como criar uma métrica personalizada no console.

1. No [console da AWS IoT](https://console.aws.amazon.com/iot), no painel de navegação, expanda **Defend**, escolha **Detect** e, em seguida, **Métricas**.

1. Na página **Métricas personalizadas**, escolha **Criar**.

1. Na página **Criar métrica personalizada**, faça o seguinte.

   1. Em **Nome**, insira um nome para a métrica personalizada. Não é possível modificar esse nome depois da criação da métrica personalizada.

   1. Em **Nome de exibição (opcional)**, você pode inserir um nome fácil para a métrica personalizada. Ele não precisa ser exclusivo e pode ser modificado após a criação.

   1. Em **Tipo**, escolha o tipo de métrica que você gostaria de monitorar. Os tipos de métricas incluem **string-list**, **ip-address-list**, **number-list** e **number**. O tipo não pode ser modificado após a criação.
**nota**  
O ML Detect permite apenas o tipo de **number**.

   1. Em **Tags**, você pode selecionar as tags que devem ser associadas ao recurso.

   Quando terminar, escolha **Confirmar**.

1. Depois de criar sua métrica personalizada, a página **Métricas personalizadas** será exibida, onde você pode ver sua métrica personalizada recém-criada.

1. Em seguida, você precisa adicionar sua métrica personalizada a um Perfil de segurança. No [console da AWS IoT](https://console.aws.amazon.com/iot), no painel de navegação, expanda **Defend**, escolha **Detect** e, em seguida, **Perfis de segurança**.

1. Escolha o Perfil de segurança ao qual você gostaria de adicionar a métrica personalizada.

1. Selecione **Ações**, **Editar**.

1. Escolha **Métricas adicionais a serem retidas** e, em seguida, escolha sua métrica personalizada. Escolha **Próximo** nas telas seguintes até chegar à página **Confirmar**. Escolha **Salvar** e **Continuar**. Depois que sua métrica personalizada for adicionada com sucesso, a página de detalhes do Perfil de segurança será exibida.
**nota**  
As estatísticas de percentil não estão disponíveis para métricas quando qualquer um dos valores de métrica são números negativos.

### Exibir detalhes da métrica personalizada
<a name="dd-detect-console-read"></a>

O procedimento a seguir mostra como visualizar os detalhes de uma métrica personalizada, no console.

1. No [console da AWS IoT](https://console.aws.amazon.com/iot), no painel de navegação, expanda **Defend**, escolha **Detect** e, em seguida, **Métricas**.

1. Escolha o **Nome da métrica** personalizada da qual você gostaria de ver os detalhes.

### Atualizar uma métrica personalizada
<a name="dd-detect-console-edit"></a>

O procedimento a seguir mostra como atualizar uma métrica personalizada no console.

1. No [console da AWS IoT](https://console.aws.amazon.com/iot), no painel de navegação, expanda **Defend**, escolha **Detect** e, em seguida, **Métricas**.

1. Selecione o botão de opção ao lado da métrica personalizada que você deseja atualizar. Então, em **Ações**, escolha **Editar**.

1. Na página **Atualizar métrica personalizada**, você pode editar o nome de exibição e remover ou adicionar tags.

1. Quando tiver terminado, escolha **Atualizar**. A página de **Métricas personalizadas**.

### Excluir uma métrica personalizada
<a name="dd-detect-console-delete"></a>

O procedimento a seguir mostra como excluir uma métrica personalizada, no console.

1. Primeiro, remova sua métrica personalizada de qualquer Perfil de segurança em que ela esteja referenciada. Você pode ver quais Perfis de segurança contêm a métrica personalizada, na página de detalhes da métrica personalizada. No [console da AWS IoT](https://console.aws.amazon.com/iot), no painel de navegação, expanda **Defend**, escolha **Detect** e, em seguida, **Métricas**.

1. Escolha a métrica personalizada que você gostaria de remover. Remova a métrica personalizada de qualquer Perfil de segurança listado em **Perfis de Segurança**, na página de detalhes da métrica personalizada.

1. No [console da AWS IoT](https://console.aws.amazon.com/iot), no painel de navegação, expanda **Defend**, escolha **Detect** e, em seguida, **Métricas**.

1. Selecione o botão de opção ao lado da métrica personalizada que você deseja excluir. Então, em **Ações**, escolha **Excluir**.

1. Na mensagem **Tem certeza de que deseja excluir a métrica personalizada?**, escolha **Excluir métrica personalizada**.
**Atenção**  
Depois de excluir uma métrica personalizada, você perderá todos os dados associados a ela. Essa ação não pode ser desfeita.

## Como usar métricas personalizadas da CLI
<a name="dd-detect-custom-metrics-how-to-cli"></a>

**Topics**
+ [AWS IoT Device Defender Agent SDK (Python)](#dd-detec-custom-metrics-cli-sdk)
+ [Crie uma métrica personalizada e adicione-a a um Perfil de segurança](#dd-detect-custom-cli-create)
+ [Exibir detalhes da métrica personalizada](#dd-detect-custom-cli-read)
+ [Atualizar uma métrica personalizada](#dd-detect-custom-cli-edit)
+ [Excluir uma métrica personalizada](#dd-detect-custom-cli-delete)

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

Para começar, baixe o atendente de amostra do AWS IoT Device Defender Agent SDK (Python). O atendente reúne as métricas e publica relatórios. Após suas métricas do lado do dispositivo serem publicadas, será possível visualizar as métricas que estão sendo coletadas e determinar os limites para a configuração de alarmes. As instruções para configurar o atendente do dispositivo estão disponíveis no Readme do [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). Para obter mais informações, consulte [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).

### Crie uma métrica personalizada e adicione-a a um Perfil de segurança
<a name="dd-detect-custom-cli-create"></a>

O procedimento a seguir mostra como criar uma métrica personalizada e adicioná-la a um Perfil de segurança usando a CLI.

1. Use o comando `[create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)` para criar sua métrica personalizada. O exemplo a seguir cria uma métrica personalizada que mede a porcentagem da bateria.

   ```
   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" \
   ```

   Saída:

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

1. Depois de criar sua métrica personalizada, você pode adicioná-la a um perfil de segurança existente usando `[update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)` ou criar um novo para usando o `[create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)`. Aqui estamos criando um perfil de segurança novo chamado *batteryUsage* a que adicionaremos nossa nova métrica personalizada *batteryPercentage*. Também adicionamos uma métrica de regras do Detect chamada *cellularBandwidth*.

   ```
   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
   ```

   Saída:

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

**nota**  
As estatísticas de percentil não estão disponíveis para métricas quando qualquer um dos valores de métrica são números negativos.

### Exibir detalhes da métrica personalizada
<a name="dd-detect-custom-cli-read"></a>

O procedimento a seguir mostra como visualizar os detalhes de uma métrica personalizada da CLI.
+ Use o comando `[list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)` para visualizar todas as métricas personalizadas.

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

  A saída deste comando é semelhante à apresentada a seguir.

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

### Atualizar uma métrica personalizada
<a name="dd-detect-custom-cli-edit"></a>

O procedimento a seguir mostra como atualizar uma métrica personalizada da CLI.
+ Use o comando `[update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)` para atualizar uma métrica personalizada. O exemplo a seguir atualiza o `display-name`.

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

  A saída deste comando é semelhante à apresentada a seguir.

  ```
  {
      "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"
  }
  ```

### Excluir uma métrica personalizada
<a name="dd-detect-custom-cli-delete"></a>

O procedimento a seguir mostra como excluir uma métrica personalizada da CLI.

1. Para excluir uma métrica personalizada, primeiro remova-a de todos os Perfis de segurança aos quais ela está anexada. Use o comando `[list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)` para visualizar Perfis de segurança com uma determinada métrica personalizada.

1. Para remover uma métrica personalizada de um Perfil de segurança, use o comando `[update-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profiles.html)`. Insira todas as informações que deseja manter, mas exclua a métrica personalizada:

   ```
   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}}]"
   ```

   A saída deste comando é semelhante à apresentada a seguir.

   ```
   {
     "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. Depois que a métrica personalizada for desanexada, use o comando `[delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)` para excluir a métrica personalizada.

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

   A saída do comando é semelhante à seguinte

   ```
   HTTP 200
   ```

## Comandos de métricas personalizadas da CLI
<a name="dd-detect-custom-metrics-cli-commands"></a>

Você pode usar os seguintes comandos da CLI para criar e gerenciar métricas personalizadas.
+ [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)

## APIs de métricas personalizadas
<a name="dd-detect-custom-metrics-apis"></a>

As seguintes APIs podem ser usadas para criar e gerenciar as métrica personalizadas.
+ [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)
+ [CustomMetrics](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteCustomMetric.html)
+ [ListSecurityProfiles](https://docs.aws.amazon.com/iot/latest/apireference/API_ListSecurityProfiles.html)