Working with the Service Debugger

The Policy Manager for the gateway has a built-in debugger to help you troubleshoot your policies. This debugger behaves similar to debuggers commonly found in programming environments. Use the debugger to:
gateway92
The Policy Manager for the
Layer7 API Gateway
has a built-in debugger to help you troubleshoot your policies. This debugger behaves similar to debuggers commonly found in programming environments. Use the debugger to:
  • Add or remove breakpoints
  • Step through a policy and view its path
  • Step into or over composite assertions
  • View values within context variables
  • Pause and resume debugging
This topic is divided into these sections:
Before You Begin
Keep in mind the following points before you debug a policy:
  • Only the main service policy and global policy fragments can be debugged. Aliases and all other policy types cannot be debugged.
  • Included policy fragments cannot be debugged on their own, but they can be debugged once inserted into a service policy or global policy fragment (using the "Step Into" function of the debugger).
  • Only the active and saved version of a policy can be debugged. To debug another policy or version, close and reopen the debugger.
  • There can be only one active debugger session per policy per Gateway node. In a clustered environment, you can have one active debugger session per policy per node.
  • Encapsulated assertions cannot be stepped into.
  • Once the debugger is started, the next message that arrives at the service endpoint is sent to the debugger, regardless of port number. In a high traffic Gateway, consider creating a copy of the policy and start the debugger in the copied policy.
  • If the active version of a policy changes after a debugger is started, be sure to close and reopen the debugger to re-synchronize the debugger with the correct policy.
  • Be aware that the debugger is attached to a service on a 
    specific
     node. This means that if the debugger is started on only some (or one) node in a clustered environment, the load balancer may route a message to a node without the debugger attached. To prevent this from happening, start the debugger on all nodes for the service.
Security Roles
To use the Service Debugger, you must have debugger permission to the policy being debugged. The following predefined roles have this permission:
  • Administrator
    : Allows you to launch the debugger for all policies.
  • Manage Webservices:
     Allows you to launch the debugger for all policies.
  • Manage
     
    [name]
     
    Service:
     Allows you to launch the debugger for the named service only.
    Debugger access to any global policy fragments also require a separate "Manage [name] Policy" role. If the service policy contains an included fragment, you require Read permission to that fragment to view or step into that fragment.
  • Manage
     
    [name]
     
    Policy:
     Allows you to launch the debugger for the named global policy fragment only. If the service policy contains an included fragment, you require Read permission to that fragment to view or step into that fragment.
    Note:
    For all other fragment types, this role has no impact on the Service Debugger.
For more information about the predefined roles, see Predefined Roles and Permissions.
The "Service Debugger" option is not visible for unsupported roles. It is currently not possible to add debugger permissions to custom roles.
Running the Service Debugger
To debug a policy:
  1. Right-click a policy in the services and policies list and then select 
    Service Debugger
    . The active version of the policy is loaded into the Service Debugger dialog.
    Only the main service policy and global policy fragments can be debugged. All other policy types cannot be debugged and do not display the "Service Debugger" option. You must have debugger permission for the given policy to see the debugger option. 
     image2014-9-15 12:14:25.pngThe top pane displays the policy that was active when the Service Debugger was open. Once debugging begins, the bottom pane shows the context variables in use by the policy, with their values at the particular point in the policy. For more information, see "Using the Context Variables Tree". 
    You may resize the Service Debugger dialog and alter the size of each pane by dragging the split bar separating the two panes.
  2. Add one or more breakpoints to the policy. This allows you to pause policy processing temporarily to examine the results. For more information, see "Using Breakpoints".
  3. Optionally add more context variables that you wish to inspect to the variables tree in the bottom pane. For more information, see "Using the Context Variables Tree".
  4. Click [
    Start
    ] (
    shortcut key: [F1]
    ) to start the debugging monitor. The Service Debugger waits for the next message destined for the service endpoint. When a message arrives, it is sent to the debugger and processed by the policy until it reaches the first breakpoint, at which point processing is suspended. If no breakpoints are defined, then the message runs to the end of the policy.
  5. When processing pauses at a breakpoint, you can choose to use one of the stepping options to manually step through the assertions or click [
    Resume
    ] to resume processing until the end of the policy or the next breakpoint is reached, whichever comes first. For more information, see "Stepping Through the Policy".
  6. When the policy finishes executing, a message is displayed in the status area at the bottom of the dialog.
    • If the policy executed successfully, the message reads "Policy completed successfully".
    • If the policy did not complete successfully, the message describes the failure and the line number where it occurred; for example: "Policy completed with error. Assertion Falsified: assertion number 27".
