检索 IoT Edge 部署中的日志

  • 项目

适用于：IoT Edge 1.4 checkmark 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 模块的日志。

提示

使用 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" 
    }
名称 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。

注意

如果日志内容超出了直接方法的响应大小限制（目前为 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"
    }

Screenshot of how to invoke direct method GetModuleLogs in the Azure portal.

你还可以将 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 代理和 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"
    }

Screenshot of how to invoke direct method UploadModuleLogs in the Azure portal.

上传支持捆绑诊断

使用 UploadSupportBundle 直接方法将 IoT Edge 模块日志的 zip 文件捆绑并上传到可用的 Azure Blob 存储容器。 此直接方法在 IoT Edge 设备上运行 iotedge support-bundle 命令以获取日志。

注意

若要从网关设备后的设备上传日志，需要在顶层设备上配置 API 代理和 blob 存储模块。 这些模块通过网关设备将日志从较低层设备路由到云中的存储。

此方法接受具有以下架构的 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。 可选。

重要

IoT Edge 支持捆绑可能包含个人身份信息。

上传日志请求成功后，会返回“状态: 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
    }

Screenshot showing how to invoke direct method UploadSupportBundle in the Azure portal.

获取上传请求状态

使用 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>"
    }

Screenshot showing how to invoke direct method GetTaskStatus in Azure portal .

后续步骤

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