Service Debugger の使用

Gateway の Policy Manager には、ポリシーのトラブルシューティングに役立つ組み込みデバッガがあります。このデバッガは、プログラミング環境でよく使用されているデバッガと同じように機能します。このデバッガを使用すると、以下の操作ができます。
gateway92
Layer7 API Gateway
の Policy Manager には、ポリシーのトラブルシューティングに役立つ組み込みデバッガがあります。このデバッガは、プログラミング環境でよく使用されているデバッガと同じように機能します。このデバッガを使用すると、以下の操作ができます。
  • ブレークポイントの追加または削除
  • ポリシーのステップ スルーおよびそのパスの表示
  • 複合アサーションへのステップ インまたはステップ オーバー
  • コンテキスト変数の値の表示
  • デバッグの一時停止および再開
このトピックは、以下のセクションに分かれています。
開始する前に
ポリシーをデバッグする前に、以下の点に留意します。
  • デバッグできるのは、メインのサービス ポリシーとグローバル ポリシー フラグメントのみです。エイリアスおよびその他のすべてのポリシー タイプはデバッグできません。
  • 内包ポリシー フラグメントは、単体ではデバッグできませんが、サービス ポリシーまたはグローバル ポリシー フラグメントにそれを挿入するとデバッグできます(デバッガの「ステップ イン」機能を使用)。
  • デバッグできるのは、アクティブな、および保存されたバージョンのポリシーのみです。別のポリシーまたはバージョンをデバッグするには、デバッガを閉じて再度開きます。
  • Gateway ノードごとに 1 つのポリシーあたり、アクティブなデバッガ セッションを 1 つのみ使用できます。クラスタ環境では、ノードごとに 1 つのポリシーあたり 1 つのアクティブなデバッガ セッションを使用できます。
  • カプセル化されたアサーションにはステップ インできません。
  • デバッガが開始されると、サービス エンドポイントに到達する次のメッセージは、ポート番号にかかわらずデバッガに送信されます。トラフィックが多い Gateway では、ポリシーのコピーを作成し、そのコピーに対してデバッガを開始することも考慮します。
  • アクティブなバージョンのポリシーがデバッガの開始後に変更された場合は、デバッガを正しいポリシーと再同期させるために、デバッガを閉じて再度開きます。
  • デバッガは、
    特定の
    ノード上のサービスにアタッチされていることに注意してください。これは、クラスタ環境内の一部の(または 1 つの)ノードでデバッガを開始した場合に、デバッガがアタッチされていないノードにロード バランサがメッセージをルーティングする可能性があることを意味します。これを回避するには、そのサービスのすべてのノードでデバッガを開始します。
セキュリティ ロール
Service Debugger を使用するには、デバッグするポリシーにデバッガ権限が必要です。以下の事前定義済みロールにはこの権限があります。
  • Administrator:
    すべてのポリシーに対してデバッガを起動できます。
  • Manage Webservices:
    すべてのポリシーに対してデバッガを起動できます。
  • Manage
    [name]
    Service:
    指定されている名前のサービスに対してのみデバッガを起動できます。
    デバッガが任意のグローバル ポリシー フラグメントにアクセスするには、個別の 「Manage [name] Service」ロールが必要です。サービス ポリシーに内包フラグメントが含まれている場合、そのフラグメントの表示またはステップ インには、そのフラグメントに対する読み取り権限が必要です。
  • Manage
    [name]
    Policy
    : 指定されている名前のグローバル ポリシー フラグメントに対してのみデバッガを起動できます。サービス ポリシーに内包フラグメントが含まれている場合、そのフラグメントの表示またはステップ インには、そのフラグメントに対する読み取り権限が必要です。
    注:
    その他のすべてのフラグメント タイプでは、このロールは Service Debugger に影響を及ぼしません。
