Cloud Logging に移行する

第 2 世代のランタイムのロギングは、第 1 世代のランタイムとは異なります。新しいランタイムにアップグレードする際の最大の変更点の一つは、App Engine と事前に統合されたロギングが第 2 世代のランタイムではサポートされておらず、ログが自動的に関連付けられないことです。第 2 世代のランタイムに移行する場合は、Cloud Logging クライアント ライブラリを使用する必要があります。

このガイドでは、Cloud Logging を使用するようにアプリを更新し、App Engine のロギング統合とほぼ同じフィルタリング機能とログ相関機能を実現する方法について説明します。

Cloud Logging は、ストレージ、検索、分析、モニタリングをサポートするリアルタイムのログ管理システムです。Cloud Logging は、Google Cloud リソースから自動的にログを収集します。アプリケーション、オンプレミスのリソース、他のクラウド プロバイダのリソースからログを収集することもできます。

主な違い

次の表に、第 1 世代のランタイムと第 2 世代のランタイムのロギングの違いを示します。

第 1 世代のランタイム 第 2 世代のランタイム
リクエストログとアプリログ(アプリケーション ログとも呼ばれます) App Engine では、リクエストログ内にすべてのアプリログが埋め込まれています。第 1 世代のランタイムのロギングでは、リクエストログの protoPayload.line.logMessage フィールドを使用してアプリログが埋め込まれます。 App Engine では、関連するリクエストログ内にアプリログが埋め込まれることはありません。App Engine では、リクエストログで protoPayload.line 属性が省略されています。アプリのログは、ロギング方法に基づいて転送されます。
  • stdoutstderr: print() などのログを logs/stdout または logs/stderr に転送します。
  • Cloud Logging クライアントの設定後の Python ロギング モジュール: Python ルート ロギング モジュール(logging.info()logging.error() など)によって書き込まれたすべてのログを logs/python に転送します。
    Python 用の Cloud Logging クライアント ライブラリが関連付けを設定していない場合、デフォルトでは、Python ルート ロギング モジュールは logs/stderr に転送します。
ログ エクスプローラでのログの表示 第 1 世代のランタイムのログタイプは appengine.googleapis.com/request_log の 1 つだけです。リクエストログを開くと、その下にアプリログが表示されます。 第 2 世代のランタイムのログには、appengine.googleapis.com/request_logstdoutstderrlogs/python のリクエストログなど、複数のログタイプが含まれます。ログタイプは、アプリがログを出力する方法によって異なります。Google の内部ログは /var/log/google_init.log でも確認できます。

アプリログとリクエストログは自動的には関連付けられないため、ログ エクスプローラにリクエストログとアプリログを表示するには、追加の手順が必要です。詳細については、リクエストログをアプリログに関連付けるログ エクスプローラで相関ログを表示するをご覧ください。
Cloud Trace の統合 レイテンシ データの収集のために Cloud Trace と自動的に統合されます。 App Engine からレイテンシのデータを収集するには、アプリと Cloud Trace を手動で統合する必要があります。詳細については、Cloud Trace 用の計装をご覧ください。
エラーレベルの関連付け スローされたエラーを ERROR 重大度レベルとして App Engine リクエストログに記録します。Error Reporting は、これらの詳細情報を Error Reporting ダッシュボードで自動的に関連付けます。 デフォルトでは、App Engine は第 2 世代のランタイムに Error Reporting を統合しません。ロギングと Error Reporting の統合を設定するには、クライアント ライブラリを使用してアプリを計測するをご覧ください。
重大度 ログ エクスプローラによってリクエストログに重大度が割り当てられます。この重大度は、リクエストログのエントリに関連付けられているアプリログのエントリの最高重大度を表します。たとえば、リクエストによってアプリが警告ログエントリを出力する場合、ログ エクスプローラのリクエスト ログエントリの横に警告アイコンが表示されます。リクエスト エントリを展開すると、リクエスト エントリ内にネストされた警告ログエントリが表示されます。 デフォルトでは、すべてのリクエストログの重大度は DEFAULT または INFO になります。リクエストログがアプリログと関連付けられており、相関ログを表示するようにログ エクスプローラが構成されていても、関連するアプリログの重大度はリクエストログに反映されません。
Logservice API Logservice API はバンドル サービス SDK の一部です。 バンドル サービス SDK から Logservice API が削除されました。詳細については、利用可能な API のリストをご覧ください。

