寫入工作記錄檔

本文說明如何編寫工作記錄,以及如何建立並執行含有工作記錄的 Batch 工作。

為工作啟用記錄功能後,系統會從工作可執行檔在執行階段列印的訊息產生工作記錄。將可執行檔設定為寫入工作記錄,即可在 Cloud Logging 中顯示自訂資訊,有助於更輕鬆地分析及排解工作問題。如要進一步瞭解記錄,請參閱「使用記錄分析工作」。

事前準備

  1. 如果您從未使用過 Batch,請參閱「開始使用 Batch」,並完成專案和使用者的必要條件,啟用 Batch。
  2. 如要取得建立寫入記錄檔工作所需的權限,請要求管理員授予下列 IAM 角色:

    如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。

    您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

建立及執行含有工作記錄的工作

如要建立及執行工作,並取得工作記錄,請在建立工作時執行下列操作:

  1. 啟用工作的記錄功能。這樣一來,系統就會產生為工作編寫的任何記錄。
  2. 針對您希望作業擁有的每個工作記錄,新增將工作記錄寫入可執行檔的指令。工作執行時,只要執行寫入工作記錄的指令,系統就會產生工作記錄。

    如要瞭解如何編寫工作記錄,請參閱本文的「編寫工作記錄」一節。

寫入工作記錄

如果作業的可執行檔在執行階段將任何內容列印至標準輸出 (stdout) 串流或標準錯誤 (stderr) 串流,系統就會寫入工作記錄。舉例來說,您可以使用 echo 指令編寫工作記錄。產生的工作記錄結構會因列印內容的格式而異。具體來說,您可以透過下列任一方式撰寫每項工作記錄:

透過列印字串寫入非結構化記錄

非結構化記錄可讓您定義訊息,也就是記錄 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 物件,撰寫結構化記錄

結構化記錄可讓您定義下列任一項目:

如要寫入結構化記錄,請列印 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_1CUSTOM_FIELD_2:工作記錄的自訂欄位名稱,例如 custom_field_1custom_field_2
  • CUSTOM_VALUE_1CUSTOM_VALUE_2:工作記錄的自訂欄位值,可以是各種資料類型,可能需要加上引號,例如 "the first custom field"2
  • PROJECT_ID:專案的專案 ID

您可以使用各種方法列印這個 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: ...

後續步驟