47 Reporting

This chapter describes the Oracle Service Bus (OSB) reporting framework, including the default JMS reporting provider and the reporting module in the OSB Administration Console.

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 Administration 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 Administration 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 the following sections:

47.1 About the Oracle Service Bus Reporting Framework

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 47.4, "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_ORACLE_HOME/lib/sb-schemas.jar.

Figure 47-1 shows the reporting framework.

Figure 47-1 Reporting Framework

Description of Figure 47-1 follows
Description of "Figure 47-1 Reporting Framework"

As shown in the Figure 47-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.

47.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 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 47.6, "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 47-2.

Figure 47-2 JMS Reporting Provider

Description of Figure 47-2 follows
Description of "Figure 47-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.

47.2.1 Reporting Actions in Global Transactions

The JMS reporting provider uses a default queue connection factory that allows proxy service 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 Console by choosing Services > Messaging > JMS Modules > jmsResources, selecting the Transactions tab, and deselecting the XA Connection Factory Enabled option.

Following is the logic that a proxy service 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.

47.3 How to Configure a Database for the JMS Reporting Provider Store

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/technetwork/middleware/ias/downloads/fusion-certification-100350.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 47.6, "How to Untarget a JMS Reporting Provider."

47.3.1 Configure the Reporting Data Source for Transactions

Make sure the JMS reporting provider 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:

47.3.2 How to Configure a Database in a Development Environment

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 Installation Guide. 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.

47.3.3 How to Configure a Database for Production

For complete information about configuring a database for production, see the Oracle Fusion Middleware Deployment Guide for Oracle Service Bus in the following chapters:

47.4 How to Enable Message Reporting

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 39, "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 47-3.

Figure 47-3 Key Name and Value

Description of Figure 47-3 follows
Description of "Figure 47-3 Key Name and Value"

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 47-4.

Figure 47-4 Keys and Associated Values Display

Description of Figure 47-4 follows
Description of "Figure 47-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 Administration Console:

47.5 How to Stop a Reporting Provider

If you wish to stop a reporting provider when the server is running in the Oracle Service Bus domain, do the following:

  1. Start the Oracle WebLogic Server Administration Console.

  2. After logging into the Oracle WebLogic Server Administration Console, in the Domain Structure, click Deployments. The Summary of Deployments page is displayed.

  3. In the Deployments table, select the check box next to the reporting provider you wish to stop.

  4. Click Stop and after the list is displayed, choose the appropriate command.

  5. After the Stop Application Assistant page is displayed, click Yes. The Deployments table shows that the state of the reporting provider is now Prepared.

47.6 How to Untarget a JMS Reporting Provider

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. The reporting provider is the only Oracle Service Bus module that persists data in a database.

If you disable the reporting provider in the development environment, you can safely suppress Apache Derby database startup when you start the domain with the following command:

startWebLogic.cmd(.sh) noderby

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.

47.6.1 How to Untarget the Default JMS Reporting Provider Before Domain Creation

To untarget the default JMS Reporting Provider in the Oracle Fusion Middleware Configuration Wizard before a domain is created:

  1. In the Configuration Wizard, select optional configurations for Deployments and Services and JMS File Store.

  2. In the related wizard pages that follow, for each server, deselect the "JMS Reporting Provider" application and the "wlsbjmsrpDataSource" JDBC system resource.

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

47.6.2 How to Untarget the JMS Reporting Provider when the Server is Running

To untarget a reporting provider when an Oracle Service Bus domain is running, do the following:

  1. Start the Oracle WebLogic Server Administration Console and log in.

  2. From the left panel, under Domain Structure, click Deployments. The Summary of Deployments page is displayed.

  3. In the Deployments table, click the reporting provider you wish to untarget. The Settings page for the Reporting Provider is displayed.

  4. Click the Targets tab.

  5. Clear the appropriate check box.

  6. Click Save. A message is displayed indicating that the settings have been successfully updated.

  7. 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.

    1. In the left panel, under Domain Structure, select Services > JDBC > Data Sources.

    2. 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.

    3. Click the Targets tab.

    4. Clear the appropriate check box.

    5. Click Save. A message is displayed indicating that the settings have been successfully updated.

    6. To activate the changes, in the Change Center, click Activate Changes.

47.6.3 How to Untarget the JMS Reporting Provider When the Server in Not Running

If the Oracle Service Bus domain is not running, 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:

  1. 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.

  2. Invoke WLST Offline.

    C:>java com.bea.plateng.domain.script.jython.WLST_offline
    
  3. To read the domain that was created using the Configuration Wizard execute:

    wls:/offline>readDomain("C:/oracle/user_projects/domains/base_domain")
    
  4. To untarget the reporting provider data source execute:

    wls:/offline/base_domain>unassign("JdbcSystemResource", "wlsbjmsrpDataSource", "Target", "AdminServer")
    
  5. To the reporting provider application execute:

    wls:/offline/base_domain>unassign("AppDeployment", "JMS Reporting Provider", "Target", "AdminServer")
    
  6. To update the domain execute:

    wls:/offline/base_domain>updateDomain()
    
  7. To close the domain execute:

    wls:/offline/base_domain>closeDomain()
    
  8. 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 Administration 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 Administration Console displays a message that the reporting provider is unavailable.

47.7 Using the Reporting Module in the Oracle Service Bus Administration Console

The reporting module in the Oracle Service Bus Administration 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 47.3, "How to Configure a Database for the JMS Reporting Provider Store."

For more information about the reporting module, see Chapter 28, "Reporting."

47.7.1 Viewing the Summary of Message Reports

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.

Figure 47-5 Summary of Messages

Description of Figure 47-5 follows
Description of "Figure 47-5 Summary of Messages"

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 47-1 describes the information in the Summary of Message Reports.

Table 47-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 47.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 24, "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 28.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.

47.7.2 Viewing Message Details

The View Message Details page displays complete information about the report messages.

Table 47-2 through Table 47-7 describe the information displayed in Report Message Detail Page.

Table 47-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:

  • REQUEST: indicates that the reporting action was executed in a request pipeline.

  • RESPONSE: indicates that the reporting action was executed in a response pipeline.

  • ERROR: the action was running in the service-level error handler.

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 47-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 20.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 47-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 19.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 47-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 47.2, "About the JMS Reporting Provider."


Table 47-6 Fault Message Information

Message Information Description

Error Code

The code associated with the error, if any. For more information, see Chapter 24, "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 47-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 22.27, "Adding Report Actions" and Section 23.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.

47.7.3 How to Purge Messages from the Reporting Data Store

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 Administration Console. This feature enables you to work with the Summary of Messages page in the Oracle Service Bus Administration 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 Administration 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.