事前定義済みロールの詳細については、「事前定義済みのロールおよび権限」を参照してください。
サポートされていないロールに対しては、[Service Debugger]オプションは表示されません。現時点では、カスタム ロールにデバッガ権限を追加することはできません。
Service Debugger の実行
ポリシーをデバッグする方法
  1. サービスおよびポリシー リスト内のポリシーを右クリックし、[
    Service Debugger
    ]を選択します。そのポリシーのアクティブなバージョンが、[Service Debugger]ダイアログ ボックスにロードされます。
    デバッグできるのは、メインのサービス ポリシーとグローバル ポリシー フラグメントのみです。その他のすべてのポリシー タイプでは、デバッグできないため、[Service Debugger]オプションは表示されません。デバッガ オプションが表示されるには、指定したポリシーに対してデバッガ権限が必要です。 
    image2014-9-15 12:14:25.png上部ペインには、Service Debugger を開いたときにアクティブだったポリシーが表示されます。デバッグを開始すると、下部ペインには、そのポリシーで使用中のコンテキスト変数が、ポリシー内の特定の時点でのその値と共に表示されます。詳細については、「コンテキスト変数ツリーの使用」を参照してください。 
    [Service Debugger]ダイアログ ボックスのサイズを変更でき、2 つのペインを区切っている分割バーをドラッグすると、各ペインのサイズを変更できます。
  2. ポリシーに 1 つ以上のブレークポイントを追加します。これにより、ポリシーの処理を一時的に停止して、その結果を調べることができます。詳細については、「ブレークポイントの使用」を参照してください。
  3. 必要に応じて、検査するほかのコンテキスト変数を下部ペインの変数ツリーに追加します。詳細については、「コンテキスト変数ツリーの使用」を参照してください。
  4. Start
    ](ショートカット キー:
    [F1]
    )をクリックして、デバッグ監視を開始します。Service Debugger は、サービス エンドポイントに向かう次のメッセージを待機します。メッセージが到達すると、それはデバッガに送信され、最初のブレークポイントに到達するまでポリシーによって処理され、そのポイントで処理が一時停止します。ブレークポイントが定義されていない場合は、メッセージはポリシーの終了まで実行されます。
  5. 処理がブレークポイントで一時停止すると、いずれかのステップ処理オプションを使用して、アサーションを手動でステップ スルーするか、または[
    Resume
    ]をクリックして、ポリシーの終わりと次のブレークポイントのどちらか早い方まで処理を再開するかを選択できます。詳細については、「ポリシーのステップ スルー」を参照してください。
  6. ポリシーの実行が終了すると、ダイアログ ボックスの下部にあるステータス領域にメッセージが表示されます。
    • ポリシーが正常に実行された場合は、「Policy completed successfully」というメッセージが表示されます。
    • ポリシーが正常に実行されなかった場合は、失敗したことと、それが発生した行番号を説明するメッセージが表示されます(例: 「Policy completed with error. Assertion Falsified: assertion number 27」)。
この時点で、以下のどれを行うか選択できます。
  • Start
    ]をクリックして、再度監視のデバッグを開始します。
  • 監視を再開する前に、ブレークポイントまたはコンテキスト変数のリストを変更します。
  • Close
    ]をクリックして Service Debugger ダイアログ ボックスを閉じた後、ポリシーを変更して、再度デバッグを開始し ます。
Stop
](ショートカット:
Shift + [F1]
)をクリックして、いつでもデバッグを停止できます。 
ブレークポイントの使用
ブレークポイントによって、ポリシー内の特定のポイントでメッセージの処理を一時停止できます。これによって、ポリシーで使用されているコンテキスト変数の値を調べることや、ポリシーを手動でステップ スルーすることができます。 
Service Debugger ダイアログ ボックスを閉じると、ブレークポイントは破棄されます。Run All Assertions Concurrently アサーションに追加できないブレークポイントは、デバッグ中に無視されます。複合アサーション内のブレークポイントによって、「ステップ処理」コントロールの動作が影響を受けることがあります。詳細については、「ポリシーのステップ スルー」を参照してください。
ブレークポイントは、いくつもの方法で設定できます。
  • 上部ペインで、行番号とアサーション名の間の空白をクリックします。
  • アサーションを右クリックし、[
    Toggle Breakpoint
    ]を選択します。
  • アサーションを選択してから、[
    Toggle Breakpoint
    ]をクリックします。
