📘

Batch カスタムステータスイベントと非構造化・構造化のタスクログ機能

2024/03/28に公開

GCP

Google Cloud

batch

tech

はじめに

こんにちは。クラウドエースデータソリューション部所属の髙根です。

クラウドエースのデータソリューション部では、IT エンジニアリングを担うシステム開発部の中で、特にデータ基盤構築・分析基盤構築からデータ分析までを含む一貫したデータ課題の解決を専門としています。

データソリューション部の活動の一環として、Google Cloud が提供しているデータ領域のプロダクトについて、新規リリースをキャッチアップするための調査報告会を毎週実施しています。
新規リリースの中で、特に重要と考えるリリースを本ページ含め記事として公開しています。

本記事でご紹介する内容は、2024年 2 月 1 日に機能追加された、Batch における カスタムステータスイベント と 構造化・非構造化のタスクログ機能 についてです。

Batch の概要

Batch は、Google Cloud Platform 上で、大規模なバッチ処理ジョブを簡単に実行できる、フルマネージド型のプロダクトです。
コンピューティングタスクを自動的にスケーリング、管理することで、開発者やデータサイエンティストが、インフラストラクチャの管理にかかる手間を最小限に抑え、大量のデータ処理を効率的に実行できます。

カスタムステータスイベントとは

カスタムステータスイベントとは、runnable の履歴に、詳細な進行状況を提供する、といった機能です。例えば、以下のようなカスタムステータスイベントの構成が可能となります。

runnable の開始
runnable の終了
barrier runnable への到達
コードの進行中に重要なイベントの発生

runnable

runnable は、バッチジョブ内で 実行されるタスク、または ジョブ の一部を指します。Batch でジョブを定義する際に、そのジョブを構成する実行単位を runnable として指定します。

barrier runnable

一連のタスクやスレッドが、特定のポイントに到達するまで進行を待機し、最後のタスクが特定のポイントに到達した後 にのみ、それら全てが再び実行できる仕組みです。

カスタムステータスイベントを構成し、使用することで、進捗状況が明確となり、ジョブの分析やトラブルシューティングが容易となります。

カスタムステータスイベントを構成してみた

実際に、ジョブを作成時に、runnable の表示名 ( displayNamefield ) を定義し、カスタムステータスイベントを構成します。

はじめる準備

Batch の使用を開始するには、下記の準備が必要となります。

使用するプロジェクトの Batch API の有効化
必要な権限を付与

ジョブの作成の権限
roles/batch.jobsEditor , roles/iam.serviceAccountUser
ジョブの閲覧の権限
roles/batch.jobsViewer

ジョブの作成

ジョブの作成は、下記の手順で行います。

JSON 構成ファイルに、runnable の表示名を定義
JSON 構成ファイルに、オプションを定義
ジョブの作成コマンドを実行

カスタムステータスイベントを構成するには、ジョブ作成時にオプションを 1つ以上使用して、カスタムステータスイベントを構成します。
構成には、gcloud CLI、または Batch API を使用する必要があり、本検証では、gcloud CLI を使用します。
下記のように、JSON 構成ファイルに runnable の表示名 ( displayName フィールド) を定義します。

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "displayName":"DISPLAY_NAME1",
            "script": {
              "text": "echo Hello world from script 1 for task ${BATCH_TASK_INDEX}"
            }
          },
          {
            "displayName":"DISPLAY_NAME2",
            "barrier": {}
          },
          {
            "displayName":"DISPLAY_NAME3",
            "script": {
              "text": "echo Hello world from script 2 for task ${BATCH_TASK_INDEX}"
            }
          }
        ]
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

下記が、JSON 構成ファイルにて定義するオプションとなります。

DISPLAY_NAME1 ：タスク1 の表示名を定義
DISPLAY_NAME2 ：タスク2 の表示名を定義
DISPLAY_NAME3 ：タスク3 の表示名を定義

上記を定義後、下記のコマンドを実行し、ジョブを作成します。

gcloud batch jobs submit JOB_NAME \
  --location LOCATION \
  --config JSON_CONFIGURATION_FILE

上記コマンドは下記のように置き換えて実行します。

JOB_NAME ：ジョブの名前
LOCATION ：ジョブの場所
JSON_CONFIGURATION_FILE ：ジョブの構成詳細が含まれる JSON ファイルのパス