移行を始める前に

  1. アプリが含まれるプロジェクトで Cloud Logging API を有効にします。

    API の有効化

  2. アプリにログを書き込む権限があることを確認します。

    デフォルトでは、アプリのデフォルトのサービス アカウントにログの書き込み権限があります。

    アプリで別のサービス アカウントを使用する場合、またはデフォルトのサービス アカウントの権限を変更した場合は、使用するアカウントにログを書き込むための logging.logEntries.create 権限が付与されていることを確認します。

  3. App Engine のさまざまな種類のログをよく理解してください。

移行プロセスの概要

Cloud Logging を使用するようにアプリを移行するには:

  1. Cloud Logging 用の Cloud クライアント ライブラリをインストールする
  2. Cloud Logging でログを書き込む
  3. リクエストログとアプリログを関連付ける
  4. ログを表示する
  5. アプリをテストする

Cloud Logging 用 Cloud クライアント ライブラリのインストール

構成ファイルをインストールして更新するには、次のように Cloud Logging 用の Cloud クライアント ライブラリを requirements.txt ファイルの依存関係のリストに追加します。

google-cloud-logging

標準の Python ロギング モジュールを使用してログを書き込む

ログエントリを書き込む各ファイルで次の処理を行います。

  1. Cloud Logging クライアント ライブラリをインポートする。
  2. Cloud Logging クライアントをインスタンス化する。
  3. デフォルト リスナーを Python ルートロガーのロギング ハンドラとして接続する、Cloud Logging クライアントの setup_logging() メソッドを実行します。

例:

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

ハンドラが接続されると、デフォルトでは、アプリケーションで出力された INFO レベル以上のログが Logging に送信されます。

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

リクエストログとアプリログを関連付ける

リクエストログとアプリログの自動的な関連付けなど、第 1 世代のランタイムで使用可能な機能の一部は第 2 世代のランタイムでは使用できません。

第 2 世代のランタイムを使用するアプリでは、次のいずれかの方法で、第 1 世代のランタイムと同様にネストされたロギングを実現できます。

  • アプリケーションで Cloud Logging クライアントを設定し、ログを関連付ける。
  • stdoutstderrtrace 識別子を使用する。

第 1 世代のランタイムと第 2 世代のランタイムのロギング動作は、次のように異なります。

  • 第 1 世代のランタイムでは、App Engine は、リクエストの処理中に出力されたすべてのアプリログをリクエストログの protoPayload.line.logMessage フィールドに埋め込みます。これらのログは、appengine.googleapis.com/request_log を介してログ エクスプローラに表示されます。

    次の図は、第 1 世代のランタイムのログを示しています。リクエストログとアプリログが関連付けられています。

    第 1 世代のランタイムのロギング

  • 第 2 世代のランタイムでは、App Engine はリクエストログの protoPayload.line 属性を省略します。アプリログの内容は、ログ エクスプローラの JSON リクエストログにはありません。アプリログは、ログ エクスプローラにログ名ごとに表示されます。

    次の図は、第 2 世代のランタイムのログを示しています。リクエストログとアプリログは個別に表示されています。

    第 2 世代のランタイムのロギング

以降のセクションでは、Cloud Logging クライアントを使用するか、stdoutstderr で構造化ロギングを使用して、ログを関連付ける方法について説明します。

Python ロギング モジュールを使用する

Python ロギング モジュールによって記録されたアプリログにリクエストを関連付けるには、Cloud Logging クライアント ライブラリを設定します。

アプリケーションの起動時に client.setup_logging() メソッドを実行すると、logging.info()logging.error() などの Python logging モジュールによって書き込まれたアプリログに trace フィールドと HTTP リクエストの詳細が追加されます。これらのログは logs/python に転送されます。

また、App Engine はこの trace フィールドを関連するリクエストログに追加します。これにより、関連するログエントリをログ エクスプローラで表示できます。

