デバッグ スナップショット

アプリをデプロイまたは起動したら、Google Cloud Console で Cloud デバッガを開くことができます。Debugger を使用すると、アプリを停止または実行速度を低下させることなく、コールスタックやローカル変数をキャプチャ、検査できます。

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

準備

Debugger は、アプリのソースコードへのアクセス権の有無に関係なく使用できます。ソースコードが入手できない場合は、下記のデバッグ スナップショットの作成で、手動でファイル名と行番号を入力する手順をご覧ください。

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

スナップショット

スナップショットは、アプリのソースコード内の特定の行位置でローカル変数とコールスタックを収集します。アプリのデータのスナップショットを返す特定の条件と場所を指定して、詳細を表示し、アプリのデバッグを行うことができます。

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

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

この処理の後、スナップショットがトリガーされると、結果が [変数] と [コールスタック] ペインに表示されます。スナップショットが設定後 40 秒以内にトリガーされると、カナリア スナップショットが適用されたインスタンスの結果が表示されます。

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

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

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

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

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

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

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

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

デバッグ スナップショットの作成

Console

スナップショットを作成したい場所の、ソースコードの行番号をクリックします。

  1. [スナップショット] パネルが選択されていることを確認します。
  2. ソースコードを含むファイルを選択します。選択したファイルの内容が中央のパネルに表示されます。

  3. ソースコードの場所の行番号をクリックします。

    スナップショットの場所を参照。

複数の行をクリックすると、ファイルに複数のスナップショットを設定できます。

Debugger にソースコードを読み込む他の方法については、ソースコードのオプションをご覧ください。

使用可能なソースコードがない場合は、「ファイル名:行」を手動で入力し、[スナップショット] パネルでスナップショットを取得できます。

手動でスナップショットの場所を設定。

gcloud

コマンドラインを使用してスナップショットの場所を設定するには、以下のコマンドを実行します。

gcloud debug snapshots create LOCATION

ここで

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

スナップショット条件（オプション）

スナップショットの条件とは、アプリの言語（Java、Python、Go をサポート）における単純な式のことで、作成するスナップショットについて true と評価される必要があります。スナップショットの条件は、任意のインスタンスによって条件が true と評価されるかスナップショットがタイムアウトするまで、行が実行されるたびに評価されます。

スナップショット条件の使用はオプションです。

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

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

コンソール

条件を指定するには、スナップショットを作成します。[条件] フィールドに条件を入力し、[更新] を選択します。条件が true と評価されると、スナップショットがトリガーされます。

スナップ ショット条件の設定。

gcloud

条件を指定するには、次のように snapshots create で --condition フラグを使用します。

gcloud debug snapshots create LOCATION --condition="ultimateAnswer <= 42 && foo==bar"

条件を表現するために、次の言語機能を使用できます。

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 以外の関数の呼び出し。

式（オプション）

Debugger の式機能を使用すると、スナップショットの作成時に複雑な式を評価することや、オブジェクト階層の走査ができます。式では、前述したスナップショットの条件での場合と同じ言語機能をサポートしています。

式の使用はオプションです。

式の典型的な用途は以下のとおりです。

  • ローカル変数セットの一部ではない静的変数またはグローバル変数の表示。
  • Debugger パネル内のローカル変数を毎回拡張する必要のない、深くネストされたメンバー変数の簡単な表示。
  • 反復的な数学的計算の回避。たとえば、(endTimeMillis - startTimeMillis) / 1000.0 での秒単位の時間の計算。

式を追加するには:

Console

  1. [式] フィールドに式を入力します。式は必要な数だけ追加できます。
  2. [再作成] を選択します。

スナップショットが作成されると、式の結果が表示されます。

式を設定。

gcloud

式を定義するには、snapshots create の --expression フラグを使用します。

gcloud debug snapshots create LOCATION \
  --expression="histogram.length"

スナップショットの表示

Console

指定した場所でアプリがソースコードを実行すると、Debugger にスナップショットのデータが表示されます。インスタンス変数とローカル変数は、パネルの [変数] セクションに表示されます。スタック トレースは、パネルの [コールスタック] セクションに表示されます。

スナップショットを表示。

スナップショットが作成された瞬間のローカル変数の値を調べて、より深いデータ構造をドリルダウンできます。また、任意のコール スタック フレームをクリックして、スタック内のそのレベルでローカル変数を調べることができます。

