Using the WLS Harvester and Console Extension with SOA Suite 11g
By Shawnbailey-Oracle on Mar 12, 2013
- Installing the Console Extension
- Configuring the Collected Metrics
- Viewing the Metrics in the Console Extension
- Exporting the Metrics
OverviewThere are occassions when we want to see how metrics trend over a period of time and we want to control which metrics they are and for how long the data is collected. The combination of the WLDF (WebLogic Diagnostic Framework) Harvester and the WebLogic Console Extension offer us the capability and the purpose of this blog post is to describe the components and walk through a configuration all the way to data export.
What is the Harvester?
The Harvester is a component of WLDF that will collect a specified metric or set of metrics at a designated interval. You configure the collection through the WLS Console and when complete the collection is done during runtime in the background and the results are persisted to the file system (by default) in binary format. From here they can be exported at any time to an XML file as described in the section 'Exporting the Metrics'.
What is the WLS Console Extension?
The Console Extension is an add-on to the WLS Console that is package with the WLS installation. After installation it is accessible from the Console itself and its purpose is to provide real time reporting on monitored system metrics, including those that are manually configured in WLDF. Below we'll see how to configure a view and what the display of the data looks like.
Installing the Console ExtensionAs mentioned, the Console Extension is included with the default WebLogic Server installation. We're going to copy the jar from the installation location to the domain:
- Find the file 'diagnostics-console-extension.jar' in 'WL_HOME\server\lib\console-ext'
- Copy the file to 'DOMAIN_HOME/console-ext'
- Restart the Admin Server
Now, it's a bit strange but when you click on the tab it will display a page that instructs you to enter the following URL in your browser: 'http://<host>:<port>/console/dashboard'. Here we simply open a new tab in the browser and enter the URL. The landing page looks like this:
By default you can expand the 'Built-in Views' on the left and select one. We select 'JVM Runtime Heap' and then click on the green 'Start' icon to start displaying collected metrics on the heap. After a few minutes our page looks like this:
You can see at the bottom of the chart that we're tracking 2 metrics, 'Heap Size Current' and 'Heap Free Current'. The sampling and display periods are configurable and we'll see below how to create our own chart. To stop the monitor simply click the 'Stop' icon at the top left and if you have more than one monitoring session you can click the icon for 'Stop All'.
Configuring the Collected Metrics
- Login to the WebLogic Console ('http://<host>:<port>')
- In the left menu expand 'Diagnostics'
- Select 'Diagnostic Modules'
- Select the Diagnostic Module which is 'Module-FMWDFW' by default
- Select the 'Collected Metrics' tab which brings you here:
First notice that you can set the sampling period on this page. The period affects both the configured Collected Metrics modules as well as any configured WLDF Watches which can be seen under the 'Watches and Notifications' tab. Here we want to create a new 'Collected Metrics' module so select the 'New' button. Takes you to this screen:
Accept the default value 'ServerRuntime' and click 'Next' for this screen:
Here we're going to select the runtime mbean that we're interest in monitoring. For this example I've chosen 'soainfra_message_processing' which you can find by simply scrolling down the list. Click 'Next' and you land here:
This screen shows the available attributes on the mbean that we can monitor. The attributes are cropped in the selection list but we'll see the full names by mousing over them. Here we're going to select 'requestProcessingTime_avg', 'requestProcessingTime_maxTime' and 'requestProcessingTime_minTime'. It should look like this:
Click 'Next' for the following screen:
Here we will have multiple selections for the actual mbean instances we want to monitor. Again they are cropped in the selection list but a mouseover reveals the full names. We select the one that contains 'bpel.type=soainfra_message_processing' as follows:
Click 'Finish' and you're done. You end up back at the landing page for 'Collected Metrics' and you now have an 'enabled' module that is ready for activation.
Here you just click 'Activate Changes' and you're collecting metrics.
Viewing the Collected MetricsSteps:
- Go to the WLDF Console landing page and make sure that the 'View List' tab is selected
- On the left select 'My Views' so that it is highlighted
- We're now going to create a new view so just click on the 'New View' icon (page with a plus sign) above 'Built-in Views'
- Fill in the name of the view below 'My Views'
You can see that there is only a chart title on the right. Now click on the 'Metric Browser' tab at the top where we'll populate the table. The page will start off with a lot of entries on the left but we'll be filtering them.
We need to make some selections on the left:
- Servers: Select the relevant server that you want to collect the metrics from. Here we have a single server domain
- Select 'Collected Metrics Only'
NOTE: If you are doing this on a SOA server that has NOT processed any composite instances since the last restart you may not see your Collected Metrics module appear. Simply run an instance of the composite to completion and try again. The reason for this is b/c the underlying DMS metric upon which it is based is not created until the first composite instance completes.
There is an arrow just to the right of the chart name. Click it and select 'New Chart'. We now get a blank chart. From here we can simply drag the three attributes from the bottom left into the chart area and they will be added to the right pane at the bottom. The chart should now look like this:
We're ready to start collecting some metrics. Click the green 'Start' icon and apply some load to the composite. In my case I modulate the wait time of the BPEL process and end up with a chart that looks like this:
The beginning of the chart shows data points packed together all at the same level. This is from the background data collection that we configured in 'Collected Metrics' and there was no variable load.
Exporting the MetricsMonitoring the data in the WLDF Console is great but there may be a need to export the data such that it can be manipulated. In order to do this we need to use WLST.
The metrics are stored in a binary file by default and this file is kept in 'DOMAIN_HOME/servers/<server>/data/store/diagnostics'. The file will have a name like 'WLS_DIAGNOSTICS0000000.DAT'. We need this for the WLST command.
- To use this particular command the server needs to be stopped. The reason for this is because the running server has a continuous lock on the DAT file while running
- Start WLST from 'FMw_HOME'/oracle_common/common/bin/wlst.sh'
- Command: exportDiagnosticData(logicalName="HarvestedDataArchive",exportFileName="<Path>/Harvester.xml", storeDir="<MW_HOME>/user_projects/domains/soasingle/servers/AdminServer/data/store/diagnostics")
- The data is exported in XML format to the specified location
- logicalName: These are predefined values and in this case we need to use 'HarvestedDataArchive'. This persistence mechanism is used for other things so there are 2 additional options that we won't cover.
- exportFileName: File you want the data exported to
- storeDir: The location of the DAT file you want to export. WLS does offer customization of this location but that is beyond the scope of this post
NOTE: The DAT file is cummulative so if you start a Collected Metrics module, delete it and start a new one then the information will be appended to the same DAT file. To start with a clean DAT file you'll need to stop the server and delete the existing one first or use your own tooling to filter the entries of interest from the combined XML.