Layer 7 API Gateway: Debugging in policy
search cancel

Layer 7 API Gateway: Debugging in policy


Article ID: 136303


Updated On:


CA API Gateway


Debugging policies can be difficult. We do have the policy debugger and we do have a debugging policy. Both tools help but the out-of-the-box debugging policy does not really produce a meaningful output. Here are a few tips to get you started. 


All supported versions of the API Gateway



  1. Place an Audit Messages in policy assertion into your service and configure it to always capture requests and responses
  2. Do a right-click on the service
  3. Select the service properties, then select Enable policy debug tracing
  4. In the appearing dialog "Do you want to edit the debug trace policy now?" select Yes
  5. In that policy you want to remove the "Audit Messages in Policy" assertion on line 5
  6. Now select the "Add Audit Details" assertion and let's work on that below:


Without changing anything the Add audit Details assertion has this content:

TRACE:${}${} policy.guid=${trace.policy.guid} assertion.number=${trace.assertion.numberstr} assertion.shortname=${trace.assertion.shortname} status=${trace.status}

As you can see it contains strings such as "", ... "policy.guid", ... these strings are used as labels. That is all good but it makes the audit result difficult to read. It also has the "trace.status" at the end although that may be the most important information you want to look at. Here is an example of the output:

What you are interested in are error codes (trace.status) and policy line numbers (trace.assertion.numberstr). But they are hidden in the log audit message at the end.


Setting up a more simple and informative Audit Detail logs:


You can turn this message into something very helpful by replacing the content of the audit detail assertion using this message:

TRACE: [${trace.status}][${trace.assertion.numberstr}][${trace.assertion.shortname}][${}]

I removed all labels and I moved the important content to the front. I have put variables into [...] brackets. The brackets will contain the following information:

  • 1: [...]: '0' if the assertion executed without error, >0 if an error occurred. Depending on your policy you may expect assertions to fail, such as comparisons!
  • 2: [...]: the assertion line number. It will tell you exactly which line was executed. If it shows something like [3.45] read it as: line 3 in the service is a fragment (or encapsulated assertion). Within that fragment (or encapsulated assertion) the policy failed on line 45. If the line numbers are not shown for encapsulated assertions open the encapsulated assertion configuration and enable Allow debug tracing into backing policy
  • 3: [...]: the assertion name
  • 4: [...]: the policy name


The new output looks like this:


Additional Information

CA recommends not to turn on audits in production environments.  If you need to keep Audits in production, we recommend not doing so internally on the Gateway servers, but relay the Audits to either an external DB, file system, or remote Syslog Server.  If you need to Turn on audits in production please do so sparingly and revert the changes once they are no longer required.  Keeping Audit logs on may fill up your database and bring down your environment.  CA also recommends the use of a manage audit records script.


1566922031226__audit2.png get_app
1566917351452__audit1.png get_app