Configuring and Using the WebLogic Diagnostic Framework

Configuring the Harvester for Metric Collection

The Harvester component of the WebLogic Diagnostic Framework (WLDF) gathers metrics from attributes on qualified MBeans that are instantiated in a running server. The Harvester can collect metrics from BEA WebLogic Server® MBeans and from custom MBeans.

This section includes:

About Harvesting, Harvestable Data, and Harvested Data

Harvesting metrics describes the process of gathering data that is useful for monitoring system state and measuring system performance. Metrics are exposed to WLDF as attributes on qualified MBeans. The harvester gathers values from selected MBean attributes at a specified sampling rate. Therefore, you can track potentially fluctuating values over time.

Data must meet certain requirements in order to be harvestable, and it must meet further requirements in order to be harvested:

Harvestable data is data that can potentially be harvested from harvestable entities, including MBean types, instances, and attributes. To be harvestable, an MBean must be registered in the local WebLogic Server runtime MBean server.
Harvested data is data that is currently being harvested. To be harvested, the data must meet all the following criteria:

The data must be harvestable.
The data must be configured to be harvested.
For custom MBeans, the MBean must have been discovered.
The data must not throw exceptions while being harvested.

The WLDFHarvesterRuntimeMBean provides the set of harvestable data and harvested data. The information returned by this MBean is a snapshot of a potentially changing state. For a description of the information about the data provided by the this MBean, see the description of the weblogic.management.runtime.WLDFHarvesterRuntimeMBean in the WebLogic Server MBean Reference.

You can use the Administration Console, the WebLogic Scripting Tool (weblogic.WLST), or JMX to configure the harvester to collect, analyze, and archive the metrics that the server MBeans and the custom MBeans contain.

Harvesting Data from the Different Harvestable Entities

You can configure the Harvester to gather data from named MBean types, instances, and attributes. In all cases, the Harvester collects the values of attributes of MBean instances, as explained in Table 5-1.

Table 5-1 Sources of Harvested Data from Different Configurations

When this entity is configured to be harvested...	Data is collected from...
A type	All attributes in all instances of the specified type
An attribute of a type	The specified attribute in all instances of the specified type
An instance of a type	All attributes in the specified instance of the specified type
An attribute of an instance of a type	The specified attribute in the specified instance of the specified type

All WebLogic Server runtime MBean types and attributes are known at startup. Therefore, when the harvester configuration is loaded, the set of harvestable WebLogic Server entities is the same as the set of WebLogic Server runtime MBean types and attributes. As types are instantiated, those instances also become harvestable.

The set of harvestable custom MBean types is dynamic. A custom MBean must be instantiated before its type can be known. (The type does not exist until at least one instance is created.) Therefore, as custom MBeans are registered with and removed from the MBean server, the set of custom harvestable types grows and shrinks. This process of detecting a new type based on the registration of a new MBean is called type discovery.

When you configure the harvester through the Administration Console, the Console provides a list of harvestable entities that can be configured. The list is always complete for WebLogic Server MBeans, but it must be discovered dynamically for custom MBeans.

Configuring the Harvester

The Harvester is configured and metrics are collected in the scope of a diagnostic module targeted to one or more server instances.

Listing 5-1 shows Harvester configuration elements in a WLDF system resource descriptor file, myWLDF.xml. This sample configuration harvests from the ServerRuntimeMBean, the WLDFHarvesterRuntimeMBean, and from a custom (non-WLS) MBean. The text following the listing explains each of the elements in the listing.

Listing 5-1 Sample Harvester Configuration

<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<name>myWLDF</name>

  <harvester>

    <enabled>true</enabled>

    <sample-period>5000</sample-period>

    <harvested-type>
      <name>weblogic.management.runtime.ServerRuntimeMBean</name>
    </harvested-type>

    <harvested-type>
      <name>weblogic.management.runtime.WLDFHarvesterRuntimeMBean</name>
        <harvested-attribute>TotalSamplingTime</harvested-attribute>
        <harvested-attribute>CurrentSnapshotElapsedTime
        </harvested-attribute>
    </harvested-type>

    <harvested-type>
      <name>myMBeans.MySimpleStandard</name>
      <harvested-instance>myCustomDomain:Name=myCustomMBean1
      </harvested-instance>
      <harvested-instance>myCustomDomain:Name=myCustomMBean2
      </harvested-instance>
    </harvested-type>

  </harvester>

