Understanding the Oracle Service Bus report action:
One of the most undervalued actions in the Oracle Service Bus is the report action. It’s just a simple not-to-often used action of the reporting palette. This is a shame since it might become a very valuable component for your environments proper auditing/tracing and error handling.
After all tracing messages in a complex middleware environment is critical to solve issues. So eventually you have to think about creating a standard solution for this. Just dumping full $body variables in your Weblogic logging is not gonna make you a very popular developer if you ask the support engineers.
So this blogpost will try to explain how the report action by default works.
Every organization has it’s own requirements regarding logging & tracing, Think about time logging has to be stored, details of the logging, etc etc etc. So for this blogpost we will use an example which might not be consistent with what you have in your environment. However the point is to get you familiar with the Report action so you can decide on your own what to do with it.
So lets start with the assumption that all our Oracle Service Bus proxy services are based upon WSDLs. These WSDLs define both the $body variable (as usual) but also uses a custom MyHeader.xsd in every SOAP header. Sending messages across your Middleware landscape require the service consumers to populate this header. This helps you as Middleware developer/administrator to standardize your middleware landscape.
This is a simple example of a custom header, which will do for our example:
<soapenv:Envelope xmlns:head="http://rubix.nl/schemas/cdm/header" xmlns:soapenv= href="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <head:myHeader> <head:CurrentDateTime>2012-01-15T18:44:29.857Z</head:CurrentDateTime> <head:CorrelationID>067e6162-3b6f-4ae2-a171-2470b63dff00</head:CorrelationID> <head:MessageID>54947df8-0e9e-4471-a2f9-9af509fb5889</head:MessageID> </head:myHeader> </soapenv:Header> ...
So we add a Report action in our Request pipeline of our service.
The expression field holds the part we actually want to trace, in this case our $header/head:myHeader however you could even use binary input here. The Key Name is best used for your reference and let you easily search later on. With the use of a CorrelationID (which is identical through out all service calls in the business process, hence the name CORRELATION ) we are eventually able to query all messages in a process and match them to our expected business process and perform active monitoring.
So let’s move forward and assume the proxy service is executed, what happens then.
Well if you check your Weblogic domain you could see that it holds a JMS Module named jmsResources which contains a Connection Factory and queue for wli reporting.
What the report action does is actually publish a message to a jms queue named wli.reporting.jmsprovider.queue. If you check the queue for messages (you probably need to pause the queues consumption) you will see a java object like this.
This ReportMessage Java object contains a lot of information, as we are going to see later on. By pausing the queue consumption we actually stopped a standard EJB which polls this queue. You can find it under Deployments in your Weblogic domain with the name JMS Reporting Provider.
What this default report provider does is poll the queue and store the report messages in the Weblogic database schema you configured during your domain creation. If we check the database there are 2 tables of interest WLI_QS_REPORT_DATA and WLI_QS_REPORT_ATTRIBUTE.
The WLI_QS_REPORT_DATA table hols a record for each Report action you used. The example below shows 2 recors due to the fact I placed 1 report action in the request pipeline and 1 report action in the error handler (which logged $fault instead of $header but forget about that). A succesfull request will show information regarding pipeline, stage, uri, operation by default. Besided that the column MSG_LABELS will contain our own mapped Key. If you would correlate this key through your landscape you would be able to monitor your process flow through this defaul reporting mechanism.
If we check the WLI_QS_REPORT_ATTRIBUTE table we can see that the MSG_GUID field is the reference between both tables and the DATA_VALUE column will hold our reported expression. In this case the custom header. And yes the screenshot shows a lame ID, I was to lazy to create a new screenshot after using a proper GUID as the example header message above shows.
With the help of a simple queury we can easily match the 2 tables and search for our required correlationID
SELECT wli_qs_report_attribute.msg_labels, wli_qs_report_attribute.state, wli_qs_report_attribute.inbound_operation, wli_qs_report_attribute.stage_name , wli_qs_report_attribute.error_code, wli_qs_report_attribute.error_reason, wli_qs_report_data.data_value FROM wli_qs_report_attribute, wli_qs_report_data WHERE wli_qs_report_attribute.msg_guid = wli_qs_report_data.msg_guid AND wli_qs_report_attribute.msg_labels='CorrelationID=1234567890'
- Pro: 1 action to rule them all, keeps your proxy services very clean
- Con: a fixed database schema design, with limitations for proper relational data storage, usage of a BLOB for most likely XML, only the date is saved and not datetime.
- Possible Con: The Weblogic reporting queue is stored on the same WLS domain
- Instead of using Report you could use your own Publish action and create a custom framework, however you would need to build up the message to publish and keep all services standardized as much as possible.
- However Oracle (BEA) mentions the possibility to create your own ReportProvider, which I try to explain in this blogpost.
- You can also trigger a report on the Alert action
- Oracle mentions that: The concepts of message reports and sensors will be merged moving forward (but this was in 2008 so they take their time).
- blogpost: Using the Oracle Service Bus report action
- blogpost: Oracle Service Bus runtime execution and message tracing
- blogpost: Oracle Service Bus, Create a custom report provider
- Pierluigi @ Java Mon Amour http://www.javamonamour.org/2011/11/osb-custom-reporting-provider.html
- OFMW Administrator’s Guide for OSB – Adding Report Actions
- OFMW Administrator’s Guide for OSB – Reporting