デバッグ ログポイント

アプリケーションをデプロイまたは起動すると、Google Cloud Console で Cloud デバッガを開くことができます。Cloud デバッガを使用すると、サービスの通常の機能を再起動したり中断したりすることなく、実行中のサービスにロギングを挿入できます。これは、ログ ステートメントを追加したり再デプロイする必要がないので、本番環境での問題をデバッグするのに便利です。

Google Cloud デバッガを使用するには、Google Cloud コンソールの [デバッグ] ページにアクセスしてください。

準備

Cloud デバッガは、アプリケーションのソースコードにアクセスできるかどうかに関係なく使用できます。ソースコードが入手できない場合は、手動でファイル名と行番号を入力する方法について、デバッグ ログポイントの追加をご覧ください。

ソースコードが Google Cloud Repository に格納されている場合、そのソースコードは自動的に [デバッグ] ビューに表示されます。

それ以外の場所（ローカルまたは Git リポジトリなど）に格納されているソースコードにアクセスするには、ソースコードの場所の選択が必要となる場合があります。

ログポイント

ログポイントでは、サービスを再起動したりサービスの通常の機能を妨げたりせずに、実行中のサービスにロギングを挿入できます。いずれかのインスタンスがログポイントの場所のコードを実行するたびに、Cloud デバッガがメッセージを記録します。ログ出力はターゲットの環境の適切なログに送信されます。たとえば App Engine では、Cloud Logging のリクエストログにログ出力が送信されます。

ログポイントは、作成後 24 時間、または削除されるかサービスが再デプロイされるまで、アクティブな状態が維持されます。受信トラフィックの多い行にログポイントを追加すると、Debugger はアプリケーションへの影響を軽減するためにログポイントを調整します。

カナリア処理が有効なデバッガ エージェント

ログポイントを設定すると、デバッガ エージェントはインスタンスのサブセットでログポイントをテストします。デバッガ エージェントがログポイントを正常に実行できることを確認したら、ログポイントがすべてのインスタンスに適用されます。分析には 40 秒ほどかかります。

このプロセスの後、ログポイントがトリガーされると、デバッグ エージェントはメッセージをログに記録します。ログポイントが設定されて 40 秒以内にトリガーされた場合、デバッガ エージェントは、カナリア ログポイントが適用されたインスタンスからメッセージをログに記録します。

デバッガ エージェントは、データをキャプチャする際に生じるレイテンシを最小限に抑えるいくつかの手法を実装しています。

Debugger エージェントがカナリア処理されている場合は、次のテキストが表示されます。

「アプリケーション インスタンスのサブセットのブレークポイントを確認しています。」

デバッガ エージェントは、インスタンスをカナリア処理しています

カナリア モードでデバッガ エージェントが失敗した場合の対処方法については、デバッグ スナップショット ページのトラブルシューティング セクションをご覧ください。

カナリア処理機能のあるデバッガ エージェント バージョンについては、言語固有のページをご覧ください。

カナリア処理が無効のデバッガ エージェント

カナリア処理が無効のデバッガ エージェントを使用してログポイントを設定すると、ログポイントはアプリのすべてのインスタンスに適用されます。いずれかのインスタンスが、設定したログポイントのロケーションでコードを最初に実行したときに、デバッガ エージェントはメッセージをログに記録します。デバッガ エージェントは、データをキャプチャする際に生じるレイテンシを最小限に抑えるいくつかの手法を実装しています。

デバッグ ログポイントの追加

Console

Google Cloud コンソールからログポイントを追加するには次を行います。

  1. 右側のパネルで [ログポイント] タブが選択されていることを確認します。
  2. 左側のパネルで、ログポイントを追加するソースコードを含むファイルを選択します。ファイルの内容がセンターパネルに表示されます。
  3. ログポイントを追加する場所の行番号をクリックし、[ログポイントを作成] を選択します。
  4. [logpoint("")] フィールドの間にメッセージを入力し、追加ボタンをクリックします。{chars} のように、式を括弧で囲むことにより、その値をロギングできます。

ログポイントのインラインを追加しています。


使用可能なソースコードがない場合は、ターゲット filename:line とその他の詳細を [ログポイント] パネルに手動で入力できます。

ログポイントを手動で追加しています。

gcloud

コマンドラインからログポイントを追加するには:

gcloud debug logpoints create LOCATION MESSAGE

ここで

  • LOCATION は、ログポイントを設定するファイルの名前と行です。FILE:LINE の形式で指定します。ここで、FILE はファイル名です。同じ名前の他のファイルと区別するために、ファイル名の前に必要なパス コンポーネントを追加することもできます。デバッグ対象に一意ではないファイル名を指定するとエラーになります。
  • MESSAGE はログに記録するメッセージです。

次の例では、info ログレベル（ログポイントのデフォルトのログレベル）で「Logging statement added」というメッセージをログに記録します。

