タスクログを書き込む

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

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

準備

  1. Batch を以前に使用したことがない場合は、Batch を使ってみるを確認し、プロジェクトとユーザーの前提条件を完了して Batch を有効にします。

  2. ログを書き込むジョブの作成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

    ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

    必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

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

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

  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 オブジェクトを出力します。以降のセクションでは、標準フィールドとカスタム フィールドを使用してログを定義する方法について説明します。カスタム ステータス イベントを使用してログを定義する方法については、カスタム ステータス イベントを構成するもご覧ください。

構造化ログの例

たとえば、メッセージ、重大度、2 つのカスタム フィールドを定義する次の 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 を使用して同等の辞書を出力します。

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

次のステップ