ファイルに複数のスナップショットを設定した場合や、作成済みのスナップショットを表示する場合は、[スナップショットの履歴] パネルを展開します。

スナップショット履歴を表示。

gcloud

コマンドラインからスナップショットの Google Cloud コンソール URL を取得するには、以下のコマンドを実行します。

gcloud debug snapshots list

STATUS  LOCATION                   CONDITION  COMPLETED_TIME  ID                  VIEW
ACTIVE  HighScoreService.java:105                             53bd97d4-b6c6-74fc  https://console.cloud.google.com/debug/fromgcloud?project=abc&dbgee=def&bp=ghi

Google Cloud コンソールでスナップショットを表示するには、VIEW 列の値をコピーしてブラウザに貼り付けます。

コマンドラインを使用して詳細なスナップショット データを表示するには、以下のコマンドを実行します。

gcloud debug snapshots describe 53bb1240f371b-baa0-feb5d

describe コマンドは、スタック トレースとローカル変数の値を返します。このコマンドは、人が読める出力ではなく、マシンが読み取れる出力を返すことを主な目的としています。

---
consoleViewUrl: https://console.cloud.google.com/debug/fromgcloud?project=1234&dbgee=gcp%3A1234%3A843aef0bd82301f7&bp=53bb1240f371b-baa0-feb5d
createTime: '2016-08-22T23:09:32.000Z'
finalTime: '2016-08-22T23:10:16.000Z'
id: 53bb1240f371b-baa0-feb5d
isFinalState: true
location: HighScoreService.java:105
stackFrames:
<... snip ...>

スナップショットの再作成

スナップショットは、一度だけ作成されます。アプリデータの別のスナップショットを同じ場所で取得する場合には、手動でスナップショットを取得します。

コンソール

スナップショットを再作成するには、[再作成] を選択します。

[再作成] ボタンが選択されています。

新しいスナップショットが [スナップショットの履歴] パネルに追加されます。その行の過去のスナップショットには [スナップショットの履歴] またはその行番号のマーカーからアクセスできます。

以前のスナップショットがラインマーカーに表示される。

gcloud

コマンドラインからスナップショットを再作成するには、create コマンドを繰り返します。

gcloud debug snapshots create LOCATION

スナップショットの場所の削除

コンソール

スナップショットの場所を削除するには、削除 をクリックします。

スナップショットの削除が選択されています。

gcloud

コマンドラインを使用してスナップショットを削除するには、以下のコマンドを実行します。

gcloud debug snapshots delete (ID | LOCATION-REGEXP)

ここで

  • ID は gcloud debug snapshots list から返される値です。

  • LOCATION-REGEXP は、スナップショットのコードの場所を定義する正規表現です。

スナップショットの共有

スナップショットを共有するには、ブラウザまたは gcloud debug snapshots list コマンドの出力からスナップショットの URL をコピーし、プロジェクトのアクセス権を持つ別のユーザーに送ります。今後の参考のために URL を保存して、スナップショットの結果を再度表示することもできます。Debugger は、スナップショットが作成されるごとに新しい URL を使用します。これにより、コード内の同じ場所でスナップショットが作成された場合であっても、個別に結果のセットを共有できます。共有の有効期限は、スナップショットが作成されてから 30 日間です。

トラブルシューティング

デバッガ エージェントによりインスタンスがクラッシュした？

デバッガ エージェントに問題がある場合、次のエラーが表示される場合があります。

変数ペインにエラー メッセージが表示されています。

以下の理由により、まるでデバッガ エージェントが安全保護対策をトリガーしたかのような誤検出が発生することがあります。

  • デバッガ エージェントのカナリア処理中に、インスタンスがシャットダウンされたため。

    カナリア スナップショットが適用されたインスタンスがシャットダウンされると、デバッガ エージェントがインスタンスを終了したように見えます。スナップショットが設定された後 40 秒以内にインスタンスがシャットダウンされていないことを確認してください。たとえば、Cloud Run や App Engine からの自動スケーリングや、新しいコードのデプロイにより、インスタンスがシャットダウンされていることがあります。

インスタンスからデバッガ エージェントを削除して、以前のバージョンを再インストールする必要があります。以前のバージョンを再インストールするには、以前のバージョンのデバッガ エージェントをインストールするための設定手順に従ってください。

古いバージョンのエージェントで問題が解決しない場合は、false 値ではないことを確認してから、デバッガ エージェントを無効にしてフィードバックを送信します。