检索 IoT Edge 部署中的日志

适用于： IoT Edge 1.5 IoT Edge 1.4

检索 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 标准中的严重性代码推导出其严重性级别。

值	Severity
0	紧急情况
1	警报
2	严重
3	错误
4	警告
5	通知
6	信息
7	调试

IoT Edge 中的记录器类充当规范实现。

检索模块日志

使用 GetModuleLogs 直接方法检索 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" 
    }

名称	Type	描述
schemaVersion	字符串	设置为 1.0
items	JSON 数组	具有 id 和 filter 元组的数组。
id	字符串	提供模块名称的正则表达式。 它可以匹配边缘设备上的多个模块。 应为 .NET 正则表达式格式。 如果有其 ID 与同一模块匹配的多个项，则只会将第一个匹配 ID 的筛选器选项应用于该模块。
filter	JSON 部分	要应用于与元组中 id 正则表达式匹配的模块的日志筛选器。
tail	integer	从最新日志行开始检索的过去的日志行数。 可选。
since	字符串	只返回此时间之后的日志，作为 rfc3339 时间戳、UNIX 时间戳或持续时间（天 (d) 小时 (h) 分钟 (m)）。 例如，可以将一天、12 小时和 30 分钟的持续时间指定为“1 天 12 小时 30 分钟”或“1d 12h 30m”。 如果同时指定 tail 和 since，将首先使用 since 值检索日志。 然后，将 tail 值应用于结果，并返回最终结果。 可选。
until	字符串	仅返回指定时间之前的日志，作为 rfc3339 时间戳、UNIX 时间戳或持续时间（天 (d) 小时 (h) 分钟 (m)）。 例如，可以将持续时间 90 分钟指定为“90 分钟”或“90m”。 如果同时指定 tail 和 since，将首先使用 since 值检索日志。 然后，将 tail 值应用于结果，并返回最终结果。 可选。
loglevel	integer	筛选等于指定日志级别的日志行。 日志行应遵循推荐的日志记录格式，并采用 Syslog 严重性级别标准。 如果你需要按多个日志级别严重性值进行筛选，请依赖于正则表达式匹配（前提是模块在记录不同的严重性级别时遵循某种一致的格式）。 可选。
regex	字符串	使用 .NET 正则表达式格式，筛选内容与指定正则表达式匹配的日志行。 可选。
encoding	字符串	gzip 或 none。 默认为 none。
contentType	字符串	json 或 text。 默认为 text。

日志检索成功后，会返回“状态: 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 存储容器。

此方法接受类似于 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" 
    }

名称	Type	描述
sasURL	字符串 (URI)	对 Azure Blob 存储容器具有写入权限的共享访问签名 URL。

上传日志请求成功后，会返回“状态: 200”，后跟具有以下架构的有效负载：

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }

名称	Type	说明
status	字符串	NotStarted、Running、Completed、Failed 或 Unknown 中的一个。
message	字符串	如果错误，则为消息；否则为空字符串。
correlationId	字符串	用于查询上传请求状态的 ID。

例如：

以下调用将以压缩的 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 命令以获取日志。

此方法接受具有以下架构的 JSON 有效负载：

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }

名称	Type	描述
schemaVersion	字符串	设置为 1.0
sasURL	字符串 (URI)	对 Azure Blob 存储容器具有写入权限的共享访问签名 URL
since	字符串	只返回此时间之后的日志，作为 rfc3339 时间戳、UNIX 时间戳或持续时间（天 (d) 小时 (h) 分钟 (m)）。 例如，可以将一天、12 小时和 30 分钟的持续时间指定为“1 天 12 小时 30 分钟”或“1d 12h 30m”。 可选。
until	字符串	仅返回指定时间之前的日志，作为 rfc3339 时间戳、UNIX 时间戳或持续时间（天 (d) 小时 (h) 分钟 (m)）。 例如，可以将持续时间 90 分钟指定为“90 分钟”或“90m”。 可选。
edgeRuntimeOnly	boolean	如果为 true，则仅从 Edge 代理、Edge 中心和 Edge 安全守护程序返回日志。 默认值：false。 可选。

上传日志请求成功后，会返回“状态: 200”，后跟架构与 UploadModuleLogs 响应相同的有效负载：

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }

名称	Type	说明
status	字符串	NotStarted、Running、Completed、Failed 或 Unknown 中的一个。
message	字符串	如果错误，则为消息；否则为空字符串。
correlationId	字符串	用于查询上传请求状态的 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 门户中，用你的信息填充 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>"
    }

上传日志请求成功后，会返回“状态: 200”，后跟架构与 UploadModuleLogs 响应相同的有效负载：

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }

名称	Type	说明
status	string	NotStarted、Running、Completed、Failed、“Cancelled”或 Unknown 之一。
message	字符串	如果错误，则为消息；否则为空字符串。
correlationId	字符串	用于查询上传请求状态的 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 门户中，用你的信息填充 GUID 后，调用名为 GetTaskStatus 且包含以下 JSON 有效负载的方法：

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

后续步骤

IoT Edge 代理和 IoT Edge 中心模块孪生的属性