Stackdriver を VFX レンダリングパイプラインのロギングサーバーとして使用する

このチュートリアルでは、ロギングサーバーの代わりに Google Stackdriver Logging を使用して、アプリケーション固有のログを記録する方法について説明します。デフォルトでは、Stackdriver Logging は、システムおよび多くの一般的なアプリケーションからのログを集計します。このチュートリアルでは、カスタムワークフローや、一般的なアプリケーションのリストにないアプリケーションからのログを取得して Stackdriver に取り込む方法も示します。

ビジュアルエフェクト（VFX）のレンダリングパイプラインやビルドシステムなど、多くのコンピューティングワークロードでは、存続時間の短いワーカーが一般的です。このチュートリアルでは、VFX ワークロードに焦点を当て、スタンドアロンの VFX レンダラ V-Ray を例として使用します。典型的な使用例の場合、VM インスタンスは、キューイングシステムによりオンデマンドで作成され、ジョブ（1 つ以上のフレームをレンダリングするなど）が割り当てられ、ジョブ完了後に終了します。ログは、レンダリングプロセスだけでなく、ファイル変換や、レンダリングされたフレームを共通ストレージにローカルにコピーする操作など、インスタンスが実行するレンダリング前またはレンダリング後のジョブからも取得する必要があります。

目標

インスタンスを作成し、そのインスタンスに Stackdriver エージェントをインストールします。
Stackdriver エージェントにログを送信するように、カスタムアプリケーションまたはワークフローを構成します。
Python クライアントライブラリを使用して、直接 Stackdriver にログを送信します。
Stackdriver でログを表示、フィルタリング、検索します。
Stackdriver から、長期アクセス可能なストレージにログをエクスポートします。

費用

このチュートリアルでは Google Stackdriver、Google BigQuery、Google Cloud Storage を使用しますが、無料利用の範囲内です。

始める前に

Cloud Platform Console プロジェクトを選択または作成します。
[プロジェクト] ページに移動
プロジェクトの課金を有効にします。
課金の有効化
Compute Engine API を有効にする。
Enable the API
gcloud beta コマンドコンポーネントをインストールします。
```
gcloud components install beta
```
デフォルトのプロジェクトを設定します。これにより、コマンドを実行するたびに --project フラグを指定する必要がなくなります。
```
gcloud config set project PROJECT_ID
```

Compute Engine のインスタンスを作成する

Stackdriver Logging エージェントは、Google Compute Engine 仮想マシン（VM）インスタンスおよび Amazon Elastic Compute Cloud（Amazon EC2）VM インスタンス上で動作します。エージェントとそれがサポートする VM インスタンスの詳細については、プロダクトドキュメントの「ロギングエージェント」を参照してください。

このチュートリアルでは、デフォルトの VM タイプを使用してインスタンスを作成できます。しかし、本番環境では、アプリケーションに必要なコンピューティングパワーを決定し、それに応じて VM を選択する必要があります。

GCP Console の [VM インスタンス] ページに移動します。
[VM インスタンス] ページに移動
[インスタンスを作成] をクリックします。
[新しいインスタンスの作成] ページで、インスタンス向けに希望するプロパティを入力します。詳細構成オプションで [管理、ディスク、ネットワーキング、SSH 認証鍵] セクションを展開します。
[作成] をクリックしてインスタンスを作成します。

新しいインスタンスを作成するには、少し時間がかかります。このチュートリアルの VM インスタンスの名前は sd-tutorial です。

Compute Engine インスタンスの設定

スーパーユーザー権限を付与されたアカウントを使用して VM インスタンスを作成した後、次の手順を実行します。

SSH を使用して sd-tutorial インスタンスに接続します。
```
gcloud compute ssh sd-tutorial
```
Stackdriver Logging エージェントをインストールします。手順について詳しくは、Stackdriver Logging エージェントをインストールする方法についてのページをご覧ください。
pip をダウンロードしてインストールします。
```
sudo yum install python-pip
```
Stackdriver Logging Python Library をダウンロードしてインストールします。
```
sudo pip install --upgrade google-cloud-logging
```

/etc/google-fluentd/config.d/vray.conf に、次の内容で V-Ray 用の Stackdriver Logging エージェント設定ファイルを作成します。

