This chapter describes the reporting framework in Oracle Service Bus, including the default JMS reporting provider and the Message Reports module in Fusion Middleware Control.
This chapter contains the following sections:
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
$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.
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.
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.
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
As shown in the Figure 12-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
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
Figure 12-1 Reporting Framework
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)
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.
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.
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 12-2.
Figure 12-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.
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 12-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 (
Figure 12-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.
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
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:
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.
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:
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.
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.
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 the Database Schemas" in Installing and Configuring the Oracle Fusion Middleware Structure.
To generate message reports, you need to create a Report action in the pipeline for which you want reports.
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:
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.
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)
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:
Select the From radio button.
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.
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:
Select the For the Last radio button.
In the days field, select the number of days previous to today for which you want to retrieve message reports.
In the hr:mm fields, select the number of hours and minutes previous to now for which you want to retrieve messages.
A list of message reports matching your criteria appears in the lower portion of the window.
Figure 12-4 Message Reports Window
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:
The Message Detail window appears. For information about the fields displayed on this window, see the online help in Fusion Middleware Control.
Figure 12-5 Message Reports Message Detail Window
The following figure shows the message body in the report.
Figure 12-6 Message Report Data
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.
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.
The Purge Messages feature may be useful during design and test phases of your project. However, 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.
To purge message reports:
The Purge Message Reports History dialog appears.
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.
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.
Follow these steps to stop a reporting provider when the Service Bus server is running
The Summary of Deployments page appears.
Follow these steps to start a reporting provider when the Service Bus server is running.
The Summary of Deployments page appears.
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.
If no reporting provider exists, you can still define a Report action. However, no data is be written.
To prevent the default JMS Reporting Provider from being targeted when you create a domain:
When the wizard creates the domain, neither resource is targeted at server startup.
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.
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:
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.
In the left panel, under Domain Structure, select Services > Data Sources.
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.
Click the Targets tab.
Clear the check box for the servers from which you want to untarget the data source.
A message indicates that the settings have been successfully updated.
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:
wls:/offline/base_domain>unassign("JdbcSystemResource", "wlsbjmsrpDataSource", "Target", "AdminServer")
wls:/offline/base_domain>unassign("AppDeployment", "JMS Reporting Provider", "Target", "AdminServer")
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.
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.
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 Your 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:
In the Targets panel under
/JMS/JMS System Resource, select jmsResources and then click the left arrow to remove it from the Targets list.
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.
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.