About Message Auditing

The CA API Gateway generates three types of audit messages:
gateway83
The
Layer7 API Gateway
generates three types of audit messages:
  • System audits
    , which you cannot control
  • Administrative audits
    , which you can control using the cluster property
    audit.adminThreshold
  • Policy message audits
    , which allows you a high degree of control
The following sections describe each audit type in detail.
System Audits
These are internal messages that are constantly generated in the background by the Gateway. These messages typically describe "housekeeping" tasks such as: server starting , license updated, connecting to a JMS endpoint, etc.
System audit events are normally rated
Fine, Finer,
or
Finest
in the severity scale, although some may be rated
Info
. System audit events are always available in the audit event log (you will need to set the filter slider to "All" to see all these events).
You have no control over system audits: they happen automatically, without requiring any assertions.
Administrative Audits
These are messages that occur when an administrative action is performed via the Policy Manager , via an administrative API, or through the Enterprise Service Manager. Examples of such actions include: publishing or updating a policy, creating a user, etc.
You can control which of these messages you want to save by using the
audit.adminThreshold
cluster property. By default, all messages at level
Info
or higher are logged.
Policy Message Audits
These are messages generated during the processing of a policy. The bulk of these are simply informational messages that have the severity level
Info
. The more important messages are rated
Warning
or
Severe
. By default, the Gateway is set to save only
Warning
or
Severe
messages;
Info
messages are eventually discarded. This behavior is by design, to prevent your audit log from being cluttered with a mass of informational messages. In most instances, you are only interested in knowing when something goes wrong.
There are several cluster properties that can be used by advanced users to more precisely control policy message audits during the auditing process. Of particular importance are the following two properties:
audit.messageThreshold
audit.detailThreshold
The values of these properties, plus the levels selected in the Audit Messages in Policy and Add Audit Detail assertions, will determine whether a message is logged and at what level.
Additional resources:
  • To learn more about the auditing cluster properties, see Audit Cluster Properties. To learn about the interaction between the threshold cluster properties and the auditing-related assertions, see the table below.
  • To learn how to use context variables to extract a wide variety of details from an audit event, see Working with the Audit Sink Policy.
Expanding the Scope of Policy Message Audits for Troubleshooting
If you are troubleshooting an elusive problem or if you want to see all the informational messages, add an Audit Messages in Policy assertion in the policy and set its "trigger" severity level to
Warning
. What this does is elevate all informational messages to a
Warning
severity level as they pass through the assertion. In other words:
"Info" messages become --> "Warning" messages
"Warning" messages remain --> "Warning" messages
"Severe" messages remain --> "Severe" messages
This results in everything being recorded to the audit event log, as all messages now meet the preset threshold of
Warning
. This is illustrated in the following diagram:
INFO_to_WARNING_auditlevel
INFO_to_WARNING_auditlevel
A message is elevated only if an Audit Messages in Policy assertion is present
and
the level in that assertion is set to
Warning
. Without elevation, only the more important messages are saved to the audit events log. The Audit Messages in Policy assertion can only boost a level or leave it unchanged. Subsequent invocations of this assertion in a policy cannot
lower
a severity level. See the table below for a summary of the interactions between cluster properties and auditing assertions.
Incoming Message Type
"Audit Messages in Policy Assertion" in policy
Cluster-wide properties
Result
audit.message Thres hold
audit.detailThreshold
Audit 'Message' @ 'INFO'
'Info' or not present
'WARNING'
'INFO'
Not Logged
'INFO'
'INFO'
Logged at 'INFO' level
'WARNING'
'WARNING'
'INFO'
Logged at 'WARNING'
Audit 'Detail' @ 'INFO'
'Info' or not present
'WARNING'
'INFO'
Logged at 'INFO' level [see 1]
'WARNING'
'WARNING'
Not Logged
'WARNING'
'WARNING'
'INFO'
Logged at 'WARNING'
Audit 'Message' @ 'WARNING'
'Info' or not present
'WARNING'
'INFO'
Logged at 'WARNING'
'INFO'
'INFO'
'WARNING'
'WARNING'
'INFO'
Audit 'Detail' @ 'WARNING'
'Info' or not present
'WARNING'
'INFO'
Logged at 'WARNING'
'WARNING'
'WARNING'
'WARNING'
'WARNING'
'INFO'
[1] The audit detail message is not logged to the database if the policy includes an Add Audit Detail Assertion with properties: Category =
Audit
, Level =
INFO
.