Cloud デバッガは 2023 年 5 月 31 日に非推奨となります。詳細については、非推奨ページとリリースノートをご覧ください。

コンセプト

このページでは、クライアントの役割、データモデル、Stackdriver Debugger API でサポートされるオペレーションについて説明します。

クライアントの役割

API は、2 つのクライアント（エージェントとデバッガ クライアント）の役割を定義します。

エージェント

エージェントとは、デバッグ対象のアプリケーションが実行されているのと同じシステム上で動作するプログラムです。エージェントは、ブレークポイントの位置にあるコードが実行された場合に、プログラム変数の値やコールスタックなどの状態データを Stackdriver Debugger に送信します。

デバッグ対象ごとに複数のエージェントを存在させることができます。たとえば、アプリケーションがいくつかの実行可能なタスクで構成されているとします。タスクごとにエージェントがありますが、すべて合わせて 1 つのデバッグ対象です。ただし、アプリケーションの複数のバージョンを実行している場合は、それぞれのバージョンが別々にデバッグ可能な個々のデバッグ対象です。

エージェントの例としては、Google Compute Engine で実行される Java または Go で記述されたアプリケーションで使用できる、Google 提供のデバッガ エージェントが挙げられます。

デバッガ クライアント

デバッガ クライアントは、ブレークポイントの設定や削除、ブレークポイントでキャプチャされた状態データ（スナップショット）を表示するアプリケーションです。デバッガ クライアントの例として、Google Cloud Platform Console で実行される Stackdriver Debugger ツールが挙げられます。また、デバッガ機能を追加した IDE もデバッガ クライアントです。

データモデル

API データモデルは、デバッグ対象およびブレークポイントのエンティティと、ブレークポイントの位置でコードが実行されたときにエージェントが収集できる状態データの種類を提供します。

デバッグ対象

デバッグ対象とは、ユーザーがデバッグするアプリケーションです。上記のように、アプリケーションを構成するすべてのタスクが同じデバッグ対象とみなされ、同じデバッグ対象 ID を共有します。サンプル アプリケーションの異なるバージョンは、異なるデバッグ対象であるとみなされます。API では、デバッグ対象は Debuggee エンティティ（REST または RPC）で表されます。

ブレークポイント

ブレークポイントは、アプリケーションに関する状態データを収集する場所と時期についてエージェントに情報を提供するエンティティです。また、収集された状態データそのものも格納します。

ブレークポイントは、次のものを指定します。

  • デバッグ対象のソースコード内の場所
  • エージェントが状態データを収集する時期を判断するために使用する条件式
  • データが収集されたときに評価する式

デバッグ対象から状態データを収集するとき、以下を含むことができます。

  • プログラム変数の値
  • コールスタック
  • 評価された式の値

ブレークポイントは、Breakpoint エンティティ（RPC または REST）で表されます。

ソースの場所

ソースの場所は、ファイルのパスと行番号で、ターゲット アプリケーション内のポイントを定義します。ソースの場所は、SourceLocation エンティティ（RPC または REST）で表されます。

変数

変数には、状態データがエージェントによって収集された時点のプログラム オブジェクト（名前付き、または名前なし）の内容が含まれています。たとえば、整数型のローカル変数の値を含めることができます。また、それ自体が変数である任意の数のメンバーを含めることもできます。変数は、Variable エンティティ（RPC または REST）で表されます。

ステータス メッセージ

ステータス メッセージは、ブレークポイントや変数の状態に関する状態情報を提供します。たとえば、無効なソースの場所に設定されたブレークポイントには、エラーを示すステータス メッセージが含まれていることがあります。ステータス メッセージは、StatusMessage エンティティ（RPC または REST）で表されます。

形式メッセージ

形式メッセージは、ステータス メッセージのテキスト コンテンツです。形式メッセージは、FormatMessage エンティティ（RPC または REST）で表されます。

オペレーション

コントローラ インターフェースおよびデバッガ インターフェースには、エージェントとデバッガ クライアントのオペレーション セットがあります。

エージェントのオペレーション

コントローラ インターフェースで、エージェントは次のオペレーションを実行できます。

オペレーション 説明 REST RPC
登録 デバッグ対象をコントローラ サービスに登録します。 register RegisterDebuggee
アクティブなブレークポイントのリストを表示 指定されたデバッグ対象のすべてのアクティブなブレークポイントのリストを返します。 list ListActiveBreakpoints
アクティブなブレークポイントを更新 ブレークポイントでアプリケーションの状態データ（プログラム変数、コールスタックなど）を更新します。 update UpdateActiveBreakpoint

エージェントのオペレーションの一般的な順序は次のとおりです。

  1. アプリケーションが起動すると、エージェントが register または RegisterDebugger メソッドを使用して、そのアプリケーションをデバッグ対象として登録します。

  2. エージェントは周期的に list または ListActiveBreakpoints を呼び出し、現在設定されているブレークポイントを取得します。

  3. アプリケーションがブレークポイントが設定されているコード位置に到達すると、状態データ（プログラム変数やコールスタックの値など）を収集し、update または UpdateActiveBreakpoint を使用してコントローラ サービスに送信します。

デバッガ クライアントのオペレーション

デバッガ インターフェースで、デバッガ クライアントは次のオペレーションを実行できます。

オペレーション 説明 REST RPC
デバッグ対象のリストを表示 クライアントのユーザーがブレークポイントを設定できるデバッグ対象のリストを表示します。 list ListDebuggees
ブレークポイントを設定 ブレークポイントの位置を設定します。 set SetBreakpoint
ブレークポイントのリストを表示 現在のユーザーがアクセスできるブレークポイントのリストを返します。 list ListBreakpoints
ブレークポイントを取得 デバッグ対象およびブレークポイント ID 別にブレークポイントの詳細を取得します。 get GetBreakpoint
ブレークポイントを削除 指定されたブレークポイントを削除します。 delete DeleteBreakpoint

デバッガ クライアントのオペレーションの一般的な順序は次のとおりです。

  1. ユーザーが（クライアント アプリケーション UI でデバッガビューを開くなどして）デバッガ ワークフローを開始すると、クライアントが list または ListDebugees メソッドを呼び出してデバッグ可能なアプリケーションのバージョンのリストを取得し、ユーザーが選択できるようにします。

  2. ユーザーが UI でブレークポイントを作成すると、クライアント アプリケーションは set または SetBreakpoint オペレーションを呼び出し、ブレークポイントを設定します。

  3. クライアント アプリケーションは周期的に get または GetBreakpoint を呼び出し、デバッグ対象がブレークポイントの位置でコードを実行し、エージェントがブレークポイントの状態データを更新したかどうかを確認します。これらが行われている場合、クライアント アプリケーションはユーザーに状態データを表示します。

  4. ユーザーが UI でブレークポイントを削除した場合、クライアントは delete または DeleteBreakpoint を呼び出します。