ブレークポイントは、いくつもの方法でクリアできます。
  • アサーション名の隣にあるブレークポイント アイコンをクリックします。
  • アサーションを右クリックし、[
    Toggle Breakpoint
    ]を選択します。
  • アサーションを選択してから、[
    Toggle Breakpoint
    ]をクリックします。
  • すべてのブレークポイントを一度に削除するには、[
    Remove All Breakpoints
    ]をクリックします。これは、既存のすべてのブレークポイントを新しいブレークポイントに置き換える場合に役立ちます。
    デバッガを閉じたときにブレークポイントは保存されないため、ポリシーに戻る前にブレークポイントをクリアする必要はありません。
処理がブレークポイントで一時停止すると、そのアサーションは黄色で強調表示され、メッセージの進捗状況が示されます。後述の「ステップ処理」オプションのいずれかを選択して続行します。
ポリシーのステップ スルー
ブレークポイントで処理が一時停止したら、ステップ処理オプションのいずれかを使用して、手動でポリシーをステップ スルーできます。
複合アサーションまたは Included ポリシー内にブレークポイントが存在する場合、それらはステップ処理階層より優先されます。詳細については、後述の例を参照してください。 
ステップ オーバー
「同じレベルの」無効化されていない次のアサーションに進むには、[
Step Over
]をクリックします。
複合アサーションでは、[
Step Over
]により、その複合アサーション親に移動した後、その複合アサーションの直後にある同一レベルの次のアサーションに移動します。
ショートカット キー: [F3]
以下の例を考えてみます。
Assertion 1 <-- breakpoint here Assertion 2 (composite assertion or policy fragment) Child A Child B Child C Assertion 3
Step Over
]の動作
  • Assertion 1 --> Assertion 2 --> Assertion 3
  • Child A にもブレークポイントがある場合:
    Assertion 1 --> Assertion 2 --> Child assertion A --> Assertion 3
  • Child A と Child C にもブレークポイントがある場合:
    Assertion 1 --> Assertion 2 --> Child A --> Child C --> Assertion 3
ステップ イン
階層に関係なく、無効化されていない次のアサーションにステップ インするには、[
Step Into
]をクリックします。
ショートカット キー: [F2]
Run All Assertions Concurrently アサーションまたはカプセル化されたアサーションにはステップ インできません。その場合、[
Step Into
]をクリックすると[
Step Over
]と同じ動作になります。
ステップ アウト
複合アサーションの処理を終了するには、[
Step Out
]をクリックします。これによって、親レベルの次のアサーションが選択されます。
ショートカット キー: Shift + [F3]
以下の例を考えてみます。
Assertion 1 Assertion 2 (composite assertion or policy fragment) Child A Child B <-- breakpoint here Child C Assertion 2a (composite assertion or policy fragment) Child D Child E Assertion 3
Step Out
]の動作
  • Child B --> Assertion 3
  • Child D にもブレークポイントがある場合:
    Child B --> Child D --> Assertion 3
  • Child D と Child E にもブレークポイントがある場合:
    Child B --> Child D --> Child E --> Assertion 3
