Configuring Reporting for Messages and Alerts

13.1 Introduction to the Service Bus Reporting Framework

Service Bus includes an extensible framework for creating one or more reporting providers for messages or alerts. You can configure pipelines to generate message and alert reports that can then be exported to reporting streams.

Message data can be captured from the message $body and other variables associated with the message, such as the $header or $inbound variables. Alert data contains information about Service Level Agreement (SLA) violations that you can configure to monitor pipelines. You can use the message or alert data delivered to the reporting provider for functions such as tracking messages or regulatory auditing.

13.1.1 Message Report Configuration

To enable message reporting you must first create a report action in a pipeline. The Report action allows you to extract information from each message and write it to the Service Bus Reporting Data Stream. You do not need to configure a report action for alert reporting. Alert data is always available in the Reporting Data Stream. For more information, see About the Pipeline Report Action.

13.1.2 Default Reporting Provider

For message reporting, Service Bus includes a JMS reporting provider. The Message Reports page in Fusion Middleware Control displays the information captured from this reporting provider. If you do not wish to use the provided JMS reporting provider, you can untarget it and create your own reporting provider using the Reporting Service Provider Interface (SPI). If you configure your own reporting provider for messages, no information is displayed in Fusion Middleware Control. You must to create your own user interface. To capture SLA alert data, you must create a reporting provider for alerts.

13.1.3 Custom Report Providers

Information you need for creating your own reporting provider is located in com.bea.wli.reporting in the Java API Reference for Oracle Service Bus. The Java API Reference provides information about what you need to do for implementing a reporting provider, including how to package it, where it goes, how to deploy it, and the order of deployment. The reporting schema is MessageReporting.xsd, located in OSB_ORACLE_HOME/lib/sb-schemas.jar.

13.1.4 Reporting Workflow

As shown in the Figure 13-1, both report messages and alerts are exported to reporting data streams. In the Report stage, information is extracted by the Report action from each message and written to the reporting data stream with metadata that adheres to MessageReporting.xsd.

Similarly, the SLA Manager uses Reporting Data Manager APIs to write to the alert reporting stream with metadata that adheres to AlertReporting.xsd. To develop a reporting provider for alerts or your own message reporting provider, you need to implement ReportingDataHandler interface and use the ReportingDataManager class.

Figure 13-1 Reporting Framework

Description of "Figure 13-1 Reporting Framework"

The ReportingDataHandler interface processes the reporting or alert data stream. It can either process or store a stream, or do both in a relational database, file, JMS queue, and so on. Depending on which stream you want to use, you need to implement the appropriate handle methods to process the data stream:

Message Reporting Stream: The Report action in the runtime uses the following two handle methods to write to the message reporting stream:
```
handle(com.bea.xml.XmlObject metadata, String s)
handle(com.bea.xml.XmlObject metadata, com.bea.xml.XmlObject data)
```
Alert Reporting Stream: The Alert Manager uses the following handle method to write to the alert reporting stream:
```
handle(com.bea.xml.XmlObject metadata, String data)
```

The ReportingDataManager is a local server object that keeps a registry of reporting providers. Reporting providers implement the ReportingDataHandler interface. The ReportingDataManager provides operations do perform the following:

Add and remove reporting data handlers.
Export reporting data stream using various handle operations.

13.2 About the JMS Reporting Provider

The JMS Reporting Provider provides a pluggable architecture to capture the reporting information from each message using a Report action in a pipeline.

The default JMS Reporting Provider is automatically configured when you create a Service Bus domain. All messages across the cluster are aggregated and stored in a JMS Reporting Provider data store in a database specific format. This provider displays information from the JMS Reporting Provider data store.

Note:

If you do not want to use the default Service Bus JMS Reporting Provider, untarget the reporting provider and its corresponding data source in your domain, as described in Untargeting a JMS Reporting Provider.

The JMS Reporting Provider consists of a producer and a consumer, which are decoupled to improve scalability. The producer is a JMS producer and the Message Driven Bean (MDB) acts as the JMS consumer, as shown in Figure 13-2.

Figure 13-2 JMS Reporting Provider

Description of "Figure 13-2 JMS Reporting Provider"

