タスクログを書き込む

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

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

構造化ログの例

たとえば、次の 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 列挙型の場合は 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: ...

次のステップ