The Harvester component of the WebLogic Diagnostics Framework (WLDF) gathers metrics from attributes on qualified MBeans instantiated in a running server. The Harvester can also collect metrics from WebLogic Server MBeans and from custom MBeans.
This chapter includes the following sections about the Harvester and how to configure it:
Harvesting, Harvestable Data, and Harvested Data
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. Only simple type attributes of an MBean can be harvestable.
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 be currently registered with the JMX server.
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 this MBean, see the description of the WLDFHarvesterRuntimeMBean in the Oracle WebLogic Server MBean Reference.
You can use the WebLogic Server Administration Console, the WebLogic Scripting Tool (WLST), or JMX to configure the Harvester to collect and archive the metrics that the server MBeans and the custom MBeans contain.
Harvesting Data from the Different Harvestable Entities
Table 8-1 Sources of Harvested Data from Different Configurations
|When this entity is configured to be harvested as...||Data is collected from...|
A type (only)
All harvestable attributes in all instances of the specified type
An attribute of a type
(type + attribute(s))
The specified attribute in all instances of the specified type
An instance of a type
(type + instance(s))
All harvestable attributes in the specified instance of the specified type
An attribute of an instance of a type
(type + instance(s) + attribute(s))
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 known and thus 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 WebLogic Server Administration Console, the Console provides a list of harvestable entities that can be configured. The list is always complete for WebLogic Server MBeans, but for custom MBeans, the list contains only the currently discovered types. See Configure metrics to collect in a diagnostic system module in the Oracle WebLogic Server Administration Console Online Help.
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. The Harvester configuration includes the sampling period, the type of data to harvest, and the type names for WebLogic Server MBeans and custom MBeans.
Example 8-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 (that is, non-WebLogic Server) MBean. The text following the listing explains each element in the listing.
Example 8-1 Sample Harvester Configuration (in DIAG_MODULE.xml)
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-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:
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. If this occurs, the Harvester tries to start the next cycle sooner, to ensure that the average interval is I.
Configuring the Types of Data to Harvest
One or more <harvested-type> elements determine the types of data to harvest. 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. However, you can use pattern-matching to specify instance names in non-canonical form, as described in Using Wildcards in Harvester Instance Names.
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.
The <harvested-attribute> element also supports an expression syntax for "drilling down" into attributes that are complex or aggregate objects, such as lists, maps, simple POJOs (Plain Old Java Objects), and various nestings of these types. See Specifying Complex and Nested Harvester Attributes, for details on this syntax. However, note that the result of these expressions must be a simple intrinsic type (
String, and so on) in order to be harvested.
If no <harvested-attribute> is present, all harvestable attributes defined for the type are collected.
Attribute and instance lists can be combined in a type.
Specifying Type Names for WebLogic Server MBeans and Custom MBeans
The Harvester supports WebLogic Server MBeans and custom MBeans. WebLogic Server MBeans are those that 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 difference in how WebLogic Server and customer types are specified. For WebLogic Server types, the type name is the name of the Java interface that defines the MBean. For example, the server runtime MBean's type name is weblogic.management.runtime.ServerRuntimeMBean.
For custom MBeans, the Harvester follows these rules:
If the MBean is not a ModelMBean, the type name is the implementing class name. (See Example 8-1.)
If the MBean is a ModelMBean, the type name is the value of the MBean Descriptor field DiagnosticTypeName.
If neither of these conditions is satisfied (if the MBean is a ModelMBean and there is no value for the MBean Descriptor field DiagnosticTypeName) then the MBean cannot be harvested.
Harvesting from the Domain Runtime MBean Server
The <harvested-type> element supports a <namespace> attribute that lets you harvest metrics from MBeans registered in the Domain Runtime MBean Server. However, Oracle recommends that you limit the usage to harvesting only Domain Runtime-specific MBeans, such as the ServerLifeCycleRuntimeMBean. Harvesting of remote managed server MBeans through the Domain Runtime MBean Server is possible, but is discouraged for performance reasons. It is a best practice to use the resident Harvester in each managed server to capture metrics related to that managed server instance.
The <namespace> attribute can have one of two values:
If the <namespace> attribute is omitted, it defaults to ServerRuntime.
Harvesting from the Domain Runtime MBean server is available only on the Administration Server. Attempts to harvest Domain Runtime MBeans on a Managed Server are ignored. See Example 8-5.
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.
Sample Configurations for Different Harvestable Types
In Example 8-2, the <harvested-type> element in the
.xml configuration file specifies that the ServerRuntimeMBean is to be harvested. Because no <harvested-instance> subelement is present, all instances of the type will be collected. However, because 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> subelements present, all available attributes of the MBean are harvested for each of the two instances.
Example 8-2 Sample Configuration for Collecting All Instances and All Attributes of a Type (in DIAG_MODULE.xml)
<harvested-type> <name>weblogic.management.runtime.ServerRuntimeMBean</name> </harvested-type>
In Example 8-3, the <harvested-type> element in the
.xml configuration file 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 subelement <harvested-attribute> specifies that only two of the available attributes of the WLDFHarvesterRuntimeMBean will be harvested: TotalSamplingTime and CurrentSnapshotElapsedTime.
Example 8-3 Sample Configuration for Collecting Specified Attributes of All Instances of a Type (in DIAG_MODULE.xml)
<harvested-type> <name>weblogic.management.runtime.WLDFHarvesterRuntimeMBean</name> <harvested-attribute>TotalSamplingTime</harvested-attribute> <harvested-attribute>CurrentSnapshotElapsedTime </harvested-attribute> </harvested-type>
In Example 8-4, the <harvested-type> element in the
.xml configuration file specifies that a single instance of a custom MBean type is to be harvested. Because this is a custom MBean, the type 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. Because no instances of <harvested-attribute> are specified, all attributes will be harvested.
Example 8-4 Sample Configuration for Collecting All Attributes of a Specified Instance of a Type (in DIAG_MODULE.xml)
<harvested-type> <name>myMBeans.MySimpleStandard</name> <harvested-instance>myCustomDomain:Name=myCustomMBean1 </harvested-instance> <harvested-instance>myCustomDomain:Name=myCustomMBean2 </harvested-instance> </harvested-type>
In Example 8-5, the <harvested-type> element in the
.xml configuration file specifies that the ServerLifeCycleRuntimeMBean is to be harvested. The <namespace> attribute specifies that this is a DomainRuntime MBean, so this configuration will only be honored on the administration server (see the note in Harvesting from the DomainRuntime MBeanServer). The subelement <harvested-attribute> specifies that only the StateVal attribute will be harvested.
Example 8-5 Sample configuration for Collecting Specified Attributes of the ServerLifeCycleMBean Type (in DIAG_MODULE.xml)
<harvested-type> <name>weblogic.management.runtime.ServerLifeCycleRuntimeMBean</name> <namespace>DomainRuntime</namespace> <known-type>true</known-type> <harvested-attribute>StateVal</harvested-attribute> </harvested-type>
Harvester Performance Considerations
When JMS connections are not cached properly, a scenario can develop in which hundreds of connections (and consequently, the corresponding connection, producer, and consumer runtime MBeans) are created and destroyed every second when the system is operating under heavy load. This situation can cause load stress on both the Harvester and the Policies and Actions system.
To avoid this problem, make sure your JMS applications conform to the best coding practices described in Cache and Re-use Client Resources in Tuning Performance of Oracle WebLogic Server. As a result, you will not only obtain better WLDF performance, but you will also improve your JMS and overall server performance.