2023 年 6 月 30 日に AWS IoT Greengrass Version 1 は延長ライフサイクルフェーズに入りました。詳細については、「AWS IoT Greengrass V1 メンテナンスポリシー」を参照してください。この日付以降、AWS IoT Greengrass V1 の機能、拡張機能、バグ修正、またはセキュリティパッチを提供するアップデートはリリースされません。AWS IoT Greengrass V1 で稼働中のデバイスは中断されず、引き続き動作し、クラウドに接続できます。重要な新機能や新たなプラットフォームのサポートが追加された AWS IoT Greengrass Version 2 への移行を強くお勧めします。
CloudWatch Metrics コネクタ
CloudWatch Metrics コネクタは、Greengrass デバイスのカスタムメトリクスを Amazon CloudWatch に発行します。このコネクタでは、CloudWatch メトリクスの発行に一元管理型のインフラストラクチャを使用して、Greengrass Core 環境をモニタリングおよび分析し、ローカルのイベントに対処できます。詳細については、「Amazon CloudWatch ユーザーガイド」の「Amazon CloudWatch メトリクスを使用する」を参照してください。
このコネクタには MQTT メッセージとしてメトリクスデータが送信されます。また、コネクタは、同じ名前空間にあるメトリクスをバッチにまとめて、定期的に CloudWatch に発行します。
このコネクタには、次のバージョンがあります。
Version |
ARN |
---|---|
5 |
|
4 |
|
3 |
|
2 |
|
1 |
|
バージョンの変更については、「Changelog」を参照してください。
要件
このコネクタには以下の要件があります。
コネクタパラメータ
このコネクタには、以下のパラメータが用意されています。
サンプルコネクタを作成する (AWS CLI)
以下の CLI コマンドは、CloudWatch Metrics コネクタを含む初期バージョンで ConnectorDefinition
を作成します。
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyCloudWatchMetricsConnector", "ConnectorArn": "arn:aws:greengrass:
region
::/connectors/CloudWatchMetrics/versions/4", "Parameters": { "PublishInterval" : "600", "PublishRegion" : "us-west-2", "MemorySize" : "16", "MaxMetricsToRetain" : "2500", "IsolationMode" : "GreengrassContainer" } } ] }'
AWS IoT Greengrass コンソールでは、グループの [Connectors] (コネクタ) ページからコネクタを追加できます。詳細については、「Greengrass コネクタの開始方法 (コンソール)」を参照してください。
入力データ
このコネクタは、MQTT トピックのメトリクスを受け取り、それを CloudWatch に発行します。入力メッセージは JSON 形式である必要があります。
- サブスクリプションのトピックフィルター
-
cloudwatch/metric/put
- メッセージのプロパティ
-
request
-
このメッセージのメトリクスに関する情報。
リクエストオブジェクトには、CloudWatch に発行するメトリクスデータが含まれています。メトリクス値は、
PutMetricData
API の仕様を満たしている必要があります。namespace
、metricData.metricName
、およびmetricData.value
プロパティのみが必須です。必須:
true
タイプ:
object
。以下のプロパティを含みます。namespace
-
このリクエスト内のメトリクスデータのユーザー定義による名前空間。CloudWatch はメトリクスデータポイントのコンテナとして名前空間を使用します。
注記
予約された文字列
AWS/
で始まる名前空間を指定することはできません。必須:
true
タイプ:
string
有効なパターン:
[^:].*
metricData
-
メトリクスのデータ。
必須:
true
タイプ:
object
。以下のプロパティを含みます。metricName
-
メトリクスの名前。
必須:
true
タイプ:
string
dimensions
-
メトリクスに関連付けられたディメンション。ディメンションは、メトリクスとそのデータに関する追加情報を提供します。1 つのメトリクスでは、最大 10 個のディメンションを定義できます。
このコネクタには
coreName
という名前のディメンションが必ず含まれ、そのコアの名前を値に持ちます。必須:
false
タイプ: 以下のプロパティを含むディメンションオブジェクトの
array
。name
-
ディメンション名。
必須:
false
タイプ:
string
value
-
ディメンション値
必須:
false
タイプ:
string
timestamp
-
メトリクスデータが受信された時刻。
Jan 1, 1970 00:00:00 UTC
からの秒数で表されます。この値を省略すると、コネクタはメッセージを受信した時刻を使用します。必須:
false
タイプ:
timestamp
注記
このコネクタのバージョン 1 から 4 を使用する場合は、1 つのソースから複数のメトリックを送信するときに、メトリックごとに個別にタイムスタンプを取得することをお勧めします。変数を使用してタイムスタンプを保存しないでください。
value
-
メトリクスの値。
注記
CloudWatch は小さすぎる値または大きすぎる値を拒否します。値は
8.515920e-109
から1.174271e+108
(基数 10)、または2e-360
から2e360
(基数 2) の範囲内であることが必要です。特殊な値 (NaN
、+Infinity
、-Infinity
など) はサポートされていません。必須:
true
タイプ:
double
unit
-
メトリクスの単位。
必須:
false
タイプ:
string
有効な値:
Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, Megabits, Gigabits, Terabits, Percent, Count, Bytes/Second, Kilobytes/Second, Megabytes/Second, Gigabytes/Second, Terabytes/Second, Bits/Second, Kilobits/Second, Megabits/Second, Gigabits/Second, Terabits/Second, Count/Second, None
- 制限
-
このコネクタを使用すると、CloudWatch
PutMetricData
API によって課せられるすべての制限がメトリクスに適用されます。以下の制限が特に重要です。-
API ペイロードに適用される 40 KB の制限
-
API リクエストごとに 20 個のメトリクス
-
PutMetricData
API の 150 トランザクション/秒 (TPS)
詳細については、「Amazon CloudWatch ユーザーガイド」の「CloudWatch の制限」を参照してください。
-
- 入力例
-
{ "request": { "namespace": "Greengrass", "metricData": { "metricName": "latency", "dimensions": [ { "name": "hostname", "value": "test_hostname" } ], "timestamp": 1539027324, "value": 123.0, "unit": "Seconds" } } }
出力データ
このコネクターは、MQTT トピックで出力データとしてステータス情報を発行します。
- サブスクリプションのトピックフィルター
-
cloudwatch/metric/put/status
- 出力例: 成功
-
レスポンスには、メトリクスデータの名前空間と CloudWatch レスポンスの
RequestId
フィールドが含まれています。{ "response": { "cloudwatch_rid":"70573243-d723-11e8-b095-75ff2EXAMPLE", "namespace": "Greengrass", "status":"success" } }
- 出力例: 失敗
-
{ "response" : { "namespace": "Greengrass", "error": "InvalidInputException", "error_message":"cw metric is invalid", "status":"fail" } }
注記
コネクタが再試行可能なエラー (接続エラーなど) を検出した場合は、次のバッチ処理で再発行を試します。
使用例
コネクタの試用に利用できる Python 3.7 Lambda 関数の例を設定するには、次のステップ (概要) を使用します。
注記
-
他の Python ランタイムを使用する場合は、Python 3.x から Python 3.7 へのシンボリックリンクを作成します。
-
「コネクタの使用を開始する (コンソール)」および「コネクタの使用を開始する (CLI)」トピックには、Twilio 通知コネクタの例を設定およびデプロイする方法を示す詳細なステップが含まれています。
-
コネクタの要件を満たしていることを確認します。
グループロール要件では、必要なアクセス許可を付与するようにロールを設定し、ロールがグループに追加されていることを確認する必要があります。詳細については、「Greengrass グループロールの管理 (コンソール)」または「Greengrass グループロールの管理 (CLI)」を参照してください。
-
入力データをコネクタに送信する Lambda 関数を作成して発行します。
サンプルコードを PY ファイルとして保存します。AWS IoT Greengrass Core SDK for Python をダウンロードして解凍します。次に、PY ファイルとルートレベルの
greengrasssdk
フォルダを含む zip パッケージを作成します。この zip パッケージは、AWS Lambda にアップロードするデプロイパッケージです。Python 3.7 Lambda 関数を作成したら、関数バージョンを公開し、エイリアスを作成します。
-
Greengrass グループを設定します。
-
エイリアスで Lambda 関数を追加します (推奨)。Lambda ライフサイクルを長期間有効に (または CLI で
"Pinned": true
に) 設定します。 -
コネクタを追加し、そのパラメータを設定します。
-
コネクタが入力データを受信し、サポートされているトピックフィルターで出力データを送信できるようにするサブスクリプションを追加します。
-
Lambda 関数をソースに、コネクタをターゲットに設定し、サポートされている入力トピックフィルターを使用します。
-
コネクタをソースとして、AWS IoT Core をターゲットとして設定し、サポートされている出力トピックフィルターを使用します。このサブスクリプションを使用して、AWS IoT コンソールでステータスメッセージを表示します。
-
-
-
グループをデプロイします。
-
AWS IoT コンソールの [Test] (テスト) ページで、出力データトピックをサブスクライブして、コネクタからのステータスメッセージを表示します。この例の Lambda 関数は長期間有効であり、グループがデプロイされた直後にメッセージの送信を開始します。
テストが終了したら、Lambda ライフサイクルをオンデマンドに (または CLI で
"Pinned": false
に) 設定して、グループをデプロイできます。これにより、関数がメッセージの送信を停止します。
例
次の例では、Lambda 関数で入力メッセージをコネクタに送信します。
import greengrasssdk import time import json iot_client = greengrasssdk.client('iot-data') send_topic = 'cloudwatch/metric/put' def create_request_with_all_fields(): return { "request": { "namespace": "Greengrass_CW_Connector", "metricData": { "metricName": "Count1", "dimensions": [ { "name": "test", "value": "test" } ], "value": 1, "unit": "Seconds", "timestamp": time.time() } } } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print("Message To Publish: ", messageToPublish) iot_client.publish(topic=send_topic, payload=json.dumps(messageToPublish)) publish_basic_message() def lambda_handler(event, context): return
ライセンス
CloudWatch Metrics コネクタには、以下のサードパーティーのソフトウェアおよびライセンスが含まれています。
-
AWS SDK for Python (Boto3)
/Apache License 2.0 -
botocore
/Apache License 2.0 -
dateutil
/PSF ライセンス -
docutils
/BSD ライセンス、GNU 一般パブリックライセンス (GPL)、Python Software Foundation ライセンス、パブリックドメイン -
jmespath
/MIT ライセンス -
s3transfer
/Apache License 2.0 -
urllib3
/MIT ライセンス
このコネクタは、Greengrass Core ソフトウェアライセンス契約
変更ログ
次の表に、コネクタの各バージョンにおける変更点を示します。
Version |
変更 |
---|---|
5 |
入力データでの重複するタイムスタンプに対応するように修正。 |
4 |
コネクタのコンテナ化モードを設定するための |
3 |
Lambda ランタイムを Python 3.7 にアップグレードしたことで、ランタイム要件が変更。 |
2 |
過剰なログ記録を減らすための修正。 |
1 |
初回リリース。 |
Greengrass グループには、一度に 1 つのバージョンのコネクタしか含めることができません。コネクタのバージョンのアップグレードについては、「コネクタのバージョンのアップグレード」を参照してください。
以下も参照してください。
-
「Amazon CloudWatch ユーザーガイド」の「Amazon CloudWatch メトリクスの使用」
-
「Amazon CloudWatch API Reference」(Amazon CloudWatch API リファレンス) の「PutMetricData」