Understanding and configuring composite audit levels

Understanding and configuring composite audit levels

Setting the level of auditing tells the SOA Infrastructure how much information you want logged in order to assist in the monitoring and troubleshooting of instances. For example, if the audit level is completely off, the administrator will have no visibility into any composite instance. No instance data is logged and it is impossible to tell anything at that point (although instances are actually created and requests are serviced just fine). On the other hand, if the audit level is set to development, not only is the instance data logged, but the payload is also logged at every operation, giving the administrator complete visibility into the step-by-step execution of every instance!

Although setting the audit level to development may appear tempting, it has both performance and storage implications. Audit data is stored in the database, and if you have a large number of transactions, the database growth can be huge. One large customer of Oracle SOA Suite 11g has audit data that grows by nearly 10 gigabytes per day, faster than they are able to purge it! The following graphs show that as the payload size increases, the resulting database storage needs drastically increase for development versus production audit levels. For example, for a sampling of 500 messages with an average message size of 400 KB, successful transactions result in 90 MB of storage space needed for development audit levels versus 31 MB for production. For faulted transactions, it's even worse. 488 MB is needed if the development audit level is set versus 190 MB for production.

Not only are there storage concerns, as we have seen, but performance implications are severe. Enabling the development audit level at the SOA Infrastructure can result in approximately a 40 percent hit in composite instance performance!

Audit levels

Although audit levels can be configured in various areas, as we shall describe shortly, they mostly (but not in every case) fall under one of these four levels:

  • Off: Absolutely no composite instance or payload information is collected. Although this is the best in terms of performance, it severely limits the visibility as no information is logged, rendering it an option that is not recommended in most cases. Instances are created, but nothing is logged to the database or displayed on the console, which may lead to difficulties in fault diagnosis and incident analysis.

  • Development: Both composite instance and payload information are collected. Though this option provides the most detail, it is the worst performing of all the audit levels. It is recommended to set this in development environments for debugging purposes, but not in production environments, except for transactions that specifically require that degree of auditing.

  • Production: Although composite instance information is collected, most payload details are not. This is the typical setting for production environments and provides the best balance between performance and visibility. If payload details need to be captured, it is best to consider setting the audit level to development only for specific composites, components, or services, as we shall describe later.

  • Inherit: Audit levels are inherited from the parent level (we will describe this shortly).

To view the instance details, you should click on the composite on the navigator on the left, click on the Instances tab, then click on the instance ID. A pop-up window will reveal the details of this instance, including the audit trails. The following screenshots show the difference between the development and production audit levels:

Audit levels set to development capture payloads throughout most activities, such as Assign and Transform. By expanding the sign in the Assign activity, the payload is displayed. As you can see, the development audit level is advantageous and it allows you to see the changes made to the message across every activity or routing rule, but as discussed earlier, there are both storage and performance implications as a result.

Order of precedence for audit level settings

Before describing the order of precedence for audit level settings and what exactly it is, let's recap on specific terminology first:

  • Component: Examples of components include a BPEL process, a Mediator service, or a BPMN process. Within JDeveloper, these components are the building blocks for composite applications.

  • Composite: A composite consists of zero or more components. For example, a single composite can include a BPEL component and two Mediator components. Composite applications are packaged into a single JAR file that is deployed to the SOA Infrastructure.

  • Service engine: Though we have not described service engines in detail yet, they are the actual engines that run the code. There are three main service engines—BPEL Service Engine, Mediator Service Engine, and BPMN Service Engine. As their names imply, the BPEL Service Engine executes the BPEL code, the Mediator Service Engine executes the Mediator code, and the BPMN Service Engine executes the BPMN code.

  • SOA Infrastructure: The SOA Infrastructure is the underlying infrastructure, which is comprised of the service engines mentioned in the preceding section and to which the composite applications are deployed.

Why have we described these terms? Because audit levels can be manipulated across each of these. It is possible to set the audit level at the component level, the composite level, or even the service engine level. But if the audit level is set at the composite level as development and at the SOA Infrastructure level as production, which one takes precedence?

At a high level, the order of precedence is as follows:

Component > Composite > Service Engine > SOA Infrastructure

What this means is that, for example, if the audit level is set to development at the composite level and production at the SOA Infrastructure level, that the setting at the composite level overrides that of the SOA Infrastructure. If the composite audit level is set to inherit, it will inherit the settings from the applicable service engine. If the service engine is also set to inherit, it will inherit the settings from the SOA Infrastructure. As a general rule, we recommend setting all audit level settings to inherit and controlling it at the SOA Infrastructure level. Then, as the need for different levels of auditing are required, start manipulating the service engine, composite, and component audit levels as needed.

Unfortunately, the rules on what takes precedence are rather complicated as you start changing each of them. If auditing at the service engine is enabled and the composite audit level is set to off, there is no audit trail generated for this composite and its underlying components. Neither the service engine nor SOA Infrastructure audit levels take effect in this case. When the audit level of a composite is set to inherit, depending on what the audit levels of the service engine and the SOA Infrastructure are, either of them may take effect, which is confusing. Detailed examples of order of precedence can be found in the first chapter of the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite 11g Release 1 (11.1.1).

Modifying audit levels

We had previously discussed that audit levels can be set at the component, composite, service engine, and SOA Infrastructure levels. Here, we will describe how to set each of these.

Modifying component audit levels

Component level auditing can only be manipulated for BPEL and BPMN components, but not Mediator components.

For example, developers can modify BPEL component level auditing by inserting the bpel.config.auditLevel property within their component reference in the composite.xml file of their project as shown in the following code snippet:

<component name="HelloWorld">
<implementation.bpel src="HelloWorld.bpel" />
<property name="bpel.config.auditLevel">Off</property>

Modifying composite audit levels

Audit levels can be changed during runtime at the composite level. To do so, perform the following steps:

  1. 1. On the navigator, expand Farm_[Domain] | SOA | soa-infra.

  2. 2. Expand the partition (for example, default) and click on the composite name (for example, HelloWorld).

  3. 3. Click on the Settings button.

  4. 4. Click on the Composite Audit Level menu item.

  5. 5. Choose between one of the four audit levels:

    • Inherit

    • Off

    • Production

    • Development

Modifying service engine audit levels

Both the BPEL Service Engine and BPMN Service Engine have a fifth audit level—minimal. The minimal audit level collects instance information, but not payload details in the flow audit trails.

To set the audit level for the BPEL Service Engine:

  1. 1. Right-click on soa-infra and then navigate to SOA Administration | BPEL Properties.

  2. 2. Set the Audit Level field.

  3. 3. Click on Apply.

To set the audit level for the BPMN Service Engine:

  1. 1. Right-click on soa-infra and then navigate to SOA Administration | BPMN Properties.

  2. 2. Set the Audit Level field.

  3. 3. Click on Apply.

To set the audit level for the Mediator Service Engine:

  1. 1. Right-click on soa-infra and then navigate to SOA Administration | Mediator Properties.

  2. 2. Set the Audit Level field.

  3. 3. Click on Apply.

Modifying SOA Infrastructure Audit Levels

The SOA Infrastructure audit level can be configured by performing the following:

  1. 1. Right-click on soa-infra and then navigate to SOA Administration | Common Properties.

  2. 2. Set the Audit Level field.

  3. 3. Click on Apply.