# カスタムメトリクス 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) ## コンソールでのカスタムメトリクスの使用方法 **Topics** + [AWS IoT Device Defender Agent 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 Agent SDK (Python) 使用を開始するには、AWS IoT Device Defender Agent SDK (Python) サンプルエージェントをダウンロードします。エージェントはメトリクスを収集し、レポートを発行します。デバイス側のメトリクスを発行すると、収集されるメトリクスを表示して、アラームを設定するためのしきい値を決定できます。デバイスエージェントの設定手順については、「[AWS IoT Device Defender Agent SDK (Python) Readme](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst)」を参照してください。詳細については、「[AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python)」を参照してください。 ### カスタムメトリクスを作成し、セキュリティプロファイルに追加する 次の手順は、コンソールでカスタムメトリクスを作成する方法を示しています。 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**] (表示名) (オプション) で、カスタムメトリクスのわかりやすい名前を入力できます。名前は一意である必要はなく、作成後に変更することができます。 1. [**Type**] (タイプ) で、監視するメトリクスのタイプを選択します。メトリクスのタイプには、**string-list**、**ip-address-list**、**number-list**、および **number** が含まれます。タイプは、作成後に変更することはできません。 **注記** ML Detect では、**数値**タイプのみ使用可能です。 1. [**Tags**] (タグ) で、リソースに関連付けるタグを選択できます。 完了したら、[**Confirm**] (確認) を選択します。 1. カスタムメトリクスを作成すると、[**Custom metrics**] (カスタムメトリクス) ページが表示され、新しく作成したカスタムメトリクスを確認できます。 1. 次に、カスタムメトリクスをセキュリティプロファイルに追加する必要があります。[AWS IoT コンソール](https://console.aws.amazon.com/iot)のナビゲーションペインで、[**Defend**] (防御) を展開し、[**Detect**] (検出)、[**Security profiles**] (セキュリティプロファイル) の順に選択します。 1. カスタムメトリクスを追加するセキュリティプロファイルを選択します。 1. [**Actions**]、[**Edit**] の順に選択します。 1. [**Additional Metrics to retain**] (保持する追加のメトリクス) を選択してから、カスタムメトリクスを選択します。[**Confirm**] (確認) ページが表示されるまで、次の画面で [**Next**] (次へ) を選択します。[**Save**] (保存) と [**Continue**] (続行) を選択します。カスタムメトリクスが正常に追加されると、セキュリティプロファイルの詳細ページが表示されます。 **注記** パーセンタイル統計は、メトリクス値が負の数値のメトリクスに対して使用することはできません。 ### カスタムメトリクスの詳細を表示する 次の手順では、カスタムメトリクスの詳細をコンソールで表示する方法を示します。 1. [AWS IoT コンソール](https://console.aws.amazon.com/iot)のナビゲーションペインで、[**Defend**] (防御) を展開し、[**Detect**] (検出)、[**Metrics**] (メトリクス) の順に選択します。 1. 詳細を表示するカスタムメトリクスの [**Metric name**] (メトリクス名) を選択します。 ### カスタムメトリクスを更新する 次の手順は、コンソールでカスタムメトリクスを更新する方法を示しています。 1. [AWS IoT コンソール](https://console.aws.amazon.com/iot)のナビゲーションペインで、[**Defend**] (防御) を展開し、[**Detect**] (検出)、[**Metrics**] (メトリクス) の順に選択します。 1. 更新するカスタムメトリクスの横にあるオプションボタンを選択します。その後、[**Actions**] (アクション) で、[**Edit**] (編集) を選択します。 1. [**Update custom metric**] (カスタムメトリクスの更新) ページで、表示名を編集したり、タグを削除または追加したりできます。 1. 完了したら、[**Update**] (更新) を選択します。[**Custom metrics**] (カスタムメトリクス) ページ。 ### カスタムメトリクスを削除する 次の手順は、コンソールでカスタムメトリクスを削除する方法を示しています。 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 からのカスタムメトリクスの使用方法 **Topics** + [AWS IoT Device Defender Agent 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 Agent SDK (Python) 使用を開始するには、AWS IoT Device Defender Agent SDK (Python) サンプルエージェントをダウンロードします。エージェントはメトリクスを収集し、レポートを発行します。デバイス側のメトリクスを発行したら、収集するメトリクスを表示して、アラームを設定するためのしきい値を決定できます。デバイスエージェントの設定手順については、「[AWS IoT Device Defender Agent SDK (Python) Readme](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python/blob/master/README.rst)」を参照してください。詳細については、「[AWS IoT Device Defender Agent SDK (Python)](https://github.com/aws-samples/aws-iot-device-defender-agent-sdk-python)」を参照してください。 ### カスタムメトリクスを作成し、セキュリティプロファイルに追加する 次の手順では、カスタムメトリクスを作成し、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" } ``` **注記** パーセンタイル統計は、メトリクス値が負の数値のメトリクスに対して使用することはできません。 ### カスタムメトリクスの詳細を表示する 次の手順は、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" ] } ``` ### カスタムメトリクスを更新する 次の手順は、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" } ``` ### カスタムメトリクスを削除する 次の手順は、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 コマンド 以下の 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 次の 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)