上記コマンド実行後、Google Cloud コンソールにて、ジョブが正常に作成されているか確認します。下記のように、ステータス列が 完了しました と表示され、ジョブが正常に作成されたことが確認できます。
Job_Creation_1

カスタムステータスイベントを表示

カスタムステータスイベントは、下記 3つの方法で表示することが可能です。本検証では、Google Cloud コンソールにて、カスタムステータスイベントを表示します。

Google Cloud コンソール
gcloud CLI
Batch API

下記の手順でカスタムステータスイベントを表示します。

Google Cloud コンソールで、[ジョブリスト] ページへ移動
[ジョブ名] 列で、ジョブの名前をクリックし、ジョブの詳細ページを開く
[イベント] タブをクリック

上記手順後、下記のようにカスタムステータスイベントが表示されます。
View_Status_Events
上記は、ジョブの状態を表しており、[日付] 列の記載通りに実行されます。下記が [日付] 列の実行の詳細についてです。

2024-03-26T01:50:01.569754163Z ： QUEUED から SCHEDULED に変更されたというメッセージ
- QUEUED では、ジョブがシステムによって受け入れられ、実行待ちのキューに追加された状態です。この段階では、ジョブはリソースが利用可能になるのを待っています。
- SCHEDULED では、ジョブがスケジュールされ、実行のために必要なリソース（CPU、メモリ、ストレージなど）の割り当てが行われている状態です。
2024-03-26T01:51:22.530548432Z ： SCHEDULED から RUNNING に変更されたというメッセージ
- SCHEDULED では、上記と同様、ジョブはリソースが利用可能になるのを待っています。
- RUNNING では、ジョブが実際に実行中である状態です。この時点で、ジョブに関連付けられたタスクが処理され、指定された作業が行われています。
2024-03-26T01:52:19.867753356Z ： RUNNING から SUCCEEDED に変更されたというメッセージ
- RUNNING では、上記と同様、ジョブが実際に実行中である状態です。
- SUCCEEDED では、ジョブの目的が達成され、必要な処理が完了したことを意味します。

上記のように、各実行可能ファイルの状態 について表示することができました。

非構造化・構造化のタスクログとは

非構造化・構造化のタスクログとは、ジョブ内で行われる各タスクに関するログ情報を、非構造化タスクログ と 構造化タスクログ といった形で提供する、といった機能です。非構造化タスクログ・構造化のタスクログは、下記のように提供の形が異なります。

非構造化タスクログ
非構造化タスクログは、タスク実行時に生成される標準出力と、標準エラー出力の内容を含みます。これらは、タスクが出力するテキストメッセージやエラーメッセージをそのまま記録します。
構造化タスクログ
構造化タスクログは、JSON形式といった、特定の形式で整理されたログデータです。JSON形式で、標準ログフィールド、カスタムフィールド、カスタムステータスイベントを含む複数のフィールドを定義することが可能です。

非構造化・構造化のタスクログを生成してみた

実際に、ジョブのログ記録を有効にし、ジョブの実行可能ファイルが実行時に出力するメッセージから、タスクログを生成します。

はじめる準備

Batch の使用を開始するには、下記の準備が必要となります。

使用するプロジェクトの Batch API の有効化
ジョブのログの有効化
必要な権限を付与

ジョブの作成の権限
roles/batch.jobsEditor , roles/iam.serviceAccountUser
ログの表示する
roles/logging.viewer

非構造化ログの生成

非構造化ログでは、生成されるログの textPayload フィールドに表示されるメッセージを定義することができます。
ジョブのログを生成するには、下記のどちらかの方法でジョブの作成時にログを有効にします。

Google Cloud コンソールを使用してジョブを作成する際は、ログの生成はデフォルトで有効となるため、有効化の操作は不要となります。
gcloud CLI または Batch API を使用してジョブを作成する際は、ログの生成はデフォルトで無効になります。そのためログを有効にする際は、ジョブの作成時に下記の構成を含めます。

{
    ...
    "logsPolicy": {
        "destination": "CLOUD_LOGGING"
    }
    ...
}

非構造化ログの確認

ジョブのログは、下記の方法で確認することができます。

Google Cloud コンソール
gcloud CLI
Logging API
Batch API（Go、java、Python、C++）

