このドキュメントでは、バッチジョブを作成して実行するときに、ジョブの runnable を記述するカスタム ステータス イベントを構成する方法について説明します。ステータス イベントの詳細については、ステータス イベントでジョブの履歴を表示するをご覧ください。
カスタム ステータス イベントを使用すると、タスクの履歴に、runnable の進行状況に関する追加の詳細情報が提供されるため、ジョブの分析とトラブルシューティングが容易になります。たとえば、runnable の開始、runnable の終了、barrier runnable への到達、またはコードの進行中に重要なイベントが発生することを表すカスタム ステータス イベントを構成できます。
準備
- Batch を以前に使用したことがなかった場合は、Batch を使ってみるを確認し、プロジェクトとユーザーの前提条件を完了して Batch を有効にします。
-
ジョブの作成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
-
プロジェクトのバッチジョブ編集者(
roles/batch.jobsEditor
) -
ジョブのサービス アカウントのサービス アカウント ユーザー(
roles/iam.serviceAccountUser
)。これは、デフォルトでは Compute Engine のデフォルトのサービス アカウントです。
ロールの付与の詳細については、アクセスの管理をご覧ください。
-
プロジェクトのバッチジョブ編集者(
カスタム ステータス イベントを構成する
ジョブの作成時に、次の 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
...
次のステップ
- ジョブの作成または実行に問題がある場合は、トラブルシューティングをご覧ください。
- ステータス イベントを表示する方法を確認する。
- タスクログを書き込む方法を学習する。
- 別のジョブ作成オプションを学習する。