At this point, you can choose to do any of the following:
  • Click [
    Start
    ] to restart debugging monitoring again.
  • Modify your breakpoints or list of context variables before restarting monitoring.
  • Click [
    Close
    ] to dismiss the Service Debugger dialog and then alter the policy before debugging again.
You can click [
Stop
] (
shortcut: Shift+[F1]
) at any time to stop the debugging. 
Using Breakpoints
Breakpoints allow you to suspend processing of a message at a particular point in the policy. This allows you to examine the values of context variables used in the policy or  o step through the policy manually. 
Breakpoints are discarded when you close the Service Debugger dialog. Breakpoints cannot be added to the Run All Assertions Concurrently Assertion are ignored during debugging. Breakpoints inside composite assertions can affect how the "stepping" controls work. See "Stepping Through the Policy" for more details.
You can set a breakpoint in any number of ways:
  • Click in the white space between the line number and assertion name in the top pane.
  • Right-click an assertion and select [
    Toggle Breakpoint
    ].
  • Select an assertion and then click [
    Toggle Breakpoint
    ].
You can clear a breakpoint in any number of ways:
  • Click the breakpoint icon next to the assertion name.
  • Right-click an assertion and select [
    Toggle Breakpoint
    ].
  • Select an assertion and then click [
    Toggle Breakpoint
    ].
  • Click 
    [Remove All Breakpoints
    ] to delete all breakpoints at once. This is useful if you want to replace all existing breakpoints with new ones.
    Breakpoints are not saved when the debugger is closed, so it is not necessary to clear the breakpoints before returning to your policy.
When processing is paused at a breakpoint, the assertion is highlighted in yellow to indicate the progress of the message. Choose one of the "stepping" options below to continue.
Stepping Through the Policy
When processing is paused at a breakpoint, you can use one of the stepping options  o step through the policy manually.
If breakpoints exist inside a composite assertion or included policy, they take precedence over the stepping hierarchy. See examples below for more details. 
Step Over
Click [
Step Over
] to step to the next non-disabled assertion 
at the same level
. For composite assertions, [
Step Over
] moves to the composite assertion parent, then to the next equal-level assertion immediately after the composite assertion. 
Shortcut key: [F3]
For example, consider the following:
Assertion 1 <-- breakpoint here Assertion 2 (composite assertion or policy fragment) Child A Child B Child C Assertion 3
How [
Step Over
] behaves:
  • Assertion 1 --> Assertion 2 --> Assertion 3
  • If also breakpoint at Child A: 
    Assertion 1 --> Assertion 2 --> Child assertion A --> Assertion 3
  • If also breakpoints at Childs A & C: 
    Assertion 1 --> Assertion 2 --> Child A --> Child C --> Assertion 3
Step Into
Click [
Step Into
] to step to the next non-disabled assertion, regardless of hierarchy. 
Shortcut key: [F2]
It is not possible to step into the Run All Assertions Concurrently Assertion or an encapsulated assertion. Clicking [
Step Into
] in this case has the same effect as [
Step Over
].
Step Out
Click [
Step Out
] to exit processing a composite assertion. This selects the next parent-level assertion. 
Shortcut key: Shift+[F3]
For example, consider the following:
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
How [
Step Out
] behaves:
  • From 
    Child B --> Assertion 3
  • If also breakpoint at Child D: 
    Child B --> Child D --> Assertion 3
  • If also breakpoints at Child D & E: 
    Child B --> Child D --> Child E --> Assertion 3
