本文說明如何設定自訂狀態事件,以便在建立及執行 Batch 工作時,描述工作可執行的項目。如要瞭解狀態事件,請參閱「透過狀態事件查看工作記錄」。
自訂狀態事件可讓您在工作歷史記錄中提供有關可執行檔進度的額外詳細資料,有助於分析及排解工作問題。舉例來說,您可以設定自訂狀態事件,說明可執行檔何時啟動、可執行檔何時結束、何時達到障礙可執行檔,或程式碼進度中發生重要事件。
事前準備
- 如果您從未使用過 Batch,請參閱「開始使用 Batch」,並完成專案和使用者的必要條件,啟用 Batch。
-
如要取得建立作業所需的權限,請要求管理員授予下列 IAM 角色:
-
批次工作編輯者 (
roles/batch.jobsEditor
) 專案 -
服務帳戶使用者 (
roles/iam.serviceAccountUser
) 在作業的服務帳戶上,預設為預設 Compute Engine 服務帳戶
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
-
批次工作編輯者 (
設定自訂狀態事件
建立工作時,請使用下列一或多個選項設定自訂狀態事件:
描述可執行的狀態:定義可執行的顯示名稱。使用 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
...