The Reporting stage contains the Report actions that collect the reporting information and dispatch the reporting stream to the JMS Reporting Provider through various handle operations in the ReportingDataManager. The JMSReportingDataHandler is the JMS producer of the reporting provider. The JMSReportingDataHandler takes the reporting stream and logs the information to a JMS queue. The MDB listens to the JMS reporting queue, which processes the message asynchronously, and stores the data in the JMS Reporting Provider data store.

While the JMS Reporting Provider processes reports generated by a Report action, it ignores reports generated due to SLA and pipeline alerts. When writing a custom reporting provider, however, you are not restricted to that behavior. Depending on your business requirements you may want to process all or a subset of reporting data delivered by the reporting framework to your custom reporting provider.

13.2.1 About the Pipeline Report Action

To receive report messages from either the JMS Reporting Provider, which is provided with the Service Bus installation, or your custom reporting provider, you must first create a Report action in the pipelines on which you want to report. The Report action allows you to extract information from each message and write it to the Service Bus reporting data stream. In the Report action, specify the information you want to extract from the message and add to the data stream.

When configuring a Report action, use key values to extract key identifiers from the message; you can configure multiple keys. Information can be captured not only from the body of the message but any other variable associated with the message, such as header or inbound variables.

You can use any XML elements as a key. For example, using the following message structure, you might use the item-code element as a way to extract the identifier:

<?xml version="1.0" encoding="utf-8"?>
<poIncoming>
    <areacode>408</areacode>
    <item-quantity>100</item-quantity>
    <item-code>ABC</item-code>
    <item-description>Medicine</item-description>
</poIncoming>

Figure 13-3 shows a key value defined with a name of ItemCode and a value of .//item-code (an XPath expression). The value of the key comes from the item-code element in the message body (body variable).

Figure 13-3 Key Name and Value in the Oracle Service Bus Console

Description of "Figure 13-3 Key Name and Value in the Oracle Service Bus Console"

When you use the default JMS Reporting Provider, the keys and associated values are displayed in the Report Index column of the Message Reports table. If you configure multiple keys, the key-value pairs are displayed in the Report Index column with each key-value separated by a comma.

For information about creating a Report action, see "Adding Report Actions" in Developing Services with Oracle Service Bus.

13.2.2 Reporting Actions in Global Transactions

The JMS reporting provider uses a default queue connection factory that allows pipelines to execute reporting actions in the context of global transactions. The connection factory, defined in the jmsResources module, is called wli.reporting.jmsprovider.ConnectionFactory.

If you do not want report actions to execute in the context of a global transaction, modify the connection factory in the Oracle WebLogic Server Administration Console by doing the following:

Select Services > Messaging > JMS Modules > jmsResources.
Select the Transactions tab.
Deselect the XA Connection Factory Enabled option.

Following is the logic that a pipeline uses when handling Report actions using this connection factory:

If a global transaction exists and the connection factory is XA-enabled (the default), the report is generated within the context of that global transaction.
If a global transaction exists and the connection factory is not XA-enabled, the transaction is suspended and the report is generated within a local transaction.
If a global transaction does not exist, the report is generated within a local transaction.

13.3 Configuring a Database for the JMS Reporting Provider Store

Service Bus requires a database for the JMS Reporting Provider data store. The Java DB database that is installed with Oracle WebLogic Server is intended for development only, not for a production environment.

In a production environment you must use one of the supported databases. For the latest information about supported databases, see Supported Databases and Drivers in Oracle Fusion Middleware Supported System Configurations at:

http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

Note:

If you do not want to use the default JMS Reporting Provider and hence do not configure a database, untarget the reporting provider and its corresponding data source in your domain, as described in Untargeting a JMS Reporting Provider.

13.3.1 Configuring the Reporting Data Source for Transactions

A default data source, wlsbjmsrpDataSource, is automatically created for Service Bus installations. If you create a custom JMS reporting provider data source, make sure the data source supports transactions in one of the following ways. Incorrect configuration could result in exceptions.

Configure the data source to use a supported XA driver.
If you use a non-XA driver for the data source, be sure to select the following options in the data source configuration:
- Supports Global Transactions
- Logging Last Resource
  
  For more information about Logging Last Resource (LLR), see "Understanding the Logging Last Resource Transaction Option" in Administering JDBC Data Sources for Oracle WebLogic Server.