gcloud debug logpoints create main.py:28 \
  "Logging statement added"

ログポイント メッセージの形式

ログポイントのメッセージにより、出力に何が記録されるかが決まります。式を使用することにより、特定の値を評価してログに記録できます。メッセージの中で {myObj.myFunc()} または {a + b} のように、式を括弧で囲んだものは、出力中でその式の値に置き換えられます。

式には次の言語機能を使用できます。

Java

ほとんどの Java 式がサポートされています。たとえば、以下の式がサポートされています。
  • ローカル変数: a == 8
  • 数値とブール演算子: x + y < 20
  • インスタンスと静的フィールド: this.counter == 20、this.myObj.isShutdown、myStatic、com.mycompany.MyClass.staticMember。
  • 等価演算子による文字列の比較: myString == "abc"
  • 関数の呼び出し。読み取り専用関数のみ使用できます。たとえば、StringBuilder.indexOf() はサポートされていますが、StringBuilder.append() はサポートされていません。
  • 完全修飾型での型キャスト: ((com.myprod.ClassImpl) myInterface).internalField

次の言語機能はサポートされていません。

  • 数値型（Integer など）のボックス化解除。代わりに myInteger.value を使用してください。

Python

以下を含め、ほとんどの Python 式はサポートされています。
  • ローカル変数とグローバル変数の読み取り。
  • 配列、リスト、スライス、辞書、オブジェクトからの読み取り。
  • シンプルなメソッドの呼び出し。

次の言語機能はサポートされていません。

  • 新しいオブジェクトを割り当てる関数、または複雑な構文を使用する関数の呼び出し。
  • 式の中での新しいオブジェクトの作成。

Go

以下を含め、ほとんどの Go 式構文がサポートされています。
  • ローカル変数とグローバル変数の読み取り。
  • 配列、スライス、マップ、構造体からの読み取り。

次の言語機能はサポートされていません。

  • インターフェース値からの読み取り。
  • 型変換と複合リテラル。
  • len 以外の関数の呼び出し。

ログポイントの条件

ログポイントの条件は、アプリケーション言語における単純な式であり、それの評価結果が true になる場合にのみログポイントがログに記録されます。ログポイントの条件は、ログポイントが期限切れになるか削除されるまで、いずれかのインスタンスによってその行が実行されるたびに評価されます。

条件は、論理演算子を含めることができる完全なブール式です。

travelAccessory == “Towel”
ultimateAnswer <= 42
travelAccessory == “Towel” && ultimateAnswer <= 42

条件には、式でサポートされているのと同じ言語機能を使用できます。

Console

'if' ステートメントに条件を入力します。

条件をインラインで設定します。

使用可能なソースコードがない場合は、[ログポイント] パネルで条件を指定できます。

gcloud

条件は、logpoints create の --condition フラグを使用して表現されます。 

gcloud debug logpoints create main.py:28 

  --condition="chars > 1" 

  --log-level="info" 

  "Logging statement added"

上の例では、アプリケーションの行 28 が実行された時点で、ログポイントによって chars の長さがチェックされます。この値が 1 より大きい場合、info レベルのメッセージがログに追加されます。

出力の表示

ログポイント出力はターゲット環境の適切なログに送信されます。

App Engine

App Engine アプリで設定されているログポイントは、Logging のリクエストログに出力を送信します。

ログは、ログパネルまたは専用のログ エクスプローラで表示できます。

ログパネルのログポイント。

Compute Engine

Compute Engine アプリで設定されているログポイントは、通常のログ ステートメントと同じ場所に出力を送信します。たとえば、Python では、デフォルトのロギング モジュールはその出力を stdout に送信しますが、特定のファイルに書き込むように構成することもできます。

これらのログを Cloud Logging に転送するように Logging エージェントを設定できます。そこから、ログ エクスプローラでログを表示できます。

ログポイントを削除する

ログポイントは 24 時間後に非アクティブになってメッセージの記録を停止し、30 日後に自動的に削除されます。手動でログポイントを削除できます。その場合、ログポイントによるログ記録は停止され、後で参照するための履歴からも削除されます。ただし、ログポイントを削除しても、すでに生成されたログメッセージは削除されません。

コンソール

ログポイントを手動で削除するには、[ログポイントの履歴] パネルのオーバーフロー メニューを使用します。 [メニュー] を選択し、[ログポイントを削除] を選択します。

ログポイントを削除します。

gcloud

手動でログポイントを削除するには、そのコードの場所の ID または正規表現を使用してログポイントを指定します。

gcloud debug logpoints delete main.py:28

Debug target not specified. Using default target: default-1
This command will delete the following logpoints:

LOCATION                   CONDITION            LOG_LEVEL  LOG_MESSAGE_FORMAT                                             ID
main.py:28                                      INFO       Logging statement added.                                       53aaa3bd8d2d7-b76f-feb5d

Do you want to continue (Y/n)?  Y
Deleted 1 logpoint.