Stepping out within a Run Assertions for Each Item Assertion steps out of the 
current loop only
, not the entire assertion. If there are more iterations remaining in this assertion, the debugger enters the loop again and then stops at the next breakpoint within that assertion (if one exists). 
Resume
Click [
Resume
] to continue processing based on the policy logic. Processing continues until the next breakpoint or the end of the policy, whichever comes first. (
shortcut key: [F4]
)
Stop
Click [
Stop
] to stop debugging, but leave the Service Debugger dialog open. Policy processing continues in the background until the end of the policy is reached.
Using the Context Variables Tree
The context variables tree displays the context variables that have been set as of a particular breakpoint. It offers an easy way to "peek" into a variable in real time during processing. The context variables are listed in the following format:
name = {dataType} "value"
Where:
  • name
     is the name of the context variable
  • dataType
     is the Java class name of the context variable (for example: String, Integer, Message, ArrayList)
  • value
     is the value of the variable at that particular breakpoint
Example:
error.status = {String} "403"
(1) The context variables are listed in alphabetical order. (2) You can copy any line in the context variables tree by selecting it and pressing Ctrl-[C]. Note that child nodes need to be specifically selected (use the Shift or Ctrl keys to select). (3) The context variables are retained when the debugger stops, but are cleared when the debugger is started again. 
Message Variables
For context variables of type Message, child nodes display the values for the attributes of the message; for example: 
image2014-10-1 16:28:50.png
Interpreting the example above:
  • The context variable is a request message, where "request" is the root node of the variable. All information about this variable are given in the child nodes.
  • The three context variables for this message are:
    • request.contentType
       
    • request.http.allheadervalues
       
    • request.mainpart
      These three variables are automatically shown in the context variables tree as you step through the policy.
  • The variable 
    request.http.allheadervalues
     is an array containing seven values. The child nodes list of the value of all the headers in the message.
List Variables
For context variables of type List or Array, child nodes display the value of each index. For an example, see "http.allheadervalues".
Context Variable Exceptions
Context variables set by the Export Variables from Fragment Assertion). 
Context variables set by the Require WS-Addressing Assertion show in the context variables tree only if a prefix is defined in the WS-Addressing Properties (a prefix is optional for this assertion). Exception: The 
${<prefix>.elements}
 variable is displayed in the context variables tree only if it is used later in the policy. 
Searching for a Context Variable
To locate a context variable quickly, type the first few characters of its name in the Search box to display all matching variables. You can jump to a variable by clicking on the displayed name or by selecting it using the Up/Down arrow keys followed by the [
Enter
] key. 
The following are some search tips:
  • The search is not case sensitive.
  • The search will match the typed text anywhere within the variable name.
  • Only variable names are matched; variable values are not included in the search.
  • For nested variables, only the child portion of the name is matched. For example, the full name for the "contentType" variable is actually "request.contentType". However you need to search for "contentType", not "request.contentType".
Manually Adding Context Variables
In addition to the context variables set in the policy, you can also manually add other context variables to the variable tree. This allows you to view other built-in variables that are not displayed by default in the tree or to examine any custom context variables. 
Context variables may be added while the debugger is running or stopped.
Manually added variables are not saved in the context variable tree when the debugger is closed.
To manually add another built-in context variable:
  1. Choose the variable from the drop-down list below the context variable tree.
    Click [
    Add
    ]. The variable is added to the tree and is shown in blue to indicate a manually added variable. The variable is  empty initially, until the debugger resumes.
To specify a custom context variable:
  1. Type in the name of the custom variable in the box for the drop-down list , with or without the "${ }" wrapper characters. The on-screen validator checks the syntax of the variable.
  2. Click [
    Add
    ]. The variable is added to the tree and is shown in blue to indicate a manually added variable. The variable is empty initially, until the debugger resumes.
To remove a manually added variable from the tree:
  • Right-click the variable and then select 
    Delete
    .
Variables that are displayed by default (that is, those not manually added) cannot be removed.