配置自定义状态事件来描述可运行对象

本文档介绍了如何配置自定义状态事件，其中介绍了 。 要了解状态事件，请参阅 通过状态事件查看任务记录。

通过自定义状态事件，您可以在任务历史记录中提供更多详细信息 可运行其可运行项的进度，这有助于 更易于分析和排查问题。 例如，您可以配置自定义状态事件， 用于说明可运行对象何时开始、可运行对象何时结束 达到可运行状态时，或者在 您的代码。

准备工作

  1. 如果您以前没有使用过 Batch，请参阅 Batch 使用入门 并通过填写 针对项目和用户的前提条件。

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

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

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

配置自定义状态事件

使用以下一项或多项内容来配置自定义状态事件 在创建作业时选择以下选项：

  • 描述可运行对象的状态 方法是定义其显示名称您可以在使用 gcloud CLI 或 Batch API 创建作业时执行此操作。

  • 指明重要的运行时事件 使用 batch/custom/event 字段写入结构化任务日志 事件。您可以在使用任何方法创建作业时执行此操作 作为脚本和容器可运行对象定义的一部分。

描述可运行对象的状态

您可以通过以下方式配置描述可运行对象状态的自定义状态事件： 定义可运行对象的显示名称 （displayName 字段）。 对于不同类型的对象，所生成的自定义状态事件 Runnable：

  • 如果您为容器可运行或脚本可运行指定显示名称， 则 Batch 会自动添加两种类型的自定义状态事件 第一个自定义状态事件表示的是任务每次启动 。第二个自定义状态事件用于指明任务何时完成 这个可运行对象和相应的 退出代码。

  • 如果您为某个对象指定了 屏障可运行， 然后，Batch 会自动添加一个 指示任务何时到达此屏障。

要创建并运行包含自定义状态事件（描述 可运行的状态，则定义 displayName 字段以声明一个或多个 使用 gcloud CLI 或 Batch API 创建可运行容器。

...
"runnables": [
  {
    "displayName":DISPLAY_NAME,
    ...
  }
]
...

例如，某个作业的自定义状态事件描述每个 runnable 的状态可以具有类似于以下内容的 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。

示例作业运行完毕后，每项任务生成的自定义状态事件类似于以下内容：

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

后续步骤