runnable を説明するカスタム ステータス イベントを構成する

このドキュメントでは、バッチジョブを作成して実行するときに、ジョブの runnable を記述するカスタム ステータス イベントを構成する方法について説明します。ステータス イベントの詳細については、ステータス イベントでジョブの履歴を表示するをご覧ください。

カスタム ステータス イベントを使用すると、タスクの履歴に、runnable　の進行状況に関する追加の詳細情報が提供されるため、ジョブの分析とトラブルシューティングが容易になります。たとえば、runnable の開始、runnable の終了、barrier runnable への到達、またはコードの進行中に重要なイベントが発生することを表すカスタム ステータス イベントを構成できます。

準備

カスタム ステータス イベントを構成する

ジョブの作成時に、次の 1 つ以上のオプションを使用してカスタム ステータス イベントを構成します。

  • 表示名を定義して、runnable の状態を記述します。これは、gcloud CLI または Batch API を使用してジョブを作成するときに行うことができます。

  • 各イベントの batch/custom/event フィールドを含む構造化タスクログを書き込むことで、重要なランタイム イベントを示します。これは、任意のメソッドを使用して、script runnable とcontainer runnable の定義の一部としてジョブを作成する場合に行うことができます。

runnable の状態の説明

runnable の表示名（displayName フィールド）を定義することで、runnable の状態を記述するカスタム ステータス イベントを構成できます。生成されるカスタム ステータス イベントは、runnable のタイプによって若干異なります。

  • container runnable またはscript runnable の表示名を定義すると、Batch によって 2 種類のカスタム ステータス イベントが自動的に追加されます。最初のカスタム ステータス イベントは、タスクがこの runnable を起動するタイミングを示します。2 番目のカスタム ステータス イベントは、タスクがこの runnable と、これに対応する終了コードを終了するタイミングを示します。

  • barrier runnable の表示名を定義すると、Batch は、タスクがこの障壁に到達したときを示すカスタム ステータス イベントを自動的に追加します。

runnable の状態を記述するカスタム ステータス イベントでジョブを作成して実行するには、gcloud CLI または Batch API を使用して 1 つ以上の runnable の displayName フィールドを定義します。

...
"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 を、runnable の名前に置き換えます。これは、ジョブ内で一意である必要があります。（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）フィールドの文字列を定義する構造化タスクログを、runnable が書き込むように構成することで、runnable を実行中に重要なイベントが発生したことを示すカスタム ステータス イベントを構成できます。

container runnable または script runnable が batch/custom/event JSON フィールドを定義する構造化タスクログを書き込むと、その時点でカスタム ステータス イベントが生成されます。追加のフィールドを含めるように構造化タスクログを構成できますが、カスタム ステータス イベントには batch/custom/event フィールドの文字列のみが含まれます。

重要なイベントが発生したときを示すカスタム ステータス イベントを使用してジョブを作成して実行するには、1 つ以上の runnable を構成して、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
  ...

次のステップ