WLDF allows for the use of wildcards in instance names within the <harvested-instance> element, and also provides drill-down and wildcard capabilities in the attribute specification of the <harvested-attribute> element.
WLDF also allows the same wildcard capabilities for instance names in Harvester watch rules, as well as specifying complex attributes in Harvester watch rules.
These capabilities are discussed in the following sections:
When specifying instance names within the <harvested-instance> element, you can:
express the instance name in non-canonical form, allowing you to specify the property list of the ObjectName out of order
express the ObjectName as a JMX ObjectName query pattern without concern as to the order of the property list.
use zero or more '*' wildcards in any of the values in the property list of an ObjectName, such as Name=*.
use zero or more '*' wildcards to replace any character sequence in a canonical ObjectName string. In this case, you must ensure that any properties of the ObjectName that are not wildcarded are in canonical form.
The instance specification in Example C-1 indicates that all instances of the WorkManagerRuntimeMBean are to be harvested. This is equivalent to not providing an instance-name qualification at all in the <harvested-type> declaration.
Example C-1 Harvesting All Instances of an MBean
<harvested-type>
<name>weblogic.management.runtime.WorkManagerRuntimeMBean</name>
<harvested-instance>*<harvested-instance>
<known-type>true</known-type>
<harvested-attribute>PendingRequests</harvested-attribute>
</harvested-type>
The example in Example C-2 shows a JMX ObjectName pattern as the <harvested-instance> value:
Example C-2 Using a JMX ObjectName Pattern
<harvested-type>
<name>com.acme.CustomMBean</name>
<harvested-instance>adomain:Type=MyType,*</harvested-instance>
<known-type>false</known-type>
</harvested-type>
In the example shown in Example C-3, some of the values in the ObjectName property list contain wildcards:
Example C-3 Using Wildcards in the Property List
<harvested-type>
<name>com.acme.CustomMBean</name>
<harvested-instance>adomain:Type=My*,Name=*,*</harvested-instance>
<known-type>false</known-type>
</harvested-type>
The example in Example C-4 indicates that all harvestable attributes of all instances of com.acme.CustomMBean are to be harvested, but only where the instance name contains the string "Name=mybean".
The Harvester provides the ability to access metric values nested within complex attributes of an MBean. A complex attribute can be a map or list object, a simple POJO, or different nestings of these types of objects. For example:
anObject.anAttribute
arrayAttribute[1]
mapAttribute(akey)
aList[1](aKey)
In addition, wildcards can be used for list indexes and map keys to specify multiple elements within a collection of those types. The following wildcards are available:
You can use '*' to specify all key values for Map attributes.
You can use '%' to replace parts of a Map key string and identify a group of keys that match a particular pattern.
You can also specify a discrete set of key values by using a comma-separated list.
For example:
aList[1](partial%Key%)
aList[*](key1,key3,keyN)
aList[*](*)
In the last example, where the '*' wildcard is used for the index to a list and as the key value to a nested map object, nested arrays of values are returned.
If you embed the '*' wildcard in a comma-separated list of map keys, such as:
aList[*](key1,*,keyN)
it is equivalent to specifying all map keys:
aList[*](*)
Note:
Leading or trailing spaces will be stripped from a map key unless the map key is enclosed within quotation marks.Using a map key pattern can result in a large number of elements being scanned and/or returned. The larger the number of elements in a map, the bigger the impact there will be on performance.
The more complex the matching pattern is, the more processing time will be required.
To use drill-down syntax to harvest the nested State property of the HealthState attribute on the ServerRuntime MBean, you would use the following diagnostic descriptor:
Example C-5 Using drill-down syntax
<harvester> <sample-period>10000</sample-period> <harvested-type> <name>weblogic.management.runtime.ServerRuntimeMBean</name> <harvested-attribute>HealthState.State</harvested-attribute> </harvested-type> </harvester>
To harvest the elements of an array or list, the Harvester supports a subscript notation wherein a value is referred to by its index position in the array or list. For example, to refer to the first element in the array attribute URLPatterns in the ServletRuntimeMBean, specify URLPatterns[0]. If you want to reference all the elements of URLPatterns using a wildcard:
Example C-6 Using a wildcard to reference all elements of an array
<harvester> <sample-period>10000</sample-period> <harvested-type> <name>weblogic.management.runtime.ServletRuntimeMBean</name> <harvested-attribute>URLPatterns[*]</harvested-attribute> </harvested-type> </harvester>
To harvest the elements of a map, each individual value is referenced by the key enclosed in parentheses. Multiple keys can be specified as a comma-delimited list, in which case the values corresponding to specified keys in the map will be harvested.
The following code example harvests the value from the map with key Foo:
<harvested-attribute>MyMap(Foo)</harvested-attribute>
The next example harvests the value from the map with keys Foo and Bar:
<harvested-attribute>MyMap(Foo,Bar)</harvested-attribute>
The next example uses the % character with a key specification to harvest all values from the map if their keys start with Foo and end with Bar:
<harvested-attribute>MyMap(Foo%Bar)</harvested-attribute>
The next example harvests all values from a map by using the * character:
<harvested-attribute>MyMap(*)</harvested-attribute>
In the next example, the MBean has a JavaBean attribute MyBean which has a nested map type attribute MyMap. This code example harvests this value from the map whose key is Foo:
<harvested-attribute>MyBeanMyMap(Foo)</harvested-attribute>
While a large number of complex or nested attributes can be specified as a single expression in terms of the Harvester and Watch and Notifications configuration, the actual metrics are persisted in terms of each individually gathered metric.
For example, if the attribute specification:
mymap(*).(a,b,c)
maps to the following actual nested attributes:
mymap(key1).a mymap(key1).b mymap(key1).c mymap(key2).a mymap(key2).b mymap(key2).c
then each of these six metrics are stored in a separate record in the HarvestedDataArchive, with the shown attribute names stored in the ATTRNAME column in each corresponding record. The values in the ATTRNAME column are the values you must use in Accessor queries when retrieving them from the archive.
Here are some example query strings:
NAME="foo:Name=MyMBean" ATTRNAME="mymap(key1).a" NAME="foo"Name=MyBean" ATTRNAME LIKE "mymap(%).a" NAME="fooName=MyMBean" ATTRNAME MATCHES "mymap\((.*?)\).a"
Within Harvester watch rules, you can use the '*' wildcard to specify portions of an ObjectName, giving you the ability to watch for multiple instances of multiple types.
For example, to specify the OpenSocketsCurrentCount attribute for all instances of the ServerRuntimeMBean that begin with the name managed, use the following syntax:
${com.bea:*Name=managed*Type=ServerRuntime*//OpenSocketCurrentCount}
Alternatively, you can use JMX ObjectName query patterns, as shown here:
${mydomain:Key1=MyMBean,*//simpleAttribute}
Note:
The ObjectName query pattern syntax supported by the Harvester will be whatever is supported by the underlying JMX implementation. The above example demonstrates syntax supported by JDK 5 and later. Refer to the JavaDoc for javax.management.ObjectName for the specific JDK version being used to run the server for the full syntax that is supported.You can specify complex attributes (a collection, an array type or an Object with nested intrinsic attribute types) within Harvester watch rule expressions. There are several ways to do this.
The following example shows a drill-down into a nested attribute in a complex type, which is then checked to see if it is greater than 0:
${somedomain:name=MyMbean//complexAttribute.nestedAttribute} > 0
You can also use wildcards to specify multiple Map keys. The following wildcards are available for specifying complex attributes:
You can use '*' to specify all key values for Map attributes.
You can use '%' to replace parts of a Map key string and identify a group of keys that match a particular pattern.
In addition, you can use a comma-separated list to specify a discrete set of key values.
In this example:
${[com.bea.foo.BarClass]//aList[*].(some%partialKey%).(aValue,bValue)} > 0
the rule would examine all elements of the aList attribute on all instances of the com.bea.foo.BarClass, drilling down into a nested map for all keys starting with the text some and containing the text partialKey afterwards. The returned values are assumed to be Map instances, from which values for the keys aValue and bValue will be compared to see if they are greater than 0.
When using the MethodInvocationStatistics attribute on the WLDFInstrumentationRuntime type, the system needs to determine the type from the variable. If the system can't determine the type when validating the attribute expression, the expression won't work. For example, the expression:
${ com.bea:Name=myScope, * //MethodInvocationStatistics.(...).(...)
will not work. You must explicitly declare the type in this situation, as shown in this code example, which drills down into the nested map structure:
$(com.bea:Name=hello,Type=WLDFInstrumentationRuntime,*//MethodInvocationStatistics(*)(*)(*)(count)) >= 1