Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Working with the Audit Sink Policy

Last update January 26, 2018

A special audit sink policy directs all the audit messages to an external database, message queue, or other location.This policy runs at the end of every service policy that is executed on the Gateway. 

The audit sink policy is created automatically when you first enable the audit sink; you can reconfigure it later if necessary.


The audit sink policy is found in the Services and Policies list on the Policy Manager interface and appears as follows in the policy window:

The following characteristics are unique to the audit sink policy:

  • Only one audit sink policy is created per CA API Gateway cluster.
  • Disabling the audit sink does not remove the audit sink policy—it simply redirects audit messages to the CA API Gateway database.

    Note: It is possible to configure the audit messages to be sent simultaneously to the database and audit sink. See Manage Log/Audit Sinks.

  • An audit sink policy can be deleted only when first disabled in the Audit Sink Properties.
  • An audit sink policy is the only place where the Convert Audit Record to XML Assertion can be used.
  • Unlike normal policies, which require a valid XML request message (which may have a blank message body, but HTTP headers are present), the audit sink policy can work with a "blank" request—that is, a request that is initially completely uninitialized. You can use the Convert Audit Record to XML Assertion to populate the sink policy's request with some XML.
  • An audit sink policy can access a large number of auditing-specific context variables that are not available elsewhere in the system. See Audit Sink Context Variables for details.
  • The properties for an audit sink policy cannot be modified.
  • Similar to the audit lookup policy, there is no request XML coming into the policy.

Aside from the above exceptions, the audit sink policy is configured and edited in similar fashion to an ordinary policy. Multiple policy revisions can be created and you can export or import the audit sink policy.

Understanding the Audit Sink Default Policy

When the audit sink is enabled, it can be configured as a custom audit sink or an external JDBC audit sink. Each produces a default policy that you can use as a starting point in your customization.

Custom Audit Sink Policy

The following policy is created when a custom audit sink is selected:

This default policy is for illustrative purposes only and must be configured. If used in its unmodified form, it is designed to always fail, reverting auditing back to the Gateway database.

Excluding the comments, the default policy contains these three assertions:

  • Convert Audit Record to XML Assertion (disabled): This assertion takes the incoming audit records and converts them into an XML request, to mimic a standard incoming request in a service policy. This assertion is disabled by default. 

    Tip: This assertion is technically not necessary in an audit sink policy. If you only need to retrieve a few specific values from the audit event, leave the assertion disabled and use an audit context variable instead.

  • Route via HTTP(S) Assertion (disabled): This assertion routes the request (that is, audit record) to a specific endpoint. This assertion is disabled by default. Enable it to perform an HTTP routing or use another routing assertion. You might also choose replace this routing assertion with other policy logic instead.
  • Stop Processing Assertion: This assertion causes the sample policy to fail and revert to auditing to the internal database. Be sure to delete this assertion once you have finished customizing the audit sink policy.

External JDBC Audit Sink Policy

The following policy is created when an external JDBC audit sink is selected:

Add your policy logic by inserting assertions at the end. Do not modify the auto-generated section at the top.

Failure of the Audit Sink Policy

When the audit sink policy fails, the audit system (by default) falls back to auditing to the internal database. You can disable this by setting the cluster property audit.sink.fallbackToInternal to "false". If fallback is disabled and the audit sink policy cannot be completed, the system logs an error discards the audit record.

Tip: As in a standard policy, an audit sink policy can have multiple branches to take some failover action in a backup branch should the primary branch fail. This way, you can avoid failing the entire audit sink policy because (for example) one particular sink endpoint is down.

Context Variables in an Audit Sink Policy

The audit sink policy uses special context variables that only work within these sink policies. For details, see Audit Sink Context Variables.

General purpose auditing-related context variables are described in Audit Context Variables.

Deleting the Audit Sink Policy

When the audit sink policy is no longer required, delete it by right-clicking it in the Services and Policies list and selecting Delete Policy.

Tip: If you delete the audit sink policy, it is recreated the next time the audit sink is enabled.

Troubleshooting an Audit Sink Policy

Detecting and correcting problems in an audit sink policy require slightly different techniques from troubleshooting normal policies, since auditing is disabled while an audit sink policy is being evaluated. The following tips might help:

Was this helpful?

Please log in to post comments.