写入任务日志

本文档介绍了如何写入任务日志，以及如何创建和运行包含任务日志的 Batch 作业。

为作业启用日志记录功能后，系统会根据作业的可运行对象在运行时打印的消息生成任务日志。通过将可运行对象配置为写入任务日志，您可以在 Cloud Logging 中显示自定义信息，这有助于更轻松地分析和排查作业问题。如需详细了解日志，请参阅使用日志分析作业。

准备工作

  1. 如果您之前未使用过 Batch，请查看开始使用 Batch 并完成项目和用户的前提条件，以启用 Batch。

  2. 如需获得创建写入日志的作业所需的权限，请让您的管理员为您授予以下 IAM 角色：

    如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建并运行包含任务日志的作业

如需创建并运行需要包含任务日志的作业，请在创建作业时执行以下操作：

  1. 为作业启用日志。这样，系统便可生成为作业写入的任何日志。

  2. 对于您希望作业拥有的每个任务日志，请添加一个将任务日志写入可运行对象的命令。作业运行时，每当执行写入任务日志的命令时，系统都会生成任务日志。

    如需了解如何写入任务日志，请参阅本文档中的写入任务日志。

写入任务日志

对于作业的可运行对象在运行时打印到标准输出 (stdout) 流或标准错误 (stderr) 流的任何内容，系统都会写入任务日志。例如，您可以使用 echo 命令写入任务日志。生成的任务日志的结构因打印内容的格式而异。具体来说，您可以使用以下任一选项写入每个任务日志：

通过打印字符串写入非结构化日志

非结构化日志可让您定义一条消息，该消息是一个字符串，会显示在日志的 textPayload 字段中。

如需写入非结构化日志，请打印未格式化的字符串，如以下部分所示。

非结构化日志示例

例如，假设您需要包含以下字符串的任务日志：

MESSAGE

打印此示例字符串会生成类似于以下内容的任务日志：

insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...

替换以下内容：

  • MESSAGE：消息，即总结任务日志用途的字符串，例如 The summary for a task log.。
  • PROJECT_ID：您的项目的项目 ID。

您可以使用多种方法打印字符串，例如在可运行的脚本中添加以下 echo 命令：

echo MESSAGE

如需查看使用 echo 命令写入非结构化任务日志的作业的全面示例，请参阅创建并运行基本作业。

通过打印 JSON 对象写入结构化日志

借助结构化日志，您可以定义以下任意内容：

如需写入结构化日志，请输出 JSON 对象。以下部分演示了如何定义包含一些标准字段和自定义字段的日志。如果您想了解如何使用自定义状态事件定义日志，另请参阅配置自定义状态事件。

结构化日志示例

例如，假设您需要一个包含以下 JSON 对象中信息的任务日志，该对象定义了一条消息、严重程度和两个自定义字段。

{
  "message": "MESSAGE"
  "severity": "SEVERITY"
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
}

打印此 JSON 对象会生成类似于以下内容的任务日志：

insertId: ...
jsonPayload:
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
  message: MESSAGE
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: SEVERITY
timestamp: ...

替换以下内容：

  • MESSAGE：消息，即总结任务日志用途的字符串，例如 The summary for a task log.。
  • SEVERITY：日志的严重程度，您可以在查看作业的日志时将其用作过滤条件。 严重程度必须是 LogSeverity 枚举之一，并转换为仅将首字母大写的字符串。例如，对于 ERROR 枚举，请指定 Error。
  • CUSTOM_FIELD_1 和 CUSTOM_FIELD_2：任务日志的自定义字段名称，例如 custom_field_1 和 custom_field_2。
  • CUSTOM_VALUE_1 和 CUSTOM_VALUE_2：任务日志的自定义字段的值，可以是各种数据类型，可能需要使用引号，例如 "the first custom field" 和 2。
  • PROJECT_ID：您的项目的项目 ID。

您可以使用多种方法打印此 JSON 对象示例。 例如，以下示例演示了打印示例 JSON 对象的一些可能方法：

  • 使用 echo 命令打印等效字符串。

  • 使用 Python 打印等效的字典。

echo 命令

如需使用 echo 命令和等效字符串打印示例 JSON 对象，请在可运行的代码中添加以下命令：

echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'

例如，假设您创建并运行了具有以下可运行对象的作业：

"script": {
  "text": "echo '{\"message\":\"The message for a structured log.\", \"severity\":\"Error\", \"custom_field_1\":\"the first custom field\", \"custom_field_2\":2}'"
}

然后，生成的任务日志类似于以下内容：

insertId: ...
jsonPayload:
  custom_field_1: the first custom field
  custom_field_2: 2
  message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...

Python

如需使用 Python 和等效的字典打印示例 JSON 对象，请在可运行的代码中添加以下示例：

#!/usr/bin/env python3

import json

entry = dict(
    severity="SEVERITY",
    message="MESSAGE",
    CUSTOM_FIELD_1=CUSTOM_VALUE_1,
    CUSTOM_FIELD_2=CUSTOM_VALUE_2,
)
print(json.dumps(entry))

例如，假设您创建并运行了具有以下可运行对象的作业：

"script": {
  "text": "#!/usr/bin/env python3\n\nimport json\n\nentry = dict(\nseverity=\"Error\",\nmessage=\"The summary for a structured task log with error severity.\",\ncustom_field_1=\"the first custom field\",\ncustom_field_2=2,\n)\nprint(json.dumps(entry))"
}

然后，生成的任务日志类似于以下内容：

insertId: ...
jsonPayload:
  custom_field_1: the first custom field
  custom_field_2: 2
  message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...

后续步骤