ログの書き込みと表示

このページでは、App Engine アプリで使用可能なログと、ログエントリの作成、関連付け、表示を行う方法について説明します。

App Engine では次の 2 種類のログを収集します。

リクエストログ: アプリに送信されたリクエストのログ。デフォルトでは、App Engine は、アプリが受信した HTTP リクエストごとにログエントリを自動的に出力します。
アプリログ: サポートされているフレームワークまたはファイルに書き込んだログエントリに基づいて App Engine アプリが出力するログエントリ。

App Engine は、リクエストログとアプリログの両方を Cloud Logging エージェントに自動的に送信します。

アプリログを書き込む

App Engine はアプリに送信されたリクエストのログを自動的に出力します。ユーザーがリクエストログを作成する必要はありません。このセクションでは、アプリログを書き込む方法について説明します。

App Engine アプリからアプリログを書き込むときに、次の方法でログが書き込まれていれば、Cloud Logging が自動的にログを取得します。

Cloud Logging との統合（推奨）
stdout と stderr を使用して構造化ログを書き込む

Cloud Logging との統合

App Engine アプリを Cloud Logging と統合することをおすすめします。この方法では Cloud Logging が提供するすべての機能を使用できます。Google 固有のコードを数行追加するだけで済みます。

Go 用 Cloud Logging ライブラリを使用すると、Cloud Logging を使用する際により高レベルのレイヤが提供されます。詳細については、Go 用に Cloud Logging を設定するをご覧ください。

構造化ログを `stdout` と `stderr` に書き込む

Cloud Logging クライアントライブラリを直接使用できない場合は、テキスト文字列を stdout と stderr に送信できます。デフォルトでは、ログのペイロードはログエントリの textPayload フィールドに保存された単純なテキスト文字列です。文字列は、ログエクスプローラ、コマンドライン、Cloud Logging API にメッセージとして表示され、メッセージを発行した App Engine のサービスとバージョンに関連付けられます。

ログからより多くの情報を取得するには、ログエクスプローラで重大度レベルを使用して、これらの文字列をフィルタします。文字列をフィルタするには、文字列を構造化データとしてフォーマットする必要があります。これを行うには、シリアル化された JSON を 1 行形式でログに書き込みます。App Engine は、このシリアル化された JSON 行を取得して解析し、ログエントリの textPayload ではなく jsonPayload フィールドに配置します。

次のスニペットは、このような構造化ログの書き込みを示しています。

各ログエントリの構造は、Entry タイプによって指定されます。


// Entry defines a log entry.
type Entry struct {
	Message  string `json:"message"`
	Severity string `json:"severity,omitempty"`
	Trace    string `json:"logging.googleapis.com/trace,omitempty"`

	// Logs Explorer allows filtering and display of this as `jsonPayload.component`.
	Component string `json:"component,omitempty"`
}

// String renders an entry structure to the JSON format expected by Cloud Logging.
func (e Entry) String() string {
	if e.Severity == "" {
		e.Severity = "INFO"
	}
	out, err := json.Marshal(e)
	if err != nil {
		log.Printf("json.Marshal: %v", err)
	}
	return string(out)
}

App Engine スタンダード環境では、構造化ログを stdout と stderr に書き込んでも、Cloud Logging API での 1 分あたりのログ取り込みリクエスト数にカウントされません。

メッセージ内の特別な JSON フィールド

特殊フィールドのドキュメントで説明されているように、構造化ログを JSON ディクショナリとして提供すると、いくつかの特殊フィールドが jsonPayload から削除され、生成された LogEntry の対応フィールドに書き込まれます。

たとえば、JSON に severity プロパティが含まれている場合、jsonPayload から削除され、代わりにログエントリの severity として表示されます。message プロパティが存在する場合は、ログエントリのメイン表示テキストとして使用されます。

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

エントリを JSON オブジェクトとしてフォーマットし、特定のメタデータを提供すると、フィルタリングだけでなく、リクエストログとの関連付けも有効にできます。リクエストログのエントリとアプリログのエントリを関連付けるには、リクエストのトレース ID が必要です。手順に沿ってログメッセージを関連付けます。

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

相関ログを表示するには、ログエクスプローラで相関ログエントリを表示するをご覧ください。

ログを表示する

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

Google Cloud コンソールの Cloud Logging からログエクスプローラを使用する。
Google Cloud CLI で gcloud を使用してログを表示する
さまざまな方法でプログラムによってログを読み取る

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

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

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

[ログエクスプローラ] に移動
ページの上部にある既存の Google Cloud プロジェクトを選択します。
[リソースの種類] で [GAE アプリケーション] を選択します。

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

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

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

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

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

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

[ログエクスプローラ] に移動
[リソースの種類] で [GAE アプリケーション] を選択します。
リクエストログを表示して関連付けるには、[ログ名] で [request_log] を選択します。また、リクエストログで関連付けるには、[関連付け] をクリックして [request_log] を選択します。
[クエリ結果] ペインで、ログエントリを開くには、[開く] をクリックします。エントリを開くと、各リクエストログに関連付けられたアプリログが表示されます。

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

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

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

Google Cloud CLI を使用する

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

gcloud app logs tail

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

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

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

Pub/Sub へのログシンクと、Pub/Sub から pull するスクリプトを使用する。
使用しているプログラミング言語のクライアントライブラリから Cloud Logging API を呼び出す。
Cloud Logging API REST エンドポイントを直接呼び出す。

料金、割り当て、ログの保持ポリシー

リクエストログとアプリログの両方に適用される料金については、Cloud Logging の料金をご覧ください。

ログの保持ポリシーとログエントリの最大サイズについては、割り当てと上限をご覧ください。ログを長期間保存する場合は、Cloud Storage にログをエクスポートできます。ログをさらに処理するために、BigQuery や Pub/Sub へエクスポートすることもできます。

ログリソース使用状況の管理

アプリのコードからログエントリの書き込み量を調整することで、アプリログからロギングアクティビティの量を制御できます。リクエストログは自動的に作成されるため、アプリに関連付けられたリクエストログエントリの数を管理するには、Cloud Logging のログ除外機能を使用します。

既知の問題

第 2 世代のランタイムのロギングに関する問題は次のとおりです。

アプリログのエントリが、リクエストログに関連付けられない場合がある。これは、アプリがリクエストを初めて受信した場合および、App Engine がアプリログにステータスメッセージを書き込む場合に発生します。詳細については、https://issuetracker.google.com/issues/138365527 をご覧ください。
ログシンクから Cloud Storage にログを転送した場合、Cloud Storage の転送先にはリクエストログのみが格納されます。App Engine は、複数のフォルダにアプリのログを書き込みます。
BigQuery は、リクエストログの @type フィールドが原因でログを取り込めません。BigQuery ではフィールド名に @type を使用できないため、自動スキーマ検出が中断されます。この問題を解決するには、スキーマを手動で定義し、リクエストログから @type フィールドを削除する必要があります。

次のステップ

Cloud Logging でログを表示してエラーのデバッグを行う方法と、Cloud Trace を使用してアプリのレイテンシを把握する方法については、レイテンシのモニタリングとアラートをご覧ください。