本文說明如何編寫工作記錄,以及如何建立並執行含有工作記錄的 Batch 工作。
為工作啟用記錄功能後,系統會從工作可執行檔在執行階段列印的訊息產生工作記錄。將可執行檔設定為寫入工作記錄,即可在 Cloud Logging 中顯示自訂資訊,有助於更輕鬆地分析及排解工作問題。如要進一步瞭解記錄,請參閱「使用記錄分析工作」。
事前準備
- 如果您從未使用過 Batch,請參閱「開始使用 Batch」,並完成專案和使用者的必要條件,啟用 Batch。
-
如要取得建立寫入記錄檔工作所需的權限,請要求管理員授予下列 IAM 角色:
-
如何建立工作:
-
批次工作編輯者 (
roles/batch.jobsEditor
) 專案 -
服務帳戶使用者 (
roles/iam.serviceAccountUser
) 在作業的服務帳戶上,預設為預設 Compute Engine 服務帳戶
-
批次工作編輯者 (
-
如要查看記錄,請按照下列步驟操作:
在專案中點選「記錄檢視器」 (
roles/logging.viewer
)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
-
如何建立工作:
建立及執行含有工作記錄的工作
如要建立及執行工作,並取得工作記錄,請在建立工作時執行下列操作:
- 啟用工作的記錄功能。這樣一來,系統就會產生為工作編寫的任何記錄。
針對您希望作業擁有的每個工作記錄,新增將工作記錄寫入可執行檔的指令。工作執行時,只要執行寫入工作記錄的指令,系統就會產生工作記錄。
如要瞭解如何編寫工作記錄,請參閱本文的「編寫工作記錄」一節。
寫入工作記錄
如果作業的可執行檔在執行階段將任何內容列印至標準輸出 (stdout
) 串流或標準錯誤 (stderr
) 串流,系統就會寫入工作記錄。舉例來說,您可以使用 echo
指令編寫工作記錄。產生的工作記錄結構會因列印內容的格式而異。具體來說,您可以透過下列任一方式撰寫每項工作記錄:
列印字串,撰寫非結構化記錄。 非結構化記錄很簡單,只能定義記錄的
textPayload
欄位。列印 JSON,寫入結構化記錄。 結構化記錄需要 JSON 格式,可讓您定義多個欄位,包括一些標準記錄欄位、自訂欄位和自訂狀態事件。
舉例來說,您可以使用結構化工作記錄定義記錄的嚴重程度,並在查看工作記錄時做為篩選條件。
透過列印字串寫入非結構化記錄
非結構化記錄可讓您定義訊息,也就是記錄 textPayload
欄位中顯示的字串。
如要寫入未經整理的記錄,請列印未經格式化的字串,如下節所示。
非結構化記錄範例
舉例來說,假設您想要包含下列字串的工作記錄:
MESSAGE
列印這個範例字串會產生類似下列內容的工作記錄:
insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...
更改下列內容:
MESSAGE
:訊息,也就是總結工作記錄用途的字串,例如The summary for a task log.
。PROJECT_ID
:專案的專案 ID。
列印字串
您可以使用各種方法列印字串,例如在可執行的項目中加入下列 echo
指令:
echo MESSAGE
如需使用 echo
指令寫入非結構化工作記錄的完整工作範例,請參閱「建立及執行基本工作」。
列印 JSON 物件,撰寫結構化記錄
結構化記錄可讓您定義下列任一項目:
- Cloud Logging 代理程式支援的標準欄位
- 自訂欄位
- 自訂狀態事件
如要寫入結構化記錄,請列印 JSON 物件。 以下各節說明如何定義含有部分標準欄位和自訂欄位的記錄。如要瞭解如何使用自訂狀態事件定義記錄,請參閱「設定自訂狀態事件」。
結構化記錄範例
舉例來說,假設您想要含有下列 JSON 物件資訊的任務記錄,該物件定義了訊息、嚴重程度和兩個自訂欄位。
{
"message": "MESSAGE"
"severity": "SEVERITY"
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
}
列印這個 JSON 物件會產生類似下列內容的工作記錄:
insertId: ...
jsonPayload:
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
message: MESSAGE
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: SEVERITY
timestamp: ...
更改下列內容:
MESSAGE
:訊息,也就是總結工作記錄用途的字串,例如The summary for a task log.
。SEVERITY
:記錄的嚴重程度,您可以在查看作業記錄時,將這項資訊做為篩選條件。 嚴重程度必須是LogSeverity
列舉之一,並轉換為字串,且只有第一個字母大寫。舉例來說,如果是ERROR
列舉,請指定Error
。CUSTOM_FIELD_1
和CUSTOM_FIELD_2
:工作記錄的自訂欄位名稱,例如custom_field_1
和custom_field_2
。CUSTOM_VALUE_1
和CUSTOM_VALUE_2
:工作記錄的自訂欄位值,可以是各種資料類型,可能需要加上引號,例如"the first custom field"
和2
。PROJECT_ID
:專案的專案 ID。
列印 JSON 物件
您可以使用各種方法列印這個 JSON 物件範例。舉例來說,下列範例顯示幾種可能的範例 JSON 物件列印方法:
- 使用
echo
指令列印對等字串。 使用 Python 列印對等的 dictionary。
echo 指令
如要使用 echo
指令和對等字串列印範例 JSON 物件,請在可執行的項目中加入下列指令:
echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'
舉例來說,假設您建立並執行的工作包含下列可執行檔:
"script": {
"text": "echo '{\"message\":\"The message for a structured log.\", \"severity\":\"Error\", \"custom_field_1\":\"the first custom field\", \"custom_field_2\":2}'"
}
然後,產生的工作記錄會類似下列內容:
insertId: ...
jsonPayload:
custom_field_1: the first custom field
custom_field_2: 2
message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...
Python
如要使用 Python 和對應的字典列印範例 JSON 物件,請在可執行的程式碼中加入下列範例:
#!/usr/bin/env python3
import json
entry = dict(
severity="SEVERITY",
message="MESSAGE",
CUSTOM_FIELD_1=CUSTOM_VALUE_1,
CUSTOM_FIELD_2=CUSTOM_VALUE_2,
)
print(json.dumps(entry))
舉例來說,假設您建立並執行的工作包含下列可執行檔:
"script": {
"text": "#!/usr/bin/env python3\n\nimport json\n\nentry = dict(\nseverity=\"Error\",\nmessage=\"The summary for a structured task log with error severity.\",\ncustom_field_1=\"the first custom field\",\ncustom_field_2=2,\n)\nprint(json.dumps(entry))"
}
然後,產生的工作記錄會類似下列內容:
insertId: ...
jsonPayload:
custom_field_1: the first custom field
custom_field_2: 2
message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...
後續步驟
- 如要進一步瞭解如何設定記錄格式,請參閱 Cloud Logging 說明文件中的「結構化記錄」。
- 瞭解如何撰寫包含自訂狀態事件的結構化工作記錄。
- 瞭解如何查看工作的任務記錄。
- 進一步瞭解工作建立選項。