從 IoT Edge 部署擷取記錄
適用於：
IoT Edge 1.5
重要
IoT Edge 1.5 LTS 是 支援的版本。 自 2024 年 11 月 12 日起，IoT Edge 1.4 LTS 已結束生命週期。 如果您是舊版，請參閱更新 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>"
}