13.3.2 Creating a Database for the JMS Reporting Provider Store

In a development environment, the default JMS Reporting Provider checks whether tables exist for the specified database at runtime. If tables do not exist, the Reporting Provider creates them; if they do exist, the Reporting Provider uses them.

Running the Repository Creation Utility (RCU) creates the schema and any required Service Bus database tables, including the tables used by the Reporting Provider. This is part of product installation. For more information, see Creating Database Schemas in Installing and Configuring the Oracle Fusion Middleware Infrastructure.

13.4 Enabling Message Reports

To generate message reports, you need to create a Report action in the pipeline for which you want reports.

This is described in About the Pipeline Report Action. See also Adding Report Actions in the Console in Developing Services with Oracle Service Bus.

You also need to enable the Reporting operational setting both globally and for the pipeline. For instructions on updating operational settings, see the following sections:

13.5 Working With Message Reports

In Fusion Middleware Control, you can view the information collected by the JMS Reporting Provider data store. The Message Reports feature lets you search for specific messages based on the pipeline that generated the report, the error code, report indexes, or a date range.

The search results appear in a table containing the extracted information and other information, such as the time the message was written to the database and the service with which the message is associated. You can drill down to view detailed information about specific messages, including error information.

To manage your message data, use the Purge feature, which lets you purge all of the messages from the reporting datastore or just the messages generated within a certain time period. Be sure to apply standard database administration practices to the database hosting the JMS Reporting Provider data store.

13.5.1 Searching for Message Reports

In order to view message reports, you need to perform a search for the reports. You can leave all search criteria blank to view all available reports, or you can filter report messages for a specified period of time, by the name of a service, by error code, and by report index. For more information about the fields on this page, see the online help for the Message Reports page.

To search for message reports:

In Fusion Middleware Control, do one of the following:
- Click the Service Bus or Service Bus Project menu, and select Message Reports.
- In the Target Navigator, right-click the name of the Service Bus server or any project deployed to the server, and select Message Reports.
Enter any of the following criteria in the search fields, or leave them empty to retrieve all messages:
- Inbound Service Name (the name of the pipeline)
- Error Code
- Report Index (key/value pairs)
You can use an asterisk (*) wildcard character in these fields.
To specify a date range for reports to retrieve, do the following:
1. Select the From radio button.
2. In the From field, enter the starting date for your date range. Select a date using the Select Date and Time icon or enter a date and time in the format Month DD, YYYY HH:MM:SS AM|PM. For example, you can enter Nov 29, 2013 12:45:00 AM.
3. Repeat the above step in the To field to define the ending date for the range.
To retrieve the most recent messages, do the following:
1. Select the For the Last radio button.
2. In the days field, select the number of days previous to today for which you want to retrieve message reports.
3. In the hr:mm fields, select the number of hours and minutes previous to now for which you want to retrieve messages.
Click Search.

A list of message reports matching your criteria appears in the lower portion of the window.

Figure 13-4 Message Reports Window

Description of "Figure 13-4 Message Reports Window"

13.5.2 Viewing Message Report Details

The Message Detail page displays complete information about the selected report message, including the node, pipeline, and stage that generated the report; timestamp; server name; inbound and outbound services; and the associated fault, if any. You can also view the text that was written to the report, which is defined in the Report action in the pipeline.

To view message report details:

In Fusion Middleware Control, perform a search for message reports as described in Searching for Message Reports.
To view a complete report for a message, click the report index for that row in the Message Reports table.

The Message Detail window appears. For information about the fields displayed on this window, see the online help in Fusion Middleware Control.

Figure 13-5 Message Reports Message Detail Window

Description of "Figure 13-5 Message Reports Message Detail Window"
To view the text that was printed to the message report, click View Report Details in the Report section of the page.

The following figure shows the message body in the report.

Figure 13-6 Message Report Data

Description of "Figure 13-6 Message Report Data"

Note:

When you create the Report action in the pipeline, you specify the value to write to the report using an XQuery expression to capture the report body text.
To view the Dashboard for the inbound or outbound service, click the name of the service.
When you are done viewing the Message Details page, you can click Close to return to the Message Reports summary page.

13.5.3 About Purging Message Reports from the Reporting Data Store