<!-- ----- Other elements ----- -->

</wldf-resource>

Configuring the Harvester Sampling Period

The <sample-period> element sets the sample period for the Harvester, in milliseconds. For example:

<sample-period>5000</sample-period>

The sample period specifies the time between each cycle. For example, if the Harvester begins execution at time T, and the sample period is I, then the next harvest cycle begins at T+I. If a cycle takes A seconds to complete and if A exceeds I, then the next cycle begins at T+A.

Configuring the Types of Data to Harvest

You configure the types of data to harvest in one or more <harvested-type> elements. Each <harvested-type> element specifies an MBean type from which metrics are to be collected. Optional sub-elements specify the instances and/or attributes to be collected for that type. Set these options as follows:

The optional <harvested-instance> element specifies that metrics are to be collected only from the listed instances of the specified type. In general, an instance is specified by providing its JMX ObjectName in JMX canonical form.
If no <harvested-instance> is present, all instances that are present at the time of each harvest cycle are collected.
The optional <harvested-attribute> element specifies that metrics are to be collected only for the listed attributes of the specified type. An attribute is specified by providing its name. The first character should be capitalized. For example, an attribute defined with getter method getFoo() is named Foo.
If no <harvested-attribute> is present, all attributes defined for the type are collected.

Specifying Type Names for WebLogic Server MBeans vs. Custom MBeans

The Harvester supports WebLogic Server MBeans and custom MBeans. WebLogic Server MBeans are those which come packaged as part of the WebLogic Server. Custom MBeans can be harvested as long as they are registered in the local runtime MBean server.

There is a small difference in how WebLogic Server and customer types are specified. For WebLogic Server types, the type name is the name of the Java interface which defines that MBean. For example, the server runtime MBean's type name is weblogic.management.runtime.ServerRuntimeMBean. For custom MBeans, the type name is the name of the implementing class (for example, see Listing 5-1).

When Configuration Settings are Validated

WLDF attempts to validate configuration as soon as possible. Most configuration is validated at system startup and whenever a dynamic change is committed. However, due to limitations in JMX, custom MBeans cannot be validated until instances of those MBeans have been registered in the MBean server.

Example Configurations for Different Harvestable Types

Listing 5-2 shows a <harvested-type> element that specifies that the ServerRuntimeMBean is to be harvested. Because no <harvested-instance> sub-element is present, all instances of the type will be collected. However, since there is always only one instance of the server runtime MBean, there is no need to provide a specific list of instances. And because there are no <harvested-attribute> sub-elements present, all available attributes of the MBean are harvested.

Listing 5-2 Example Configuration for Collecting All Instances and All Attributes of a Type

    <harvested-type>
      <name>weblogic.management.runtime.ServerRuntimeMBean</name>
    </harvested-type>

Listing 5-3 shows a <harvested-type> element that specifies that the WLDFHarvesterRuntimeMBean is to be harvested. As above, because there is only one WLDFHarvesterRuntimeMBean, there is no need to provide a specific list of instances. The sub-element <harvested-attribute> specifies that only two of the available attributes of the WLDFHarvesterRuntimeMBean will be harvested: TotalSamplingTime and CurrentSnapshotElapsedTime.

Listing 5-3 Example Configuration for Collecting Specified Attributes of All Instances of a Type

    <harvested-type>
      <name>weblogic.management.runtime.WLDFHarvesterRuntimeMBean</name>
        <harvested-attribute>TotalSamplingTime</harvested-attribute>
        <harvested-attribute>CurrentSnapshotElapsedTime
        </harvested-attribute>
    </harvested-type>

Listing 5-4 shows a <harvested-type> element that specifies that a single instance of a custom MBean type is to be harvested. Because this is a custom MBean, the name is the implementation class. In this example, the two <harvested-instance> elements specify that only two instances of this type will be harvested. Each instance is specified using the canonical representation of its JMX ObjectName. Since no instances of<harvested-attribute> are specified, all attributes will be harvested.

Listing 5-4 Example Configuration for Collecting Specified Attributes of a Specified Instance of a Type

    <harvested-type>
      <name>myMBeans.MySimpleStandard</name>
      <harvested-instance>myCustomDomain:Name=myCustomMBean1
      </harvested-instance>
      <harvested-instance>myCustomDomain:Name=myCustomMBean2
      </harvested-instance>
    </harvested-type>