stdoutstderr を使用する

stdoutstderr を使用してログエントリを書き込むと、これらのエントリがログ エクスプローラに表示されます。ただし、フィルタリングとリクエストログとの相関を有効にするには、エントリを JSON オブジェクトとしてフォーマットし、特定のメタデータを指定する必要があります。このアプローチの詳細については、構造化ログを stdout と stderr に書き込むをご覧ください。本アプローチでは次の操作を行うことで、リクエストのトレース ID をアプリケーション ログに追加します。

  1. X-Cloud-Trace-Context リクエスト ヘッダーからトレース ID を抽出します。
  2. 構造化ログエントリの logging.googleapis.com/trace という名前のフィールドに ID を書き込みます。X-Cloud-Trace-Context ヘッダーの詳細については、リクエストを強制的にトレースするをご覧ください。

ログを表示する

アプリログとリクエストログを表示する方法はいくつかあります。

ログ エクスプローラを使用する

ログ エクスプローラを使用して、アプリログとリクエストログを表示できます。

  1. Google Cloud コンソールの [ログ エクスプローラ] に移動します。

    [ログ エクスプローラ] に移動

  2. ページの上部にある既存の Google Cloud プロジェクトを選択します。

  3. [リソースの種類] で [GAE アプリケーション] を選択します。

ログ エクスプローラでは、App Engine サービスとバージョン、その他の条件でフィルタリングできます。ログで特定のエントリを検索することもできます。詳細については、ログ エクスプローラの使用をご覧ください。

単純なテキスト エントリを標準出力に送信する場合は、ログビューアを使用して重要度でアプリエントリをフィルタリングすることはできません。また、特定のリクエストに対応するアプリログを表示することもできません。ログ エクスプローラでは、テキストやタイムスタンプなど、他のタイプのフィルタを使用することもできます。

ログ エクスプローラで相関ログエントリを表示する

ログ エクスプローラで、親ログエントリに関連付けられた子ログエントリを表示するには、ログエントリを開きます。

たとえば、App Engine リクエストのログエントリとアプリケーション ログエントリを表示するには、次のようにします。

  1. Google Cloud コンソールのナビゲーション パネルで、[ロギング] を選択してから、[ログ エクスプローラ] を選択します。

    [ログ エクスプローラ] に移動

  2. [リソースの種類] で [GAE アプリケーション] を選択します。

  3. リクエストログを表示して関連付けるには、[ログ名] で [request_log] を選択します。また、リクエストログで関連付けるには、[関連付け] をクリックして [request_log] を選択します。

    ログの関連付け

  4. [クエリ結果] ペインで、ログエントリを開くには、[開く] をクリックします。エントリを開くと、各リクエストログに関連付けられたアプリログが表示されます。

ログのフィルタを作成すると、各リクエストログに対応するアプリログが子ログとして表示されます。ログ エクスプローラは、アプリケーションが google-cloud-logging ライブラリを使用していると仮定して、アプリログの trace フィールドと特定のリクエストログを関連付けます。

次の図は、trace フィールドでグループ化されたアプリログを示しています。

アプリログのエントリがリクエストログのエントリにネストされている。

Google Cloud CLI を使用する

App Engine のログをコマンドラインから表示するには、次のコマンドを使用します。

gcloud app logs tail

詳細については、gcloud app logs tail をご覧ください。

プログラムでログを読み取る

プログラムでログを読み取るには、次のいずれかの方法を使用します。

アプリをテストする

エラーなしでアプリをデプロイできれば、移行は成功です。Cloud Logging が機能していることを確認するには、次の操作を行います。

  1. ログ エクスプローラに移動し、リクエストログのエントリを開きます。

    [ログ エクスプローラ] に移動

  2. リクエストの処理時にアプリによって生成されたアプリログがリクエストログ内にネストされていることを確認します。

  3. すべてのアプリ エンドポイントが想定どおりに機能している場合は、トラフィック分割を使用して、更新したアプリのトラフィックを徐々に増やします。更新したアプリに転送されるトラフィックを増やす前に、アプリに問題がないか注意深くモニタリングしてください。