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

本文档介绍如何在创建和运行批量作业时配置描述作业可运行状态的自定义状态事件。 如需了解状态事件，请参阅通过状态事件查看作业的历史记录。

通过自定义状态事件，您可以在任务历史记录中提供有关其可运行项进度的更多详细信息，使作业更易于分析和问题排查。例如，您可以配置自定义状态事件，用于描述可运行对象何时启动、可运行对象何时结束、何时到达屏障就绪状态，或者代码执行过程中发生的重要事件。

准备工作

配置自定义状态事件

在创建作业时，请使用以下一个或多个选项配置自定义状态事件：

  • 通过定义可运行进程的显示名称来描述其状态。您可以在使用 gcloud CLI 或 Batch API 创建作业时执行此操作。

  • 编写结构化任务日志，并在每个事件中使用 batch/custom/event 字段，从而指示重要的运行时事件。使用任何方法创建作业时，您可以在脚本和容器可运行对象定义中执行此操作。

描述可运行对象的状态

您可以通过定义一个可运行设备的显示名称（displayName 字段）来配置用于描述该运行对象状态的自定义状态事件。对于不同类型的可运行对象，生成的自定义状态事件会略有不同：

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

  • 如果您为屏障可运行定义了显示名称，则 Batch 会自动添加一个自定义状态事件，用于指明任务何时到达此屏障线。

如需使用描述可运行对象状态的自定义状态事件创建和运行作业，请使用 gcloud CLI 或 Batch API 为一个或多个可运行对象定义 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。

示例作业运行完毕后，每项任务生成的自定义状态事件如下所示：

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

后续步骤