CA API Gateway 9.1

9.4 9.1

Working with the Audit Sink Policy

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. 
gateway92
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.
Contents:
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:
Audit_Sink_Sample_Policy_JDBC.png
The following characteristics are unique to the audit sink policy:
  • Only one audit sink policy is created per
    API Gateway
     cluster.
  • Disabling the audit sink does not remove the audit sink policy—it simply redirects audit messages to the
    API Gateway
     database.
    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, you configure and edit audit sink policies in a similar fashion to an ordinary policy. This includes creating multiple policy revisions exporting or importing 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:
Audit_Sink_Sample_Policy.png
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
API Gateway
 database.
Excluding the comments, the default policy contains these three assertions:
  • Convert Audit Record to XML
    : This assertion takes the incoming audit records and converts them into an XML request, to mimic a standard incoming request in a service policy. To learn more about this assertion, see Convert Audit Record to XML Assertion.
    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, use a context variable.
  • Route via HTTP
    : This assertion routes the request (that is, audit record) to a specific endpoint. Edit this assertion as necessary or replace it with another routing assertion. Alternatively, replace this routing assertion with other policy logic. This assertion is disabled by default. To learn more about this assertion, see Route via HTTP(S) Assertion.
  • Stop Processing
    : 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. To learn more about this assertion, see Stop Processing Assertion .
External JDBC Audit Sink Policy
The following policy is created when a JDBC audit sink is selected:
Audit_Sink_Sample_Policy_JDBC.png
Add your policy logic by inserting assertions at the end. Do not modify the auto-generated section at the top.
For best practices, you should write information to queuing system from the Gateway. You can use either the Route via JMS Assertion or the Route via MQ Native Assertion. This allows the audit information to be gathered and sent outside of normal policy execution. This prevents the overhead of auditing from affecting policy execution, which helps overall performance.
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.
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
.
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:
 

Content feedback and comments