寫入工作記錄檔

本文說明如何編寫工作記錄，以及如何建立並執行含有工作記錄的 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_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 物件列印方法：

  • 使用 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: ...

後續步驟