# Métriques personnalisées
<a name="dd-detect-custom-metrics"></a>

Grâce aux métriques AWS IoT Device Defender personnalisées, vous pouvez définir et surveiller des métriques propres à votre flotte ou à votre cas d'utilisation, telles que le nombre d'appareils connectés aux passerelles Wi-Fi, les niveaux de charge des batteries ou le nombre de cycles d'alimentation des prises intelligentes. Les comportements de métriques personnalisés sont définis dans les Profils de Sécurité, qui spécifient les comportements attendus pour un groupe d'appareils (un groupe d'objets) ou pour tous les appareils. Vous pouvez surveiller les comportements en configurant des alarmes, que vous pouvez utiliser pour détecter et répondre aux problèmes spécifiques aux appareils.

**Topics**
+ [Comment utiliser des métriques personnalisées dans la console](#dd-detect-custom-metrics-how-to-console)
+ [Comment utiliser les métriques personnalisées à partir de la CLI](#dd-detect-custom-metrics-how-to-cli)
+ [Commandes CLI de métriques personnalisées](#dd-detect-custom-metrics-cli-commands)
+ [API des métriques personnalisées](#dd-detect-custom-metrics-apis)

## Comment utiliser des métriques personnalisées dans la 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)
+ [Créez une métrique personnalisée et ajoutez-la à un Profil de Sécurité](#dd-detect-console-create)
+ [Afficher les détails des métriques personnalisées](#dd-detect-console-read)
+ [Mettre à jour une métrique personnalisée](#dd-detect-console-edit)
+ [Suppression d'une métrique personnalisée](#dd-detect-console-delete)

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

Pour commencer, téléchargez l’échantillonAWS IoT Device Defender Agent SDK (Python). L'agent rassemble les métriques et publie des rapports. Une fois que les métriques côté appareil sont publiées, vous pouvez consulter les métriques collectées et déterminer les seuils de configuration des alarmes. Les instructions de configuration de l'agent de périphérique sont disponibles dans [AWS IoT Device Defender Agent SDK (Python) Readme](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). Pour plus d'informations, consultez [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).

### Créez une métrique personnalisée et ajoutez-la à un Profil de Sécurité
<a name="dd-detect-console-create"></a>

La procédure suivante vous montre comment créer une métrique personnalisée dans la console.

1. Dans la [AWS IoT console](https://console.aws.amazon.com/iot), dans le panneau de navigation, développez **Defend**, puis **Détecter**, **Métriques**..

1. Sur la page **Custom metrics (Mesures personnalisées)**, choisissez **Create (Créer)**.

1. Sur la page **Create your message (Créer une métrique personnalisée)**, procédez comme suit.

   1. Sous **Name (Nom)**, entrez le nom de votre métrique personnalisée. Vous ne pouvez pas modifier ce nom après avoir créé la métrique personnalisée.

   1. Sous **Nom d'affichage (facultatif)**, vous pouvez saisir un nom convivial pour votre métrique personnalisée. Ils n'ont pas besoin d'être uniques et peuvent être modifiés après leur création.

   1. Sous **Type**, choisissez le type de métrique que vous souhaitez surveiller. Les types de métriques incluent **string-list**, **ip-address-list**, **number-list**, et **number (numéro)**. Le type ne peut pas être modifié après sa création.
**Note**  
ML Detect n'autorise que le type de **number**.

   1. Sous **Tags (Balises)**, vous pouvez sélectionner les balises à associer à la ressource.

   Lorsque vous avez terminé, choisissez **Confirm (Confirmer)**.

1. Une fois que vous avez créé votre métrique personnalisée, la page **Mesures personnalisées** apparaît, où vous pouvez voir la métrique personnalisée que vous venez de créer.

1. Ensuite, vous devez ajouter votre métrique personnalisée à un Profil de Sécurité. Dans la [AWS IoT console](https://console.aws.amazon.com/iot), dans le panneau de navigation, développez **Defend**, puis sélectionnez **Detect**, **Profils de sécurité**.

1. Choisissez le profil de sécurité auquel vous souhaitez ajouter votre métrique personnalisée.

1. Choisissez **Actions**, **Modifier**.

1. Choisissez ** Additional Metrics to retain (les mesures supplémentaires à conserver)**, puis choisissez votre métrique personnalisée. Choisissez **Suivant** sur les écrans suivants jusqu'à ce que vous atteigniez la page de **Confirmer**. Choisissez **Enregistrer** et **Continuer**. Une fois que votre métrique personnalisée a été ajoutée avec succès, la page des détails du profil de sécurité apparaît.
**Note**  
Les statistiques sur les centiles ne sont pas disponibles pour les métriques lorsque l'une des valeurs des métriques est un nombre négatif.

### Afficher les détails des métriques personnalisées
<a name="dd-detect-console-read"></a>

La procédure suivante vous montre comment afficher les détails d'une métrique personnalisée dans la console.

1. Dans [AWS IoT console](https://console.aws.amazon.com/iot), dans le panneau de navigation, développez **Defend**, puis **Détecter**, **Métriques**.

1. Choisissez le **Metric name** (nom de la métrique) personnalisée dont vous souhaitez afficher les détails.

### Mettre à jour une métrique personnalisée
<a name="dd-detect-console-edit"></a>

La procédure suivante vous montre comment mettre à jour une métrique personnalisée dans la console.

1. Dans [AWS IoT console](https://console.aws.amazon.com/iot), dans le panneau de navigation, développez **Defend**, puis **Détecter**, **Métriques**.

1. Sélectionnez le bouton d'option en regard de la métrique personnalisée à mettre à jour. Ensuite, pour **Actions**, choisissez **Modifier**.

1. Sur la page **Update custom metric** (Mettre à jour une métrique personnalisée), vous pouvez modifier le nom d'affichage et supprimer ou ajouter des balises.

1. Lorsque vous avez terminé, sélectionnez **Update**. (Mettre à jour) La page **Custom metrics** (métriques personnalisées).

### Suppression d'une métrique personnalisée
<a name="dd-detect-console-delete"></a>

La procédure suivante vous montre comment supprimer une métrique personnalisée dans la console.

1. Tout d'abord, supprimez votre métrique personnalisée de tout profil de sécurité dans lequel elle est référencée. Vous pouvez voir quels profils de sécurité contiennent votre métrique personnalisée sur la page détails de votre métrique personnalisée. Dans [AWS IoT console](https://console.aws.amazon.com/iot), dans le panneau de navigation, développez **Defend**, puis **Détecter**, **Métriques**.

1. Choisissez la métrique personnalisée que vous souhaitez supprimer. Supprimez la métrique personnalisée de tout profil de sécurité répertorié sous **Security Profiles** sur la page détails des métriques personnalisées.

1. Dans [AWS IoT console](https://console.aws.amazon.com/iot), dans le panneau de navigation, développez **Defend**, puis **Détecter**, **Métriques**.

1. Sélectionnez le bouton d'option en regard de la métrique personnalisée à supprimer. Ensuite, pour **Actions**, choisissez **Supprimer**.

1. Sur le champ **Êtes-vous sûr de vouloir supprimer une métrique personnalisée ?**, choisissez **Supprimer la métrique personnalisée**.
**Avertissement**  
Une fois que vous avez supprimé une métrique personnalisée, vous perdez toutes les données associées à cette métrique. Cette action ne peut pas être annulée.

## Comment utiliser les métriques personnalisées à partir de la 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)
+ [Créez une métrique personnalisée et ajoutez-la à un profil de sécurité](#dd-detect-custom-cli-create)
+ [Afficher les détails des métriques personnalisées](#dd-detect-custom-cli-read)
+ [Mettre à jour une métrique personnalisée](#dd-detect-custom-cli-edit)
+ [Suppression d'une métrique personnalisée](#dd-detect-custom-cli-delete)

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

Pour commencer, téléchargez l’échantillonAWS IoT Device Defender Agent SDK (Python). L'agent rassemble les métriques et publie des rapports. Une fois les métriques côté appareil publiées, vous pouvez afficher les métriques collectées et déterminer les seuils de configuration des alarmes. Les instructions de configuration de l'agent de l’appareil sont disponibles dans [AWS IoT Device Defender Agent SDK (Python) Readme](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst). Pour plus d'informations, consultez [AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python).

### Créez une métrique personnalisée et ajoutez-la à un profil de sécurité
<a name="dd-detect-custom-cli-create"></a>

La procédure suivante vous montre comment créer une métrique personnalisée et l'ajouter à un profil de sécurité à partir de la CLI.

1. Utilisez ensuite la commande `[create-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/create-custom-metric.html)` pour créer votre métrique personnalisée. L'exemple suivant crée une métrique personnalisée qui mesure le pourcentage de batterie.

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

   Sortie :

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

1. Après avoir créé votre métrique personnalisée, vous pouvez soit l'ajouter à un profil existant à l'aide de `[update-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profile.html)`, soit créer un nouveau profil de sécurité pour ajouter la métrique personnalisée à l'aide de `[create-security-profile](https://docs.aws.amazon.com/cli/latest/reference/iot/create-security-profile.html)`. Ici, nous créons un nouveau profil de sécurité appelé *BatteryUsage* pour ajouter notre nouvelle métrique personnalisée *BatteryPercentage* à. Nous ajoutons également une métrique Rules Detect appelée *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
   ```

   Sortie :

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

**Note**  
Les statistiques sur les centiles ne sont pas disponibles pour les métriques lorsque l'une des valeurs des métriques est un nombre négatif.

### Afficher les détails des métriques personnalisées
<a name="dd-detect-custom-cli-read"></a>

La procédure suivante vous montre comment afficher les détails d'une métrique personnalisée à partir de la CLI.
+ Utilisez la commande `[list-custom-metrics](https://docs.aws.amazon.com/cli/latest/reference/iot/list-custom-metrics.html)` pour afficher toutes vos statistiques personnalisées.

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

  La sortie de cette commande ressemble à ce qui suit.

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

### Mettre à jour une métrique personnalisée
<a name="dd-detect-custom-cli-edit"></a>

La procédure suivante vous montre comment mettre à jour une métrique personnalisée à partir de la CLI.
+ Utilisez la commande `[update-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/update-custom-metric.html)` pour mettre à jour une métrique personnalisée. L'exemple suivant met à jour le `display-name`.

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

  La sortie de cette commande ressemble à ce qui suit.

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

### Suppression d'une métrique personnalisée
<a name="dd-detect-custom-cli-delete"></a>

La procédure suivante vous montre comment supprimer une métrique personnalisée de la CLI.

1. Pour supprimer une métrique personnalisée, supprimez-la d’abord de tous les profils de sécurité auxquels elle est associée. Utilisez la commande `[list-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/list-security-profiles.html)` pour afficher les profils de sécurité avec une certaine métrique personnalisée.

1. Pour supprimer une métrique personnalisée d'un profil de sécurité, utilisez la commande `[update-security-profiles](https://docs.aws.amazon.com/cli/latest/reference/iot/update-security-profiles.html)`. Saisissez toutes les informations que vous souhaitez conserver, mais excluez la métrique personnalisée.

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

   La sortie de cette commande ressemble à ce qui suit.

   ```
   {
     "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. Une fois la métrique personnalisée détachée, utilisez la commande `[delete-custom-metric](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-custom-metric.html)` pour supprimer la métrique personnalisée.

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

   La sortie de cette commande ressemble à ce qui suit

   ```
   HTTP 200
   ```

## Commandes CLI de métriques personnalisées
<a name="dd-detect-custom-metrics-cli-commands"></a>

Vous pouvez utiliser les commandes CLI suivantes pour créer et gérer des métriques personnalisées.
+ [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 des métriques personnalisées
<a name="dd-detect-custom-metrics-apis"></a>

Les API suivantes peuvent être utilisées pour créer et gérer des métriques personnalisées.
+ [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)