You can purge all of the messages from the reporting datastore or just purge reports that were generated during a specific time period. Message purging is an asynchronous process, allowing you to continue working with the Message Reports page while the purge occurs in the background. Fusion Middleware Control does not display a message to indicate that a purge is in process, but if another user attempts to start a purge while a purge is in progress, the following message appears:

A Purge job is already running. Please try later.

The duration it takes a purge to complete depends on how many messages are in the purge queue. The deletion of messages is slowed if you search for reporting messages during the purge process. Moreover, the Message Reports page may display incorrect data as some data may not yet be purged.

13.5.4 Purging Message Reports from the Reporting Data Store

The Purge Messages feature may be useful during design and test phases of your project.

In a production environment, Oracle recommends that the management of the data in your database (including purging) is handled by the Database Administrator using database management tools. Creating a script based on the business requirements is recommended, as running a script directly on the database is much faster. Keep in mind to limit the amount of data for deletion. The following example removes data from the WLI_QS_REPORT_ATTRIBUTE table (and the WLI_QS_REPORT_DATA table through cascade delete):

DELETE FROM WLI_QS_REPORT_ATTRIBUTE WHERE DB_TIMESTAMP BETWEEN TO_DATE(:1 , 
:"SYS_B_0") AND TO_DATE(:2 , :"SYS_B_1") where rownum < 10000

To improve performance, create a combined index for the msg_guid and db_timestamp columns:

create index myIndex on myTable (msg_guid, db_timestamp);

To purge message reports:

In Fusion Middleware Control, perform a search for message reports as described in Searching for Message Reports.
Click Purge.

The Purge Message Reports History dialog appears.
Do one of the following:
- To purge messages for all dates, select All.
- To purge messages for a specific date range, select Purge From and then specify the start and end dates and times using the Select Date and Time icons.
  
  Note:
  
  You can also manually enter a month, day, year, and time in the format MM/DD/YY HH:MM:SS. For example, you can enter 10/10/07 12:45:00 AM.
Click OK.
Read the warning message and then click OK again to proceed.
Click Close.

13.6 Stopping a Reporting Provider

Follow these steps to stop a reporting provider when the Service Bus server is running

Log in to the Oracle WebLogic Server Administration Console.
In the Domain Structure, click Deployments.

The Summary of Deployments page appears.
In the Deployments table, select the check box next to the reporting provider you want to stop.
Click Stop and then select the appropriate stop command.

13.7 Starting a Reporting Provider

Follow these steps to start a reporting provider when the Service Bus server is running.

Log in to the Oracle WebLogic Server Administration Console.
In the Domain Structure, click Deployments.

The Summary of Deployments page appears.
In the Deployments table, select the check box next to the reporting provider you want to start.
Click Start and then select the appropriate start command.

13.8 Untargeting a JMS Reporting Provider

If you do not want to use the default JMS Reporting Provider (or a custom reporting provider), untarget the provider in your domain.

When you create a Service Bus domain, the JMS Reporting Provider is included as a target in the deployment list. Untargeting the default JMS Reporting Provider and its associated data source lets you avoid benign JMS reporting errors at server startup.

Note:

If no reporting provider exists, you can still define a Report action. However, no data is be written.

13.8.1 Untargeting the Default JMS Reporting Provider During Domain Creation

To prevent the default JMS Reporting Provider from being targeted when you create a domain:

On the Advanced Configuration page of the Configuration Wizard, select optional configurations for Deployments and Services and JMS File Store.
When the Deployments Targeting page appears, select Service Bus JMS Reporting Provider in the Targets panel and then click the left arrow to remove it from the Targets list.
When the Services Targeting page appears, select wlsbjmsrpDataSource in the Targets panel and then click the left arrow to remove it from the Targets list.

When the wizard creates the domain, neither resource is targeted at server startup.

13.8.2 Untargeting the JMS Reporting Provider when the Server is Running

To untarget a reporting provider when the Service Bus domain is running:

Start the Oracle WebLogic Server Administration Console and log in.
In the Domain Structure panel, click Deployments.

The Summary of Deployments page appears.
In the Deployments table, click the reporting provider you wish to untarget.

The Settings page for the provider appears.
Click the Targets tab.
Clear the check box for the component to untarget.
Click Save.

