本文档介绍了如何在创建和运行 Batch 作业时配置自定义状态事件,以描述作业的可运行对象。如需了解状态事件,请参阅通过状态事件查看作业的历史记录。
借助自定义状态事件,您可以在任务的历史记录中提供有关其可运行对象进度的更多详细信息,这有助于更轻松地分析和排查作业问题。 例如,您可以配置自定义状态事件,用于描述可运行对象何时开始、可运行对象何时结束、何时到达屏障可运行对象,或代码执行过程中何时发生重要事件。
准备工作
- 如果您之前未使用过 Batch,请查看开始使用 Batch 并完成项目和用户的前提条件,以启用 Batch。
-
如需获得创建作业所需的权限,请让您的管理员为您授予以下 IAM 角色:
-
项目的 Batch Job Editor (
roles/batch.jobsEditor
) -
服务账号用户 (
roles/iam.serviceAccountUser
) 作业的服务账号(默认情况下为默认 Compute Engine 服务账号)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
-
项目的 Batch Job Editor (
配置自定义状态事件
在创建作业时,您可以使用以下一个或多个选项来配置自定义状态事件:
通过定义可运行对象的显示名称来描述其状态。您可以在使用 gcloud CLI 或 Batch API 创建作业时执行此操作。
通过为每个事件编写带有
batch/custom/event
字段的结构化任务日志,指示重要的运行时事件。您可以在使用任何方法创建作业时执行此操作,作为脚本和容器可运行对象的定义的一部分。
描述可运行对象的状态
您可以通过定义可运行对象的显示名称(displayName
字段)来配置描述可运行对象状态的自定义状态事件。不同类型的可运行对象生成的自定义状态事件略有不同:
如果您为可运行的容器或可运行的脚本定义了显示名称,Batch 会自动添加两种类型的自定义状态事件。第一个自定义状态事件表示任务何时开始运行此可运行对象。第二个自定义状态事件表示任务何时完成此可运行对象以及相应的退出代码。
如果您为屏障可运行对象定义了显示名称,Batch 会自动添加一个自定义状态事件,用于指示任务何时到达此屏障。
如需创建并运行具有描述可运行对象状态的自定义状态事件的作业,请使用 gcloud CLI、Batch API 或库为一个或多个可运行对象定义 displayName
字段。
gcloud
使用 Google Cloud CLI 创建作业,该作业在 JSON 文件的一个或多个 runnables
定义中包含 displayName
字段:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
例如,如果作业具有描述每个可运行对象状态的自定义状态事件,则其 JSON 配置文件可能类似于以下内容:
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"displayName":"DISPLAY_NAME1",
"script": {
"text": "echo Hello world from script 1 for task ${BATCH_TASK_INDEX}"
}
},
{
"displayName":"DISPLAY_NAME2",
"barrier": {}
},
{
"displayName":"DISPLAY_NAME3",
"script": {
"text": "echo Hello world from script 2 for task ${BATCH_TASK_INDEX}"
}
}
]
},
"taskCount": 3
}
],
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
}
将 DISPLAY_NAME1
、DISPLAY_NAME2
和 DISPLAY_NAME3
替换为可运行对象的名称,该名称在作业中必须是唯一的,例如 script 1
、barrier 1
和 script 2
。
API
使用 REST API 创建作业,该作业在 JSON 文件的一个或多个 runnables
定义中包含 displayName
字段:
...
"runnables": [
{
"displayName":DISPLAY_NAME,
...
}
]
...
例如,如果作业具有描述每个可运行对象状态的自定义状态事件,则其 JSON 配置文件可能类似于以下内容:
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"displayName":"DISPLAY_NAME1",
"script": {
"text": "echo Hello world from script 1 for task ${BATCH_TASK_INDEX}"
}
},
{
"displayName":"DISPLAY_NAME2",
"barrier": {}
},
{
"displayName":"DISPLAY_NAME3",
"script": {
"text": "echo Hello world from script 2 for task ${BATCH_TASK_INDEX}"
}
}
]
},
"taskCount": 3
}
],
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
}
将 DISPLAY_NAME1
、DISPLAY_NAME2
和 DISPLAY_NAME3
替换为可运行对象的名称,该名称在作业中必须是唯一的,例如 script 1
、barrier 1
和 script 2
。
Go
Java
Node.js
Python
示例作业运行完毕后,每个任务生成的自定义状态事件类似于以下内容:
statusEvents:
...
- description: 'script at index #0 with display name [DISPLAY_NAME1] started.'
eventTime: '...'
type: RUNNABLE_EVENT
- description: 'script at index #0 with display name [DISPLAY_NAME1] finished with exit
code 0.'
eventTime: '...'
type: RUNNABLE_EVENT
- description: 'barrier at index #2 with display name [DISPLAY_NAME2] reached.'
eventTime: '...'
type: BARRIER_REACHED_EVENT
- description: 'script at index #2 with display name [DISPLAY_NAME3] started.'
eventTime: '...'
type: RUNNABLE_EVENT
- description: 'script at index #2 with display name [DISPLAY_NAME3] finished with exit
code 0.'
eventTime: '...'
type: RUNNABLE_EVENT
...
指示重要的运行时事件
您可以配置自定义状态事件,以指示可运行对象运行时何时发生重要事件,方法是配置该可运行对象以写入结构化任务日志,该日志定义了 Batch 自定义状态事件 (batch/custom/event
) 字段的字符串。
如果容器可运行对象或脚本可运行对象写入定义了 batch/custom/event
JSON 字段的结构化任务日志,则会在当时生成自定义状态事件。虽然您可以配置结构化任务日志以包含其他字段,但自定义状态事件仅包含 batch/custom/event
字段的字符串。
如需创建并运行作业,其中包含用于指示重要事件发生时间的自定义状态事件,请配置一个或多个可运行对象,以通过打印 JSON 写入结构化日志,并将 batch/custom/event
字段定义为日志的一部分。
...
"runnables": [
{
...
"echo '{\"batch/custom/event\":\"EVENT_DESCRIPTION\"}'"
...
}
]
...
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
...
例如,如果作业具有自定义状态事件来指示何时发生重要事件,则其 JSON 配置文件可能类似于以下内容:
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"script": {
"text": "sleep 30; echo '{\"batch/custom/event\": \"EVENT_DESCRIPTION\"}'; sleep 30"
}
}
]
},
"taskCount": 3
}
],
"logsPolicy": {
"destination": "CLOUD_LOGGING"
}
}
将 EVENT_DESCRIPTION
替换为自定义状态事件的说明,例如 halfway done
。
示例作业运行完毕后,每个任务生成的自定义状态事件类似于以下内容:
statusEvents:
...
- description: EVENT_DESCRIPTION
eventTime: '...'
type: RUNNABLE_CUSTOM_EVENT
...