Oracle Service Bus delivers message data and alerts to one or more reporting providers. Message data can be captured from the body of the message and from other variables associated with the message, such as header or inbound variables. Alert data contains information about Service Level Agreement (SLA) violations that you can configure to monitor proxy services. You can use the message or alert data delivered to the reporting provider for functions such as tracking messages or regulatory auditing.
Oracle Service Bus includes a JMS reporting provider for message reporting. The Reporting module in the Oracle Service Bus Console displays the information captured from this reporting provider. If you do not wish to use the JMS Reporting Provider that is provided with your Oracle Service Bus installation, 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 the Oracle Service Bus Console. You must to create your own user interface. To capture SLA data, you must to create a reporting provider for alerts.
This chapter contains information about following topics
Section 45.1, "About the Oracle Service Bus Reporting Framework"
Section 45.6, "Using the Reporting Module in the Oracle Service Bus Console"
Oracle Service Bus contains an extensible framework for creating one or more reporting providers for messages or alerts.
To enable message reporting you must first create a Report action in the message flow for the proxy service. The Report action allows you to extract information from each message and write it to the Oracle 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 Section 45.3, "How to Enable Message Reporting."
Information you need for creating your own reporting provider is located in com.bea.wli.reporting
in the Oracle Fusion Middleware 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_HOME
/lib/sb-schemas.jar
.
Figure 45-1 shows the reporting framework.
As shown in the Figure 45-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 the 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.
The ReportingDataHandler interface takes the reporting or alert data stream and processes it. 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 of Oracle Service Bus run time 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 to:
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 proxy service message flow. The default JMS Reporting Provider is automatically configured when you create an Oracle 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 Oracle Service Bus JMS Reporting Provider, you should untarget the reporting provider and its corresponding data source in your domain, as described in Section 45.5, "How to Untarget 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 45-2.
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 Oracle Service Bus installation, or your reporting provider, you must first create a Report action in the message flow for the proxy service. The Report action allows you to extract information from each message and write it to the Oracle Service Bus Reporting Data Stream. In the Report action, you must specify the information you want to extract from the message and add to the Oracle Service Bus Reporting 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. For more information about message variables, see Chapter 37, "Message Context."
You can use any XML elements as a key:
<?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>
For example, you can specify the key as the itemcode, the value as .//item-code
(an XPath expression), and the variable as message body (body), as shown in Figure 45-3.
If you are using the default JMS Reporting Provider, the keys and associated values are displayed in the Report Index column of the Summary of Messages 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, as shown in Figure 45-4.
Figure 45-4 Keys and Associated Values Display
For information about creating a Report action or on how to view the Summary of Messages page, see the following in Using the Oracle Service Bus Console:
If you wish to stop a reporting provider when the server is running in the Oracle Service Bus domain, do the following:
Start the Oracle WebLogic Server Administration Console.
After logging into the Oracle WebLogic Server Administration Console, in the Domain Structure, click Deployments. The Summary of Deployments page is displayed.
In the Deployments table, select the check box next to the reporting provider you wish to stop.
Click Stop and after the list is displayed, choose the appropriate command.
After the Stop Application Assistant page is displayed, click Yes. The Deployments table shows that the state of the reporting provider is now Prepared.
If you do not want to use the default Oracle Service Bus JMS Reporting Provider (or a custom reporting provider), you should untarget it in your domain.
When you create an Oracle Service Bus domain, the Configuration Wizard, by default, includes the JMS Reporting Provider 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 and potentially speeds server startup, since no corresponding database startup is required.
This section provides different options for untargeting a reporting provider.
Note:
If no reporting provider exists, you can still define a Report action. However, no data is be written.To untarget the default JMS Reporting Provider in the Oracle Fusion Middleware Configuration Wizard before a domain is created:
In the Configuration Wizard, select optional configurations for Deployments and Services and JMS File Store.
In the related wizard pages that follow, deselect "JMS Reporting Provider" and "wlsbjmsrpDataSource."
When the wizard creates the domain, neither resource is targeted at server startup.
To untarget a reporting provider when the server is running in the Oracle Service Bus domain, do the following:
Start the Oracle WebLogic Server Administration Console and log in.
From the left panel, under Domain Structure, click Deployments. The Summary of Deployments page is displayed.
In the Deployments table, click the reporting provider you wish to untarget. The Settings page for the Reporting Provider is displayed.
Click the Targets tab.
Clear the appropriate check box.
Click Save. A message is displayed indicating 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 use their own data sources. 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 > JDBC > Data Sources.
In the Summary of JDBC Data Source page, click the name of the data source you wish to untarget. The Settings page for the data source is displayed.
Click the Targets tab.
Clear the appropriate check box.
Click Save. A message is displayed indicating that the settings have been successfully updated.
To activate the changes, in the Change Center, click Activate Changes.
If the server is not running in the Oracle Service Bus domain, you can use the WebLogic Scripting Tool (WLST) to remove the JMS Reporting Provider from the Oracle Service Bus domain. For more information about WLST, see Oracle Fusion Middleware Oracle WebLogic Scripting Tool.
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 Oracle Fusion Middleware Oracle 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()
After the Oracle Service Bus JMS reporting provider is untargeted, the Reporting module in the Oracle Service Bus Console indicates that the reporting provider is not deployed.
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 Oracle Service Bus Console displays a message that the reporting provider is unavailable.The reporting module in the Oracle Service Bus Console displays the information collected by the JMS Reporting Provider Data Store. The first page of the Reporting module, called the Summary of Messages, displays 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 customize the display of information on this page by filtering and sorting the data. You can also drill down to view detailed information about specific messages, including error information.
The Reporting module provides a purge function to help you manage your message data. You can purge all of the messages from the reporting datastore or base the purge on a time-range.
The JMS Reporting Provider Data Store requires a database. An evaluation version of the Apache Derby database is installed with Oracle WebLogic Server. You can use Derby for a development environment but not for production. Oracle Service Bus also supports databases from other vendors. Be sure to apply standard database administration practices to the database hosting the JMS Reporting Provider Data Store. For more information, see Section 45.6.4, "How to Configure a Database for the JMS Reporting Provider Store."
For more information about the reporting module, see Chapter 27, "Reporting."
When you click Message Reports in the Reporting module of the Operations navigation bar, the Summary of Messages page is displayed. This page contains a table that provides a list of report messages sorted by the database timestamp.
If the messages are not filtered, the Summary of Messages table displays up to 100 of the latest messages based on the database timestamp. If you filter the messages, up to 1000 messages are displayed.
Note:
The filter is not reset automatically. The filter remains in effect until you update it or reset it.Table 45-1 describes the information in the Summary of Message Reports.
Table 45-1 Summary of Message Reports
Column Name | Description |
---|---|
Report Index |
Displays the key-value pairs extracted from the message context variables or the message payload. For more information, see Section 45.2, "About the JMS Reporting Provider." |
DB TimeStamp |
Displays the time when the message was written to the database. |
Inbound Service |
Displays the inbound service associated with the message. Click the name of the service to go to View a Proxy Service page. |
Error Code |
Displays the error code associated with this message, if it exists. For more information about error codes, see Chapter 23, "Proxy Services: Error Handlers." |
To search for specific messages, click Filter in the Summary of Messages Table to filter the display of messages.
You can filter report messages for a specified period of time, by the name of a service, by error code, and by report index. After you filter the messages, the title of the page changes to Summary of Filtered Messages. For information about using the Summary of Messages filter, see Section 27.1, "Viewing Reporting Messages."
To view more information about a report message, click the name of the message in the Report Index column. The View Message Details page is displayed.
The View Message Details page displays complete information about the report messages.
Table 45-2 through Table 45-7 describe the information displayed in Report Message Detail Page.
Table 45-2 General Configuration Message Information
Message Information | Description |
---|---|
Message ID |
An unique identifier for this message. |
Database Timestamp |
The time when the message was written to the database. |
Time at point of Logging |
The date and time, on the server machine, that the message was reported. |
Server name |
The name of the server from which this message was generated. |
State |
The state of the pipeline from which this message was generated. The pipeline can be in one of the following states:
|
Node Name |
The pipeline node from which this message was generated. |
Pipeline Name |
The pipeline from which this message was generated. |
Stage Name |
The stage from which this message was generated. |
Table 45-3 Inbound Service Message Information
Message Information | Description |
---|---|
Name |
The inbound proxy service associated with this message. An inbound proxy service exchanges messages with client applications. The name is a link to the View a Proxy Service page. For more information about this page, see Section 19.5.1, "View a Proxy Service - Configuration Details Page.". |
URI |
The URI associated with the proxy service. |
Operation |
The inbound operation associated with this message. Operations are the tasks performed by a pipeline or route node in the message flow associated with the service. |
Table 45-4 Outbound Service Message Information
Message Information | Description |
---|---|
Name |
The outbound business service associated with this message. An outbound business service exchanges messages with an Oracle Service Bus proxy service. Click on the link to go to View Business Service Details page. For more information about this page, see Section 18.5.1, "View a Business Service - Configuration Details Page." |
URI |
The URI to the outbound business service end point. |
Operation |
The name of the operation invoked on the outbound service. Operations are the tasks performed by a pipeline or route node in the message flow associated with the service. |
Table 45-5 Report Index Message Information
Message Information | Description |
---|---|
Report Text Index |
Displays the key-value pairs extracted by a Report Action from the message context variables or the message payload. For more information, see Section 45.2, "About the JMS Reporting Provider." |
Table 45-6 Fault Message Information
Message Information | Description |
---|---|
Error Code |
The code associated with the error, if any. For more information, see Chapter 23, "Proxy Services: Error Handlers." |
Reason |
The reason the error occurred, if any. |
Detail |
The fault details associated with the error. These details, if present, are typically a stack trace of where a particular fault occurred. The stack trace may be truncated due to a size limitation in the database. The limit is 2048 characters. |
Table 45-7 Report Body Message Information
Message Information | Description |
---|---|
Detail |
Opens a new browser window that displays the report body in a browser. You can use an XQuery expression in a Report action to capture the report body text. For more information, see Section 21.27, "Adding Report Actions" and Section 22.1, "Creating and Editing Inline XQuery and XPath Expressions." |
Detail opens a browser window that displays the report body in a browser. You can use an XQuery expression in a Report Action to capture the report body text.
You can purge all of the messages from the reporting datastore or base the purge on a range of time. Message purging is an asynchronous process that occurs in the Oracle Service Bus Console. This feature enables you to work with the Summary of Messages page in the Oracle Service Bus Console while the purge occurs in the background.
The duration of time 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 Summary of Messages page may display incorrect data as some data may not yet be purged.
Because the purge process is asynchronous and occurs in the background, the Oracle Service Bus Console does not display any messages to indicate that a purge is in process. However, if another user attempts to start a purge when a purge is in progress, the following message is displayed:
A Purge job is already running. Please try later.
Oracle Service Bus requires a database for the JMS Reporting Provider Data Store. The Apache Derby 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/technology/software/products/ias/files/fusion_certification.html
Note:
If you do not want to use the default Oracle Service Bus JMS Reporting Provider and hence do not configure a database, you should untarget the reporting provider and its corresponding data source in your domain, as described in Section 45.5, "How to Untarget a JMS Reporting Provider."Make sure the JMS reporting provider data source supports transactions in one of the following ways:
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 Oracle Fusion Middleware Configuring and Managing JDBC for Oracle WebLogic Server.
When you create an Oracle Service Bus domain, the Configuration Wizard does not create database tables automatically. In a development environment, the default JMS Reporting Provider checks whether tables exist for the specified database at run time. If tables do not exist, the Reporting Provider creates them; if they do exist, the Reporting Provider uses them.
You can specify which database is used by the JMS Reporting Provider in one of the following ways:
Run the reporting SQL scripts in your Oracle Service Bus domain. The scripts are located in OSB_ORACLE_HOME/dbscripts.
When you create a domain in the Configuration Wizard, customize the JDBC settings on the reporting provider. For more information, see "Installing and Configuring Oracle Service Bus" in the Oracle Fusion Middleware Installation Guide for Oracle Service Bus. If you are using Apache Derby in your development environment, the default database with Oracle WebLogic Server, you need not specify a database in the Configuration Wizard.