<source>
  @type tail
  read_from_head true
  format /^(\[(?<time>.*?)\])?((?<severity> ?(debug|info|warning|error|critical)): )?(?<message>.*)$/
  time_format %Y/%b/%d|%H:%M:%S
    # Log file names must be of the format SH.SEQ.SHOT.ROLE.log.
    # For example: myfilm.fba.0050.render.log
  path /home/*/vray/logs/*.log
  pos_file /var/lib/google-fluentd/pos/vray.pos
  tag vray.*
</source>
<filter vray.**>
  @type record_transformer
  <record>
    # Parse the log file name and add additional key:value records
    # to aid in filtering and searching logs in Stackdriver.
    # Assumes you are following the convention in this tutorial.
    show ${tag_parts[-5]}
    seq ${tag_parts[-4]}
    shot ${tag_parts[-3]}
    role ${tag_parts[-2]}
    tag ${tag_suffix[1]} # Strip off the "vray." prefix.
  </record>
</filter>

fluentd の構成の詳細については、構成ファイルの構文をご覧ください。

Stackdriver の設定をリロードします。
```
sudo service google-fluentd reload
```
本番環境の設定の場合、次に、構成されたこの VM からカスタム VM イメージを作成し、パイプラインがオンデマンドでその VM を開始できるようにすることができます。

VFX についての特別な考慮事項

レンダリングソフトウェアパッケージごとに、独自のログ出力が生成されます。このチュートリアルでは、V-Ray スタンドアロンレンダラを使用していますが、stdout/stderr に出力するそれ以外のレンダラまたはアプリケーションに合わせて調整することもできます。このチュートリアルでは、一般化された fluentd 構成を使用し、キューイングシステムがレンダラの出力を検索に適した特定の形式でファイル名にリダイレクトすることを想定しています。単一の VM で複数のジョブを実行する場合は、ファイル名が確実に一意となるようにする必要があります。

Stackdriver でのログファイルの名前

Stackdriver ログの命名規則を定義する際には、スタジオで使用されている命名規則のベストプラクティスに従います。Stackdriver ではリソース全体からの検索が可能であるため、一貫した命名規則を使用することにより、同じまたは類似のデータでタグ付けされた異なるリソースから生成されたログを検索できます。このチュートリアルにおいてキューマネージャーは、レンダリングワーカープロセスを開始する前に環境変数に次の値を設定します。これらの値は、ログにタグを付けるため、また、一意のファイル名を生成するために使用されます。

フィールド名	環境変数	値
表示（プロジェクト）名	`SHOW`	`myfilm`
シーケンス名	`SEQ`	`fba`
ショット番号	`SHOT`	`0050`
役割	`ROLE`	`render`

この例では、これらの値に基づいて、ビジュアルエフェクトワークフロー特有の命名規則を構成します。

<SHOW>.<SEQ>.<SHOT>.<ROLE>.log

たとえば、ショット fba0050 のレンダリングログには、次のようにタグが付けられます。

myfilm.fba.0050.render.log

このチュートリアルでは、キューマネージャーがこの規則に従ってログファイル名を設定すると想定していますが、スタジオのさまざまなニーズに合わせて変更するのは簡単です。

Stackdriver の設定を手動でテストする

レンダラもキューイングマネージャーも使用せずに構成を確認するには、サンプルログエントリをテストログにコピーします。ホームディレクトリから、次のコマンドを入力します。

mkdir -p vray/logs/

export SHOW='testshow' SEQ='testseq' SHOT='testshot' ROLE='testrole'

echo "debug: Test log line at `date` from ${HOSTNAME}" >> vray/logs/${SHOW}.${SEQ}.${SHOT}.${ROLE}.log

まもなくこの行がログビューアに表示されるはずです。

ログ配信を確認する

GCP Console の [ログビューア] ページに移動します。

[ログビューア] ページに移動

[ログ] メニューの下に、作成したログ名のタグが付けられたエントリが表示されます（この場合は testshow.testseq.testshot.testrole）。
このログを表示して、出力を確認します。

また、[project-id] と [log-name] を適切に置き換えることにより、gcloud ツールの beta コマンドを使用してログを読むこともできます。
```
# List all logs.
gcloud beta logging logs list

# Read the contents of a specific log.
gcloud beta logging read projects/[project-id]/logs/[log-name]
```

gcloud コマンドラインツールを使用したロギングの詳細については、ドキュメントをご覧ください。

レンダリングプロセスから Stackdriver へのログ出力

正しく設定され、検証されたなら、次のような V-Ray スタンドアロンコマンドラインを使用することにより、Stackdriver にログを送信できます。この例の場合、コマンドラインフラグにより、ファイルへのリダイレクト用に出力が最適化された V-Ray プロセスが開始されます。キューイングマネージャーは、SCENE_FILE を、該当するローカルファイルパスに置き換えるものと想定されています。また、ログファイルの名前セクションで説明されているように、ログの名前を生成するために使用される 4 つの環境変数（SHOW、SEQ、SHOT、および ROLE）も設定する必要があります。

vray \
   -display=0 \
   -showProgress=0 \
   -progressUseCR=0 \
   -progressUseColor=0 \
   -sceneFile SCENE_FILE > vray/logs/${SHOW}.${SEQ}.${SHOT}.${ROLE}.log 2>&1

Stackdriver API への直接ログ出力

ほとんどの VFX パイプラインでは、アセットの準備、公開、データ転送、レンダリング、トランスコードなど、プログラムによるタスクを実行するために、いずれかのスクリプト言語が使用されます。クライアントライブラリを使用して、これらのタスクの出力を Stackdriver に記録することができます。このチュートリアルでは、VFX 業界で広く使用されている Python を使用します。

オンプレミスからも、クラウドベースのワークステーションからも Stackdriver にログを送信することができます。Stackdriver とは Python API を介して通信するため、このような方法でログを書き込む場合、Stackdriver Logging エージェントはインストールしません。

Python ライブラリを使用して Stackdriver にログを書き込む

Python スクリプトを使用して Stackdriver にログを出力するには、まず次の手順を実行する必要があります。

ログメタデータを構築します。
重大度を指定します。
ログに記録するリソースのタイプを決定します。

スクリプトは次の処理を実行します。

適切な命名規則が使用されることを確認します。
ログデータをアセンブルします。
Google プロジェクトリソースレベルでログを書き込みます。

オンプレミスのワークステーションまたはサーバーからログを記録する場合は、Stackdriver へのログ出力の前に認証が必要です。クラウドインスタンスからログを記録する場合、認証はすでに完了しています。

logToStackdriver.py

GitHub で表示

#!/usr/bin/python
#
# Copyright 2017 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from google.cloud import logging
from google.cloud.logging.resource import Resource
import getpass
import os
import socket

def write(text, severity='INFO', show=None, seq=None, shot=None, role=None, **kwargs):
    '''Wrapper method for assembling the payload to send to logger.log_text.'''

    # Extract and build LOG_ID from environment.
    # For example: 'myfilm.slb.0050.render'
    if not show:
        show = os.getenv('SHOW')
    if not seq:
        seq = os.getenv('SEQ')
    if not shot:
        shot = os.getenv('SHOT')
    if not role:
        role = os.getenv('ROLE')

    if not show or not seq or not shot or not role:
        raise Exception('One or more log name tokens are empty. Unable to log.')
    # end if

    # Assemble logger name.
    logger_name = '.'.join([
        show,
        seq,
        shot,
        role
    ])

    print '# Logging to %s...' % logger_name

    # Build logger object.
    logging_client = logging.Client()
    logger = logging_client.logger(logger_name)

    # Assemble the required log metadata.
    label_payload = {
        "artist" : getpass.getuser(),
        "hostname" : socket.gethostname(),
        "show" : show,
        "seq" : seq,
        "shot" : shot,
        "role" : role
    }

    # Add optional kwargs to payload.
    label_payload.update(kwargs)

    # Write log.
    logger.log_text(
        text,
        resource=Resource(type='project', labels={'project_id':show}),
        severity=severity,
        labels=label_payload
    )

# end write

モジュールをパイプライン中の任意の Python スクリプトにインポートして、オンプレミスアーティストワークステーションかクラウドインスタンスのいずれかで実行します。

import logToStackdriver as lts
lts.write( 'This is the text to log.', show='myfilm', seq='slb', shot='0050', role='render' )

デフォルトでは、すべてのログは Google GCP Console の [Stackdriver Logging] > [ログ] > [Google プロジェクト] のプロジェクトリソースに書き込まれます。

[Stackdriver ログ] > [ログ] > [Google プロジェクト]

ログをエクスポートする

Stackdriver 保存期間を超えてログを保持するには、ログをエクスポートする必要があります。

安価で長期的なストレージを利用するには、ログを Google Cloud Storage のバケットにエクスポートします。ビッグデータ分析を実行するには、BigQuery データセットにエクスポートします。いずれの場合も、まずシンクと呼ばれるオブジェクトを作成します。シンクを使用すると、エクスポートするログエントリを選択するフィルタを作成したり、Cloud Storage または BigQuery を宛先として選択したりできます。シンクを作成すると、指定されたログが指定された宛先にすぐにエクスポートされます。ログビューアのログは、Stackdriver API を使用して、または gcloud logging コマンドラインツールを直接使用することにより、エクスポートできます。

BigQuery にエクスポートする

SQL セマンティクスを使用することにより、BigQuery に格納されたログを照会することができます。サードパーティ分析ツールの多くは、これらのログをネイティブにサポートしています。手順は次のとおりです。

BigQuery データセットを作成します。
フィルタを使用してシンクを作成し、ログをそのテーブルにエクスポートします。次のコマンドラインでは、[PROJECT_ID] により GCP プロジェクトが参照されていることに注意してください。
```
gcloud beta logging sinks create render-errors-bq  \
    bigquery.googleapis.com/projects/[PROJECT_ID]/datasets/[DATASET] \
    --log-filter "jsonPayload.SHOW=myfilm AND jsonPayload.SHOT=fba AND severity>=WARNING"
```
BigQuery データセットに追加するサービスアカウント名を示すメッセージが表示されます。データセット名の横にあるプルダウンをクリックし、[データセットの共有] をクリックすることにより、ウェブ UI を使用できます。

Stackdriver に送信されるもののうち、このフィルタに一致する次のログは、少し遅れてデータセットに送信されます。詳細については、シンクの仕組みのドキュメントを参照してください。

Cloud Storage にエクスポート

ログをファイルに保存するには、それらを Cloud Storage バケットにエクスポートします。Cloud Storage バケットについては、アクセス頻度の低いファイル用の低価格のストレージクラスを選択するか、または無料使用許可を利用できます。Cloud Storage は、HTTP により、または他の多くの GCP 製品との直接統合によって簡単にアクセスできます。

次の手順は、Cloud Storage にエクスポートする方法を示します。

Cloud Storage バケットを作成します。

Stackdriver で、フィルタを使用してシンクを作成し、それらのログを Cloud Storage にエクスポートします。

gcloud beta logging sinks create render-errors-gcs  \
    storage.googleapis.com/my-gcs-bucket \
    --log-filter "jsonPayload.SHOW=myfilm AND jsonPayload.SHOT=fba AND severity>=WARNING"

Stackdriver に送信されるもののうち、このフィルタに一致する次のログは、少し遅れてバケット中のファイルに送信されます。詳細については、シンクの仕組みのドキュメントを参照してください。

クリーンアップ

このチュートリアルで使用するリソースについて、Google Cloud Platform アカウントに課金されないようにする手順は次のとおりです。

プロジェクトの削除

課金を停止する最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除する手順は次のとおりです。

Cloud Platform Console で、[プロジェクト] ページに移動します。
[プロジェクト] ページに移動する
プロジェクト名の右側にある、ゴミ箱アイコンをクリックします。
警告: プロジェクトの削除は、次のような結果になります。
- 既存のプロジェクトを使った場合、プロジェクトで行っていた、他の作業も削除されます。
- 削除されたプロジェクトのプロジェクト ID は再使用できません。将来に使う予定のカスタムプロジェクト ID を作成していた場合は、プロジェクト内のリソースを削除するようにしてください。そうすれば、appspot.com URL のような、プロジェクト ID を使う URL をそのまま利用することができます。

Compute Engine インスタンスの削除

Compute Engine インスタンスを削除する手順は次のとおりです。

GCP Console の [VM インスタンス] ページに移動します。
[VM インスタンス] ページに移動
削除したいインスタンスの隣のチェックボックスを選択します。
ページの上部にある、[削除] ボタンをクリックし、インスタンスを削除します。

Cloud Storage バケットの削除

Cloud Storage バケットを削除する手順は次のとおりです。

Cloud Platform Console で、Cloud Storage ブラウザに移動します。
Cloud Storage ブラウザに移動する
削除したいバケットの隣にあるチェックボックスをクリックします。
ページの上部にある [削除] ボタンをクリックし、バケットを削除します。

次のステップ

Stackdriver Logging のドキュメントを確認します。
Fluentd についての詳細について確認します。
Fluentd 設定ファイルの詳細を確認します。
Stackdriver Logging Quota Policy の詳細を確認します。
Google Cloud Platform のその他の機能を試す。チュートリアルをご覧ください。