タスクログを書き込む

このドキュメントでは、タスクログを書き込む方法と、タスクログのあるバッチジョブを作成して実行する方法について説明します。

ジョブのロギングが有効になっている場合、実行時にジョブの runnable が出力したメッセージからタスクログが生成されます。タスクログを書き込むように runnable を構成すると、Cloud Logging にカスタム情報を表示できます。これにより、ジョブの分析とトラブルシューティングが容易になります。ログの詳細については、ログを使用してジョブを分析するをご覧ください。

準備

タスクログのあるジョブを作成して実行する

タスクログが必要なジョブを作成して実行するには、ジョブの作成時に次の操作を行います。

  1. ジョブのログを有効にします。これにより、ジョブに書き込まれたすべてのログが生成されます。

  2. ジョブに含めるタスクログごとに、タスクログを runnable に書き込むコマンドを追加します。ジョブを実行すると、タスクログを書き込むコマンドが実行されるたびにタスクログが生成されます。

    タスクログを書き込む方法については、このドキュメントのタスクログを書き込むをご覧ください。

タスクログを書き込む

タスクログは、実行時に標準出力（stdout）ストリームまたは標準エラー（stderr）ストリームにジョブの runnable が出力するコンテンツのすべてについて書き込まれます。たとえば、タスクログを作成するには、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。

runnable に次の echo コマンドを含めるなど、さまざまな方法を使用して文字列を出力できます。

echo MESSAGE

echo コマンドを使用して非構造化タスクログを書き込むジョブの包括的な例については、基本ジョブの作成と実行をご覧ください。

JSON オブジェクトを出力します。

構造化ログでは、次のいずれかを定義できます。

構造化ログを書き込むには、JSON オブジェクトを出力します。 以降のセクションでは、標準フィールドとカスタム フィールドのいくつかを使用してログを定義する方法について説明します。カスタム ステータス イベントでログを定義する方法については、カスタム ステータス イベントを構成するをご覧ください。

構造化ログの例

たとえば、タスクログに次の JSON オブジェクトの情報が含まれているとします。このオブジェクトは、メッセージ、重大度、2 つのカスタム フィールドを定義します。

{
  "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 enum の場合は 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 を使用して同等の辞書を出力します。

echo コマンド

echo コマンドと同等の文字列を使用してサンプルの JSON オブジェクトを出力するには、runnable に次のコマンドを含めます。

echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'

たとえば、次の runnable を使用してジョブを作成して実行するとします。

"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 オブジェクトのサンプルを出力するには、次のサンプルを runnable に含めます。

#!/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))

たとえば、次の runnable を使用してジョブを作成して実行するとします。

"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: ...

次のステップ