本検証では、Google Cloud コンソールを使用して確認します。下記の手順でログを表示します。

Google Cloud コンソールで、[ジョブリスト] ページに移動
[ジョブ名] 列で、ジョブの名前をクリックし、ジョブの詳細ページを開く
[ログ] タブをクリック
ジョブに関連付けられたすべてのログが表示される　
※ ログをフィルタリングする（オプション）

非構造化ログでは、textPayload にログメッセージが記載されています。下記が実際のログとなります。
Unstructured_Log_textPayload

構造化ログの生成

構造化ログを生成するには、JSON オブジェクトを出力します。構造化ログでは、下記のいずれかの 3つを定義することができます。本検証では、カスタムステータスイベントを定義します。

Cloud Logging エージェントでサポートされている標準フィールド
カスタムフィールド
カスタムステータスイベント

JSON オブジェクトを出力する方法として、下記 2つの方法があり、本検証では、echo コマンドを使用して JSON オブジェクトを出力します。

echo コマンドを使用して、同等の文字列を出力する
Python を使用して、同等の辞書を出力する

下記のように、echo コマンドと同等の文字列を、ジョブの作成時に使用する実行可能ファイルに含めます。

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "displayName":"DISPLAY_NAME",
            "script": {
              "text": "echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":\"CUSTOM_VALUE_1\", \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'"
            }
          }
        ]
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

下記が、echo コマンドにて定義する文字列となります。
MESSAGE、SEVERITY、CUSTOM_VALUE_1、CUSTOM_VALUE_2 は、実際の使用状況に応じて適切な値に置き換える必要があります。

\"message\":\"MESSAGE\" ：タスクログの目的を要約した文字列を示す
\"severity\":\"SEVERITY\" ：ログの重大度
\"CUSTOM_FIELD_1\":CUSTOM_VALUE_1 ：タスクログのカスタムフィールドの名前とタスクログのカスタムフィールドの値
\"CUSTOM_FIELD_2\":CUSTOM_VALUE_2 ：タスクログのカスタムフィールドの名前とタスクログのカスタムフィールドの値

上記を定義後、下記のコマンドを実行し、構造化ログの生成について定義したジョブを作成します。

gcloud batch jobs submit JOB_NAME \
  --location LOCATION \
  --config JSON_CONFIGURATION_FILE

上記コマンドは下記のように置き換えて実行します。

JOB_NAME ：ジョブの名前
LOCATION: ：ジョブの場所
JSON_CONFIGURATION_FILE ：ジョブの構成詳細が含まれる JSON ファイルのパス

上記コマンド実行後、Google Cloud コンソールにて、ジョブが正常に作成されているか確認します。下記のように、ステータス列が 完了しました と表示され、ジョブが正常に作成されたことが確認できます。
Job_Creation_2

構造化ログの確認

非構造化ログと同様、ジョブのログは、下記の方法で確認することができます。

Google Cloud コンソール
gcloud CLI
Logging API
Batch API（Go、java、Python、C++）

本検証では、構造化ログと同様、Google Cloud コンソールを使用してログを表示します。
（手順については「非構造化ログの確認」にて記載。）

構造化ログでは、jsonPayload にログメッセージが記載されています。下記が実際に、記載されたログとなります。
Unstructured_Log_jsonPayload

まとめ

今回は、Batch における、カスタムステータスイベントと非構造化・構造化のタスクログ機能についてご紹介しました。検証を通し、カスタムステータスイベントの使用や、ログの詳細を生成にすることで、下記の 3点を実現することができます。

進捗状況が明確になる
ジョブの分析に役立つ情報を取得することができる
トラブルシューティングが容易にすることができる

このようなケースを検討してる際は、ぜひお試しください。

はじめに

Batch の概要

カスタム ステータス イベント とは

カスタム ステータス イベント を構成してみた

はじめる準備

ジョブの作成

カスタム ステータス イベント を表示

非構造化・構造化のタスクログ とは

非構造化・構造化のタスクログ を生成してみた

はじめる準備

非構造化ログの生成

非構造化ログの確認

構造化ログの生成

構造化ログの確認

まとめ

Discussion

カスタムステータスイベントとは

カスタムステータスイベントを構成してみた

カスタムステータスイベントを表示

非構造化・構造化のタスクログとは

非構造化・構造化のタスクログを生成してみた