A message indicates that the settings have been successfully updated.
After you untarget the reporting provider, untarget the data source used by the reporting provider, as follows:

Note:

This step is only required for reporting providers that do not share a data source with other components. To untarget the default JMS reporting provider in Oracle Service Bus installation you must perform the following steps.
1. In the left panel, under Domain Structure, select Services > Data Sources.
2. In the Summary of JDBC Data Source page, click the name of the data source to untarget.
  
  The Settings page for the data source appears.
3. Click the Targets tab.
4. Clear the check box for the servers from which you want to untarget the data source.
5. Click Save.
  
  A message indicates that the settings have been successfully updated.

13.8.3 Untargeting the JMS Reporting Provider When the Server in Not Running

If the Service Bus domain is not running, you can use the WebLogic Scripting Tool (WLST) to remove the JMS Reporting Provider from the domain.

To untarget a reporting provider, complete the following steps:

If you have not already set up your environment to use WLST, see "Main Steps for Using WLST" in Using the WebLogic Scripting Tool in Understanding the WebLogic Scripting Tool.

Invoke WLST Offline.

C:>java com.bea.plateng.domain.script.jython.WLST_offline

To read the domain that was created using the Configuration Wizard execute:
```
wls:/offline>readDomain("C:/oracle/user_projects/domains/base_domain")
```

To untarget the reporting provider data source execute:

wls:/offline/base_domain>unassign("JdbcSystemResource", "wlsbjmsrpDataSource", "Target", "AdminServer")

To the reporting provider application execute:

wls:/offline/base_domain>unassign("AppDeployment", "JMS Reporting Provider", "Target", "AdminServer")

To update the domain execute:

wls:/offline/base_domain>updateDomain()

To close the domain execute:
```
wls:/offline/base_domain>closeDomain()
```
Exit from the WLST command prompt execute:
```
wls:/offline>exit()
```

Note:

In a cluster, the JMS Reporting Provider is targeted to Cluster. Therefore in a cluster, to view and purge messages, you must configure at least one Managed Server to run with the Administration server. If no Managed Servers are running, the reporting provider is unavailable.

13.9 Using Oracle Advanced Queueing JMS

By default, the JMS Reporting Provider uses WebLogic JMS for its data store. If Service Bus is running in a clustered environment, you can configure the domain to use Oracle AQ JMS instead. This changes the JMS provider for both reporting and for the poller transports.

When you configure the domain to use Oracle AQ, the configuration wizard generates a new JMS system resource, OSBAQJMSServer, which is associated with a foreign JMS server for AQ JMS. The required JMS foreign destinations, foreign connection factory, initial context factory, and datasource are configured for reporting queues and for poller transport queues. The JMS foreign server for AQ JMS is configured to use the JMS reporting datasource wlsbjmsrpDataSource, which is the same datasource used by the default WebLogic JMS.

Note:

Oracle AQ JMS is only supported with Service Bus in a clustered environment using an Oracle database.

The following steps indicate any special steps you need to take when creating the clustered Service Bus domain. For more information about creating the domain, see Configuring Oracle Service Bus Domain in Installing and Configuring Oracle Service Bus.

To configure a clustered domain to use Oracle AQ JMS:

On the Advanced Configuration page of the Configuration Wizard, select optional configurations for Deployments and Services and Managed Servers, Clusters and Coherence.
Configure your administration and managed servers, define the cluster, and assign the servers to the cluster as you normally would.
When the Services Targeting page appears, do the following:
1. In the Targets panel under Cluster/cluster_name/JMS/JMS System Resource, select jmsResources and then click the left arrow to remove it from the Targets list.
2. Select OSBAQJMSServer in the Services panel under JMS System Resource, select the name of the cluster in the Targets panel, and then click the right arrow to add the service to the Targets list.
  
  This targets the service to the cluster.
3. Select OSBAQJMSServer in the Services panel again, select the name of the Admin Server in the Targets panel, and then click the right arrow to add the service to the Targets list.
  
  This targets the service to the Admin Server.
Continue configuring the domain as you normally would.

Once the domain is created, you can view the JMS resource and its associated connection factories and destinations in the JMS Modules pages of the Oracle WebLogic Server Administration Console.