本文档介绍了如何写入任务日志,以及如何创建和运行包含任务日志的批处理作业。
为作业启用日志记录功能后,任务日志就会根据该作业的可运行对象在运行时输出的消息生成。 通过将可运行对象配置为写入任务日志,您可以在 Cloud Logging 中显示自定义信息,这有助于使作业更易于分析和问题排查。如需详细了解日志,请参阅使用日志分析作业。
准备工作
- 如果您之前未使用过 Batch,请查看 Batch 使用入门,并在满足项目和用户的前提条件以启用 Batch。
-
如需获取创建写入日志的作业所需的权限,请让管理员向您授予以下 IAM 角色:
-
如需创建任务,请执行以下操作:
-
项目的 Batch Job Editor (
roles/batch.jobsEditor
) -
对作业的服务帐号拥有的 Service Account User (
roles/iam.serviceAccountUser
),默认为默认的 Compute Engine 服务帐号
-
项目的 Batch Job Editor (
-
如需查看日志,请执行以下操作:
针对项目的日志查看器 (
roles/logging.viewer
)
如需详细了解如何授予角色,请参阅管理访问权限。
-
如需创建任务,请执行以下操作:
创建并运行包含任务日志的作业
如需创建并运行想要包含任务日志的作业,请在创建作业时执行以下操作:
- 为作业启用日志。这样,系统就可以生成为作业写入的任何日志。
对于您希望作业包含的每个任务日志,请添加一个命令,用于将任务日志写入可运行对象。作业运行时,只要执行写入任务日志的命令,系统就会生成任务日志。
如需了解如何写入任务日志,请参阅本文档中的写入任务日志。
写入任务日志
系统会针对作业的可运行对象在运行时输出到标准输出 (stdout
) 流或标准错误 (stderr
) 流的任何内容写入任务日志。例如,您可以使用 echo
命令写入任务日志。生成的任务日志的结构取决于您设置输出内容的格式。具体来说,您可以使用以下某个选项写入每个任务日志:
通过输出字符串写入非结构化日志。 非结构化日志很简单,仅允许您定义日志的
textPayload
字段。通过输出 JSON 编写结构化日志。结构化日志需要 JSON 格式,以便您定义多个字段,包括一些标准日志字段、自定义字段和自定义状态事件。
例如,您可以使用结构化任务日志来定义日志的严重性,您可以在查看作业的日志时将其用作过滤条件。
通过输出字符串写入非结构化日志
通过非结构化日志,您可以定义消息,该消息是显示在日志的 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 对象写入结构化日志
借助结构化日志,您可以定义以下任意项:
- Cloud Logging 代理支持的标准字段
- 自定义字段
- 自定义状态事件
如需写入结构化日志,请输出 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 对象。例如,以下示例演示了输出示例 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: ...
后续步骤
- 如需详细了解如何设置日志格式,请参阅 Cloud Logging 文档中的结构化日志记录。
- 了解如何编写包含自定义状态事件的结构化任务日志。
- 了解如何查看作业的任务日志。
- 详细了解作业创建选项。