從 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 代理程式模組中包含的直接方法，從 IoT Edge 部署擷取記錄，而不需要裝置的實體或 SSH 存取權。 直接方法會在裝置上實作，然後可從雲端叫用。 IoT Edge 代裝程式包含直接方法，可協助您從遠端監視和管理 IoT Edge 裝置。 本文中討論的直接方法已正式推出 1.0.10 版。
如需有關直接方法如何使用及如何在自己的模組中實作的詳細資訊，請參閱了解 IoT 中樞的直接方法並從中樞叫用直接方法。
這些直接方法的名稱會區分大小寫。
建議的記錄格式
雖然並非必要，但為了與這項功能達到最佳相容性，建議的記錄格式為：
<{Log Level}> {Timestamp} {Message Text}
{Timestamp} 應該格式化為 yyyy-MM-dd HH:mm:ss.fff zzz，而且 {Log Level} 應該使用下表，其會從 Syslog 標準中的嚴重性程式代碼衍生其嚴重性層級。
| 值 | 嚴重性 |
|---|---|
| 0 | 緊急服務 |
| 1 | 警示 |
| 2 | 重大 |
| 3 | 錯誤 |
| 4 | 警告 |
| 5 | 注意事項 |
| 6 | 資訊 |
| 7 | 偵錯 |
IoT Edge 中的記錄器類別可作為標準實作。
擷取模組記錄
使用 GetModuleLogs 直接方法來擷取 IoT Edge 模組的記錄。
提示
使用 since 和 until 篩選選項來限制記錄擷取範圍。 在沒有界限的情況下呼叫此直接方法會擷取所有記錄，而所有記錄可能會很大、耗時或成本高昂。
Azure 入口網站中的 [IoT Edge 疑難排解] 頁面提供簡化的檢視模組記錄體驗。 如需詳細資訊，請參閱從 Azure 入口網站監視 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 規則運算式格式。 如果有多個專案識別碼符合相同的模組，則只會將第一個相符標識碼的篩選選項套用至該模組。 |
| 篩選器 | JSON 區段 | 要套用至 Tuple 中 id 規則運算式符合模組的記錄篩選。 |
| tail | 整數 | 要擷取的過去記錄行數目 (從最新記錄開始)。 選擇性。 |
| 自 | string | 僅傳回自此時間以來的記錄，其形式為 rfc3339 時間戳記、UNIX 時間戳記或持續時間 (天 (d) 小時 (小時) 分鐘 (m))。 例如，一天、12 小時和 30 分鐘的持續時間可以指定為 1 天 12 小時 30 分鐘 或 1d 12h 30m。 如果同時指定 tail 和 since ，則會先使用 since 值來擷取記錄。 然後，tail 值會套用至結果，並傳回最終結果。 選擇性。 |
| 直到 | string | 僅傳回特定時間以前的記錄，其形式為 rfc3339 時間戳記、UNIX 時間戳記或持續時間 (天 (d) 小時 (小時) 分鐘 (m))。 例如，您可以將持續時間 90 分鐘指定為 90 分鐘或 90m。 如果同時指定 tail 和 since ，則會先使用 since 值來擷取記錄。 然後，tail 值會套用至結果，並傳回最終結果。 選擇性。 |
| loglevel | 整數 | 篩選等於指定記錄層級的記錄行。 記錄行應遵循建議的記錄格式，並使用 Syslog 嚴重性層級標準。 如果您需要依多個記錄層級嚴重性值進行篩選，請依賴 RegEx 比對，但前提是模組在記錄不同嚴重性層級時會遵循一些一致格式。 選擇性。 |
| RegEx | string | 使用 .NET 規則運算式 格式篩選內容符合指定規則運算式的記錄行。 選擇性。 |
| 編碼 | string | gzip 或 none。 預設值為 none。 |
| contentType | string | json 或 text。 預設值為 text。 |
注意
如果記錄內容超過直接方法的回應大小限制 (目前為 128 KB)，則回應會傳回錯誤。
成功擷取記錄會傳回「狀態」：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 入口網站中，使用方法名稱 GetModuleLogs 和下列 JSON 承載，叫用方法：
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
您也可以使用管線將 CLI 傳送至 Linux 公用程式 (例如 gzip) 以處理壓縮的回應。 例如：
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 儲存體容器。
注意
使用 since 和 until 篩選選項來限制記錄擷取範圍。 在沒有界限的情況下呼叫此直接方法會擷取所有記錄，而所有記錄可能會很大、耗時或成本高昂。
如果您想要從閘道裝置後方的裝置上傳記錄，最上層裝置上必須設定 API Proxy 和 Blob 儲存體模組。 這些模組會透過閘道裝置，將記錄從較低層裝置路由至雲端中的儲存體。
此方法會接受類似 GetModuleLogs 的 JSON 承載，並新增 "sasUrl" 機碼：
{
"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 | 字串 (URI) | 具有 Azure Blob 儲存體容器寫入權限的共用存取簽章 URL。 |
上傳記錄的成功要求會傳回「狀態」：200，後面接著結構描述如下的承載：
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 名稱 | 類型 | 描述 |
|---|---|---|
| status | 字串 | NotStarted、Running、Completed、Failed 或 Unknown 的其中一個。 |
| message | string | 如果發生錯誤，則為訊息，否則為空字串。 |
| correlationId | string | 要查詢上傳要求狀態的識別碼。 |
例如：
下列叫用會以壓縮的 JSON 格式，從所有模組上傳最後 100 個記錄行：
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 入口網站中，將您的資訊填入 sasURL 後，使用方法名稱 UploadModuleLogs 和下列 JSON 承載叫用方法：
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
上傳支援套件組合診斷
使用 UploadSupportBundle 直接方法，將 IoT Edge 模組記錄組合成 zip 檔案並上傳至可用的 Azure Blob 儲存體容器。 此直接方法會在 IoT Edge 裝置上執行 iotedge support-bundle 命令，以取得記錄。
注意
如果您想要從閘道裝置後方的裝置上傳記錄，最上層裝置上必須設定 API Proxy 和 Blob 儲存體模組。 這些模組會透過閘道裝置，將記錄從較低層裝置路由至雲端中的儲存體。
此方法接受具有下列結構描述的 JSON 承載：
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| 名稱 | 類型 | 描述 |
|---|---|---|
| schemaVersion | string | 設定為 1.0 |
| sasURL | 字串 (URI) | 具有 Azure Blob 儲存體容器寫入權限的共用存取簽章 URL |
| 自 | string | 僅傳回自此時間以來的記錄，其形式為 rfc3339 時間戳記、UNIX 時間戳記或持續時間 (天 (d) 小時 (小時) 分鐘 (m))。 例如，一天、12 小時和 30 分鐘的持續時間可以指定為 1 天 12 小時 30 分鐘 或 1d 12h 30m。 選擇性。 |
| 直到 | string | 僅傳回特定時間以前的記錄，其形式為 rfc3339 時間戳記、UNIX 時間戳記或持續時間 (天 (d) 小時 (小時) 分鐘 (m))。 例如，您可以將持續時間 90 分鐘指定為 90 分鐘或 90m。 選擇性。 |
| edgeRuntimeOnly | boolean | 如果為 true，則只會從 Edge 代理程式、Edge 中樞和 Edge 安全性精靈傳回記錄。 預設：false。 選擇性。 |
重要
IoT Edge 支援套件組合可能包含個人識別資訊。
上傳記錄的成功要求會傳回 「狀態」：200，後面接著結構描述與 UploadModuleLogs 回應相同的承載：
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 名稱 | 類型 | 描述 |
|---|---|---|
| status | 字串 | NotStarted、Running、Completed、Failed 或 Unknown 的其中一個。 |
| message | string | 如果發生錯誤，則為訊息，否則為空字串。 |
| correlationId | string | 要查詢上傳要求狀態的識別碼。 |
例如：
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 入口網站中，將您的資訊填入 sasURL 後，使用方法名稱 UploadSupportBundle 和下列 JSON 承載叫用方法：
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
取得上傳要求狀態
使用 GetTaskStatus 直接方法來查詢上傳記錄要求的狀態。 GetTaskStatus 要求承載會使用上傳記錄要求的 correlationId 來取得工作的狀態。 correlationIdUploadModuleLogs 直接方法呼叫的回應中會傳回 。
此方法接受具有下列結構描述的 JSON 承載：
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
上傳記錄的成功要求會傳回 「狀態」：200，後面接著結構描述與 UploadModuleLogs 回應相同的承載：
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 名稱 | 類型 | 描述 |
|---|---|---|
| status | 字串 | NotStarted、Running、Completed、Failed、'Cancelled' 或 Unknown 的其中一個。 |
| message | string | 如果發生錯誤，則為訊息，否則為空字串。 |
| correlationId | string | 要查詢上傳要求狀態的識別碼。 |
例如：
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 入口網站中，將您的資訊填入 GUID 後，使用方法名稱 GetTaskStatus 和下列 JSON 承載叫用方法：
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
