写入任务日志

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

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

准备工作

  1. 如果您之前未使用过批处理功能，请参阅开始使用批处理，并完成适用于项目和用户的前提条件，以启用批处理功能。

  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: ...

后续步骤