Working with the Debug Trace Policy

The Policy Manager in the gateway has a special "trace policy" that can help you diagnose and troubleshoot problems in a service policy, for both SOAP and non-SOAP services. When enabled, this trace policy executes after each assertion has completed within the service being debugged.
gateway92
The Policy Manager in the
Layer7 API Gateway
has a special "trace policy" that can help you diagnose and troubleshoot problems in a service policy, for both SOAP and non-SOAP services. When enabled, this trace policy executes after each assertion has completed within the service being debugged.
The following is a partial list of the information that is passed to the trace policy for the assertion that just finished executing:
  • service entity ID
  • service ordinal
  • policy entity ID
  • policy ordinal
  • assertion status
For a complete list of information available to the trace policy, see  Debug Trace Policy Context Variables.
WARNING:
Enable policy debug tracing only for troubleshooting purposes. Do not enable it for production use. As the trace policy is run for each assertion in the policy, performance is degraded significantly.
This topic is divided into these sections:
Enabling the Debug Trace Policy
To enable the debug trace policy, select the
Enable policy debug tracing
option in the [General] tab of the  Published Service Properties. If there is an existing trace policy, it is used (new revision added), otherwise a new one is created.
After the tracing policy is enabled, it appears in the Services and Policies list with the name "[Internal Debug Trace Policy]", which is fixed and cannot be changed.
image2014-9-15 13:1:16.png
When enabled, the trace policy is executed once for each assertion that completes in the target policy.
The following characteristics are unique to the debug trace policy:
  • There is a single trace policy that is shared by all published services that have tracing enabled.
  • The debug trace policy is edited like a normal policy, but cannot be deleted while it is in use (that is, enabled in the Service Properties of any published service).
  • The debug trace policy can access many debug-specific context variables that exist only while the trace policy is active. See  Debug Trace Policy Context Variables for details.
  • The debug trace policy uses the same audit context as the policy being traced. For example, audit detail messages added during tracing are combined with the detail messages from the target policy.
  • The properties for a debug trace policy cannot be modified.
  • The debug policy can optionally trace into the underlying policy fragment of an encapsulated assertion. For details, see  Encapsulated Assertion Configuration Properties.
Aside from the above exceptions, the debug trace policy behaves like any ordinary policy: policy revisions apply and you can export or import the debug trace policy.
Deleting the Debug Trace Policy
When the debug trace policy is no longer required, you can delete it by right-clicking it in the Services and Policies list and selecting
Delete Policy
. You cannot delete the trace policy if debug tracing is still enabled on any policy.
If you delete the debug trace policy, it is recreated the next time policy debug tracing is enabled. However be aware that is an entirely new trace policy—it does not have access to any policy revision history from the previously deleted trace policy. Do not delete the trace policy if you want to keep its revision history.
Understanding the Debug Trace Policy
When the debug trace policy is enabled for the first time, it is created with a simple default policy (line wraps under "Audit Details" in the illustration below have been added for clarity):
image2014-10-1 16:34:39.png
The default trace policy can be used immediately, without modification. It does the following:
  1. Enables auditing with the  Audit Messages in Policy Assertion.
  2. Adds the following details to the audit record using the  Add Audit Detail Assertion Add Audit Detail assertion:
    • name of the service
    • name of the policy
    • GUID of the policy
    • number of the assertion within the policy
    • name of the assertion
    • status returned by the assertion
These details are retrieved from the corresponding debug trace context variables. You may edit the default trace policy as necessary.
More Complex Example
The following is a more complex trace policy that collects trace information for an entire request as a batch, then emails it to someone, sending no more than one email per traced request:
Set Context Variable: ${trace.out} = "${trace.out} TRACE: service.oid=${trace.service.oid} assertion.number=${trace.assertion.numberstr} policy.guid=${trace.policy.guid} assertion.shortname=${trace.assertion.shortname} status=${trace.status}\n" At Least One Assertion Must Evaluate to True All Assertions Must Evaluate to True Compare Expression: ${trace.final} == "true" Send Email Alert: [email protected]: subject=Debug trace for policy body="${trace.out}" Continue Processing
In this more complex example, a new line beginning with "TRACE:" is appended to the
${trace.out}
context variable each time the trace policy is invoked for a request. When the debug trace is complete (
${trace.final}
returns "true"), the contents of the
${trace.out}
variable is emailed to [email protected].
The trace policy can be as complex and full featured as any normal service policy, but CA Technologies highly recommends keeping it as short and basic as possible. Remember, the full trace policy is executed each time an assertion completes in the target policy.
Saving Trace Information to a File
To save the trace information to a log file:
  1. Using the  Manage Log/Audit Sinks task, create a log sink with the following properties:
    Name:
    trace
    Description:
    Save trace information to a file
    Type:
    File
    Severity Threshold:
    All
    Selected Categories:
    Gateway Log, Audits
    (hold down [Ctrl] key to select both)
  2. Using the  Manage Cluster-Wide Properties task, add the cluster property log.levels with the following line that is appended to the value:
    com.l7tech.server.trace.TracePolicyEvaluator.level = FINER
  3. Configure your trace policy to accumulate any desired trace information in the context variable ${trace.out}. For example, the policy sample under "
    More Complex Example
    " above is a good example.
  4. When service consumption is complete, you can find the trace log file in this directory:
    /opt/SecureSpan/Gateway/node/default/var/logs
Security Permissions
To edit a debug trace policy, you must have one or more roles that grant permission for:
  • Managing services
  • Managing policies
  • Managing cluster-wide properties
These can be either predefined roles or custom roles with the appropriate permissions.
Adding an Audit Sink to Debug Tracing
For a comprehensive debugging solution, configure an audit sink that runs in addition to a debug trace policy. This helps troubleshoot issues such as the service policy terminating unexpectedly with a serious policy exception. When a policy terminates abnormally, debug tracing also stops. The addition of an audit sink lets you take some action after the termination.
The audit sink policy
cannot
access any of the context variables?created by the debug trace policy.
If an audit sink is configured, it is invoked after a request finishes processing.
To enable policy debug tracing:
  1. Open the properties for the service being debugged.
  2. In the [General] tab, select the
    Enable policy debug tracing
    check box.
  3. Click [
    OK
    ]. You are asked whether you want to edit the debug trace policy.
    • Click [
      Yes
      ] to open the trace policy for editing. You have a chance to save any currently open policy as a new revision.
    • Click [
      No
      ] to continue working in the current policy. You can edit the trace policy later by opening [Internal Debug Trace Policy] from the Services and Policies list.
Once tracing is enabled, the trace policy is run every time an assertion completes in the service policy. The performance impact depends on the complexity of the trace policy, but it is likely significant.
To allow debug tracing to access the assertions within the underlying policy fragment ("backing policy") of an encapsulated assertion, you must select the "Allow debug tracing into backing policy" check box in the  Encapsulated Assertion Configuration Properties.