IoT Edge の展開からログを取得する
適用対象:
IoT Edge 1.5 IoT Edge 1.4
重要
サポートされているリリースは、IoT Edge 1.5 LTS と IoT Edge 1.4 LTS です。 IoT Edge 1.4 LTS は、2024 年 11 月 12 日にサポートが終了します。 以前のリリースの場合は、「IoT Edge を更新する」を参照してください。
IoT Edge エージェント モジュールに含まれているダイレクト メソッドを使用して、デバイスへの物理的または SSH アクセスを必要とせずに、IoT Edge の展開からログを取得します。 ダイレクト メソッドはデバイスに実装され、その後クラウドから呼び出すことができます。 IoT Edge エージェントには、IoT Edge デバイスをリモートで監視および管理できるようにするダイレクト メソッドが含まれています。 この記事で説明するダイレクト メソッドは、1.0.10 リリースで一般提供されています。
ダイレクト メソッドの詳細、使用方法、独自のモジュールに実装する方法については、「IoT Hub からのダイレクト メソッドの呼び出しについて」を参照してください。
これらのダイレクト メソッドの名前は、大文字と小文字を区別して処理されます。
推奨されるログ形式
必須ではありませんが、この機能との最適な互換性のために、推奨されているログ形式を次に示します。
<{Log Level}> {Timestamp} {Message Text}
{Timestamp} は yyyy-MM-dd HH:mm:ss.fff zzz のように書式設定する必要があり、{Log Level} は次の表を使用して指定する必要があります。この表にある重大度レベルは、Syslog 標準の重大度コードに基づいたものです。
| Value | 重要度 |
|---|---|
| 0 | 緊急 |
| 1 | アラート: |
| 2 | Critical |
| 3 | エラー |
| 4 | 警告 |
| 5 | 通知 |
| 6 | Informational |
| 7 | デバッグ |
IoT Edge の Logger クラスは、canonical 実装として機能します。
モジュール ログを取得する
GetModuleLogs ダイレクト メソッドを使用して、IoT Edge モジュールのログを取得します。
ヒント
取得するログの範囲を制限するには、since および until フィルター オプションを使用します。 このダイレクト メソッドを境界なしで呼び出すとすべてのログが取得され、サイズが大きくなるか、時間がかかるか、コストが高くつく可能性があります。
Azure portal の IoT Edge のトラブルシューティング ページは、モジュール ログを表示するための簡単なエクスペリエンスを提供します。 詳細については、「Azure portal から IoT Edge デバイスを監視およびトラブルシューティングする」を参照してください。
このメソッドは、次のスキーマを持つ JSON ペイロードを受け取ります。
{
"schemaVersion": "1.0",
"items": [
{
"id": "regex string",
"filter": {
"tail": "int",
"since": "string",
"until": "string",
"loglevel": "int",
"regex": "regex string"
}
}
],
"encoding": "gzip/none",
"contentType": "json/text"
}
| 名前 | 種類 | 説明 |
|---|---|---|
| schemaVersion | string | 1.0 に設定 |
| アイテム | JSON 配列 | id および filter の組を含む配列。 |
| id | string | モジュール名を指定する正規表現。 エッジ デバイス上の複数のモジュールと一致させることができます。 .NET の正規表現の形式が必要です。 ID が同じモジュールと一致する項目が複数ある場合、最初に一致する ID のフィルター オプションのみがそのモジュールに適用されます。 |
| フィルター | JSON セクション | 組になった id 正規表現と一致するモジュールに適用されるログ フィルター。 |
| tail | integer | 最新から始めて取得される過去のログ行の数。 省略可能。 |
| 次の日時以降 | string | rfc3339 タイムスタンプ、UNIX タイムスタンプ、または期間 (日 (d) 時間 (h) 分 (m)) として指定するこの日時以降のログのみを取得します。 たとえば、1 日、12 時間、30 分の期間は、1 day 12 hours 30 minutes または 1d 12h 30m と指定できます。 tail と since の両方が指定された場合、最初に since 値を使用してログが取得されます。 次に、tail の値が結果に適用され、最終的な結果が返されます。 省略可能。 |
| until | string | rfc3339 タイムスタンプ、UNIX タイムスタンプ、または期間 (日 (d) 時間 (h) 分 (m)) として指定する日時以前のログのみを取得します。 たとえば、期間 90 分は、90 minutes または 90m と指定できます。 tail と since の両方が指定された場合、最初に since 値を使用してログが取得されます。 次に、tail の値が結果に適用され、最終的な結果が返されます。 省略可能。 |
| loglevel | integer | 指定されたログ レベルに等しいログ行をフィルター処理します。 ログ行は推奨されるログ形式に従い、Syslog の重大度レベルの標準を使用する必要があります。 複数のログ レベル重大度値でフィルター処理する必要がある場合、異なる重大度レベルをログに記録するときにモジュールが何らかの一貫した形式に従っているのであれば、正規表現の一致を使用します。 省略可能。 |
| regex | string | .NET の正規表現の形式を使用して、指定された正規表現と一致するコンテンツを含むログ行をフィルター処理します。 省略可能。 |
| encoding | string | gzip または none のいずれかです。 既定値は none です。 |
| contentType | string | json または text のいずれかです。 既定値は text です。 |
Note
ログ コンテンツが、現在 128 KB のダイレクト メソッドの応答サイズの制限を超えた場合、応答はエラーを返します。
ログを正常に取得すると、 "status":200 が返され、要求で指定した設定によってフィルター処理された、モジュールから取得されたログを含むペイロードが後に続きます。
次に例を示します。
az iot hub invoke-module-method --method-name 'GetModuleLogs' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
'
Azure portal で、メソッド名 GetModuleLogs と次の JSON ペイロードを指定してメソッドを呼び出します。
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
また、CLI 出力を gzip のような Linux ユーティリティにパイプして、圧縮された応答を処理することもできます。 次に例を示します。
az iot hub invoke-module-method \
--method-name 'GetModuleLogs' \
-n <hub name> \
-d <device id> \
-m '$edgeAgent' \
--method-payload '{"contentType": "text","schemaVersion": "1.0","encoding": "gzip","items": [{"id": "edgeHub","filter": {"since": "2d","tail": 1000}}],}' \
-o tsv --query 'payload[0].payloadBytes' \
| base64 --decode \
| gzip -d
モジュール ログをアップロードする
UploadModuleLogs ダイレクト メソッドを使用して、指定された Azure Blob Storage コンテナーに要求されたログを送信します。
Note
取得するログの範囲を制限するには、since および until フィルター オプションを使用します。 このダイレクト メソッドを境界なしで呼び出すとすべてのログが取得され、サイズが大きくなるか、時間がかかるか、コストが高くつく可能性があります。
ゲートウェイ デバイスの背後にあるデバイスからログをアップロードする場合は、API プロキシと Blob Storage モジュールが最上位層デバイスに構成されている必要があります。 これらのモジュールは、ゲートウェイ デバイスを介して下位層のデバイスからクラウド内のストレージにログをルーティングします。
このメソッドは、"sasUrl" キーを追加することで、GetModuleLogs に似た JSON ペイロードを受け入れます。
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS URL",
"items": [
{
"id": "regex string",
"filter": {
"tail": "int",
"since": "string",
"until": "string",
"loglevel": "int",
"regex": "regex string"
}
}
],
"encoding": "gzip/none",
"contentType": "json/text"
}
| 名前 | 種類 | 説明 |
|---|---|---|
| sasURL | string (URI) | Azure Blob Storage コンテナーへの書き込みアクセスを含む共有アクセス署名 URL。 |
ログのアップロード要求が成功すると、 "status":200 が返され、次のスキーマを持つペイロードが後に続きます。
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 名前 | 種類 | Description |
|---|---|---|
| status | string | NotStarted、Running、Completed、Failed、または Unknownの 1 つ。 |
| message | string | エラーの場合はメッセージ、それ以外の場合は空の文字列。 |
| correlationId | string | アップロード要求の状態を照会するための ID。 |
次に例を示します。
次の呼び出しによって、すべてのモジュールから最新の100 のログ行を、圧縮された JSON 形式でアップロードします。
az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": ".*",
"filter": {
"tail": 100
}
}
],
"encoding": "gzip",
"contentType": "json"
}
'
次の呼び出しによって、edgeAgent および edgeHub からの最新の 100 のログ行と、tempSensor モジュールからの最新の 1000 のログ行が、圧縮されていないテキスト形式でアップロードします。
az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edge",
"filter": {
"tail": 100
}
},
{
"id": "tempSensor",
"filter": {
"tail": 1000
}
}
],
"encoding": "none",
"contentType": "text"
}
'
Azure portal で、次の情報を含めた sasURL を指定した後に、メソッド名 UploadModuleLogs と次の JSON ペイロードを指定してメソッドを呼び出します。
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
サポート バンドル診断をアップロードする
UploadSupportBundle ダイレクト メソッドを使用して、IoT Edge モジュール ログの zip ファイルをバンドルし、使用可能な Azure Blob Storage コンテナーにアップロードします。 このダイレクト メソッドによって、IoT Edge デバイス上で iotedge support-bundle コマンドが実行されて、ログが取得されます。
Note
ゲートウェイ デバイスの背後にあるデバイスからログをアップロードする場合は、API プロキシと Blob Storage モジュールが最上位層デバイスに構成されている必要があります。 これらのモジュールは、ゲートウェイ デバイスを介して下位層のデバイスからクラウド内のストレージにログをルーティングします。
このメソッドは、次のスキーマを持つ JSON ペイロードを受け取ります。
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| 名前 | 種類 | 説明 |
|---|---|---|
| schemaVersion | string | 1.0 に設定 |
| sasURL | string (URI) | Azure Blob Storage コンテナーへの書き込みアクセスを含む共有アクセス署名 URL |
| 次の日時以降 | string | rfc3339 タイムスタンプ、UNIX タイムスタンプ、または期間 (日 (d) 時間 (h) 分 (m)) として指定するこの日時以降のログのみを取得します。 たとえば、1 日、12 時間、30 分の期間は、1 day 12 hours 30 minutes または 1d 12h 30m と指定できます。 省略可能。 |
| until | string | rfc3339 タイムスタンプ、UNIX タイムスタンプ、または期間 (日 (d) 時間 (h) 分 (m)) として指定する日時以前のログのみを取得します。 たとえば、期間 90 分は、90 minutes または 90m と指定できます。 省略可能。 |
| edgeRuntimeOnly | boolean | true の場合、Edge Agent、Edge Hub、および Edge Security Daemon からのログのみを返します。 既定値は false です。 省略可能。 |
重要
IoT Edge サポート バンドルには、個人を特定できる情報が含まれている場合があります。
ログのアップロード要求が成功すると、 "status":200 が返され、UploadModuleLogs 応答と同じスキーマを持つペイロードが後に続きます。
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 名前 | 種類 | Description |
|---|---|---|
| status | string | NotStarted、Running、Completed、Failed、または Unknownの 1 つ。 |
| message | string | エラーの場合はメッセージ、それ以外の場合は空の文字列。 |
| correlationId | string | アップロード要求の状態を照会するための ID。 |
次に例を示します。
az iot hub invoke-module-method --method-name 'UploadSupportBundle' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
'
Azure portal で、次の情報を含めた sasURL を指定した後に、メソッド名 UploadSupportBundle と次の JSON ペイロードを指定してメソッドを呼び出します。
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
アップロード要求の状態を取得する
GetTaskStatus ダイレクト メソッドを使用して、アップロード ログ要求の状態を照会します。 GetTaskStatus 要求ペイロードは、アップロード ログ要求の correlationId を使用して、タスクの状態を取得します。 correlationId は、UploadModuleLogs ダイレクト メソッド呼び出しの応答内で返されます。
このメソッドは、次のスキーマを持つ JSON ペイロードを受け取ります。
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
ログのアップロード要求が成功すると、 "status":200 が返され、UploadModuleLogs 応答と同じスキーマを持つペイロードが後に続きます。
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 名前 | 種類 | Description |
|---|---|---|
| status | string | NotStarted、Running、Completed、Failed、'Cancelled'、Unknown のいずれか。 |
| message | string | エラーの場合はメッセージ、それ以外の場合は空の文字列。 |
| correlationId | string | アップロード要求の状態を照会するための ID。 |
次に例を示します。
az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
'
Azure portal で、次の情報を含めた GUID を指定した後に、メソッド名 GetTaskStatus と次の JSON ペイロードを指定してメソッドを呼び出します。
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