Run Assertions for Each Item アサーション内でステップ アウトする場合、そのアサーション全体からではなく、
現在のループのみ
からステップ アウトします。そのアサーションで繰り返しが残っている場合は、デバッガは再度ループに入った後、そのアサーション内の次のブレークポイント(存在する場合)で停止します。 
再開
ポリシー ロジックに基づいて処理を続行するには、[
Resume
]をクリックします。次のブレークポイントとポリシーの終わりのどちらか早い方まで、処理を続行します。(ショートカット キー:
[F4]
停止
デバッグを停止し、[Service Debugger]ダイアログ ボックスは表示したままにするには、[
Stop
]をクリックします。ポリシーの処理は、ポリシーの終わりに達するまでバックグラウンドで続行されます。
コンテキスト変数ツリーの使用
コンテキスト変数ツリーには、特定のブレークポイントの時点で設定されているコンテキスト変数が表示されます。これによって、処理中にリアルタイムに変数の中を「ピークする」ための容易な方法が提供されます。コンテキスト変数は以下の形式でリスト表示されます。
name = {dataType} "value"
説明
  • name:
    コンテキスト変数の名前
  • dataType:
    コンテキスト変数の Java クラス名(例: String、Integer、Message、ArrayList)
  • value:
    特定のブレークポイントでのその変数の値
例:
error.status = {String} "403"
(1) コンテキスト変数はアルファベット順でリスト表示されます。(2) コンテキスト変数ツリー内の任意の行を選択して Ctrl - [C]を押すと、その行をコピーできます。子ノードは、Shift または Ctrl キーを使用して選択する必要があることに注意してください。(3) コンテキスト変数は、デバッガの停止中は保持されますが、デバッガが再度開始されるとクリアされます。 
メッセージ変数
タイプが「Message」のコンテキスト変数では、子ノードにはメッセージの属性の値が表示されます。例:
image2014-10-1 16:28:50.png
上記の例の解釈:
  • このコンテキスト変数はリクエスト メッセージであり、この変数のルート ノードは「request」です。この変数に関するすべての情報は子ノードで表示されています。
  • このメッセージの 3 つのコンテキスト変数は次のとおりです。
    • request.contentType
    • request.http.allheadervalues
    • request.mainpart
      このポリシーにステップ スルーすると、これらの 3 つの変数はコンテキスト変数ツリーに自動的に表示されます。
  • request.http.allheadervalues
    変数は 7 つの値を持つ配列です。子ノードには、メッセージ内のすべてのヘッダの値がリスト表示されています。
リスト変数
タイプが「List」または「Array」のコンテキスト変数では、子ノードには各インデックスの値が表示されます。例としては、「http.allheadervalues」を参照してください。
コンテキスト変数の例外
Export Variables from Fragment アサーションで設定されているコンテキスト変数。 
Require WS-Addressing アサーションで設定されているコンテキスト変数は、[WS-Addressing Properties]でプレフィックスが定義されている場合にのみ、コンテキスト変数ツリーに表示されます(このアサーションでは、プレフィックスはオプションです)。例外:
${<prefix>.elements}
要素は、後ほどポリシー内で使用される場合にのみ、コンテキスト変数ツリーに表示されます。 
コンテキスト変数の検索
コンテキスト変数をすばやく見つけるには、その名前の最初の数文字を[Search]ボックスに入力すると、一致するすべての変数が表示されます。表示された名前をクリックするか、または Up/Down 矢印キーを使用して選択してから
Enter
キーを押すと、その変数にジャンプできます。 
いくつかの検索のヒントを以下に示します。
  • 検索では大文字と小文字は区別されません。
  • 検索では、入力されたテキストが変数名のどこに含まれていても一致します。
  • 変数名のみが照合され、変数値は検索されません。
  • ネストしている変数では、名前の子の部分のみが照合されます。たとえば、「contentType」変数の完全名は、実際には「request.contentType」ですが、「request.contentType」ではなく「contentType」を検索する必要があります。
コンテキスト変数の手動での追加
ポリシーで設定されているコンテキスト変数に加えて、ほかのコンテキスト変数を可変ツリーに手動で追加することもできます。これによって、デフォルトではツリーに表示されないほかの組み込み変数を表示したり、任意のカスタム コンテキスト変数を調べたりできます。 
デバッガの実行中または停止中に、コンテキスト変数を追加できます。
デバッガを閉じると、手動で追加した変数はコンテキスト変数ツリーに保存されません。
別の組み込みコンテキスト変数を手動で追加する方法
  1. コンテキスト変数ツリーの下にあるドロップダウン リストから変数を選択します。
    Add
    ]をクリックします。その変数がツリーに追加され、手動で追加された変数であることを示すために青で表示されます。デバッガが再開されるまで、変数は最初は空です。
カスタム コンテキスト変数を指定する方法
  1. ドロップダウン リストのボックスに、ラッパー文字「${ }」を付けるかまたは付けずに、カスタム変数の名前を入力します。画面上の検証機能によって、変数の構文がチェックされます。
  2. Add
    ]をクリックします。その変数がツリーに追加され、手動で追加された変数であることを示すために青で表示されます。デバッガが再開されるまで、変数は最初は空です。
追加の変数をツリーから手動で削除する方法
  • 変数を右クリックし、[
    Delete
    ]を選択します。
デフォルトで表示される変数(つまり、手動で追加されていない変数)は削除できません。