E Using Wildcards in Expressions
WLDF also allows the same wildcard capabilities for instance names in Harvester policies, as well as specifying complex attributes in Harvester policies.
This appendix includes the following sections:
- Using Wildcards in Harvester Instance Names
When specifying instance names within the <harvested-instance> element, you have some flexibility with regards to the property list order. - Specifying Complex and Nested Harvester Attributes
The Harvester provides the ability to access metric values nested within complex attributes of an MBean. - Using the Accessor with Harvested Complex or Nested Attributes
While a large number of complex or nested attributes can be specified as a single expression in terms of the Harvester and Policy and Actions configuration, the actual metrics are persisted in terms of each individually gathered metric. - Using Wildcards in Policy Instance Names
Within Harvester policy expressions, you can use the asterisk (*
) wildcard character to specify portions of an ObjectName. This gives you the ability to watch for multiple instances of a type. - Specifying Complex Attributes in Harvester Policies
You can specify complex attributes (a collection, an array type or an Object with nested intrinsic attribute types) within Harvester policy expressions.
Using Wildcards in Harvester Instance Names
-
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 asterisk (
*
) wildcard characters in any of the values in the property list of an ObjectName, such asName=*
. -
Use zero or more asterisk (
*
) wildcard characters to replace any character sequence in a canonical ObjectName string. In this case, you must ensure that any properties of the ObjectName not substituted by a wildcard character are in canonical form.
Parent topic: Using Wildcards in Expressions
Examples
The instance specification in Example E-1 indicates that all instances of the WorkManagerRuntimeMBean are to be harvested. This is equivalent to not providing any instance-name qualification in the <harvested-type> declaration.
Example E-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>
Example E-2 shows a JMX ObjectName pattern as the <harvested-instance> value:
Example E-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 Example E-3, some of the values in the ObjectName property list contain wildcard characters:
Example E-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>
In Example E-4, all harvestable attributes of all instances of com.acme.CustomMBean are to be harvested, but only those in which the instance name contains the string Name=mybean
.
Example E-4 Harvesting All Attributes of Multiple Instances
<harvested-type> <name>coma.acme.CustomMBean</name> <harvested-instance>*Name=mybean*</harvested-instance> <known-type>true</known-type> </harvested-type>
Parent topic: Using Wildcards in Harvester Instance Names
Specifying Complex and Nested Harvester Attributes
-
anObject.anAttribute
-
arrayAttribute[1]
-
mapAttribute(akey)
-
aList[1](aKey)
In addition, wildcard characters can be used for list indexes and map keys to specify multiple elements within a collection of those types. The following wildcard characters are available:
-
You can use the asterisk (
*
) wildcard character to specify all key values for Map attributes. -
You can use the percent (
%
) wildcard character 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,key
N
)
-
aList[*](*)
In the last example, where the asterisk (*
) wildcard character is used for the index to a list and as the key value to a nested map object, nested arrays of values are returned.
Embedding the asterisk (*
) wildcard character in a comma-separated list of map keys is equivalent to specifying all map keys. For example, the following two specifications are equivalent:
-
aList[*](key1,*,key
N
)
-
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, returned, or both. The larger the number of elements in a map, the bigger the impact is on performance.
The more complex the matching pattern is, the more processing time is required.
Parent topic: Using Wildcards in Expressions
Examples
To use drill-down syntax to harvest the nested State property of the HealthState attribute on the ServerRuntime MBean, use the diagnostic descriptor shown in Example E-5.
Example E-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 in which 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]
. Example E-6 shows referencing all elements of URLPatterns
using a wildcard character.
Example E-6 Using a Wildcard Character 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 are harvested, as shown in the following examples.
The following example . . . | . . . shows the following |
---|---|
<harvested-attribute>MyMap(Foo)</harvested-attribute> |
Harvesting the value from the map with key |
<harvested-attribute>MyMap(Foo,Bar)</harvested-attribute> |
Harvesting the value from the map with keys |
<harvested-attribute>MyMap(Foo%Bar)</harvested-attribute> |
Using the percent ( |
<harvested-attribute>MyMap(*)</harvested-attribute> |
Harvesting all values from a map by using the asterisk ( |
<harvested-attribute>MyBeanMyMap(Foo)</harvested-attribute> |
The MBean has a JavaBean attribute |
Parent topic: Specifying Complex and Nested Harvester Attributes
Using the Accessor with Harvested Complex or Nested Attributes
While a large number of complex or nested attributes can be specified as a single expression in terms of the Harvester and Policy and Actions configuration, the actual metrics are persisted in terms of each individually gathered metric.
For example, 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
Each of the preceding 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.
The following are examples of 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"
Parent topic: Using Wildcards in Expressions
Using Wildcards in Policy Instance Names
Within Harvester policy expressions, you can use the asterisk (*
) wildcard character to specify portions of an ObjectName. This gives you the ability to watch for multiple instances of a type.
For example, to specify the OpenSocketsCurrentCount attribute for all instances of the ServerRuntimeMBean that begin with the name managed:
-
The instance-name pattern can be a valid JMX ObjectName pattern, in which case the property list order is not important. For example:
${com.bea:Name=managed*,Type=ServerRuntime,*//OpenSocketCurrentCount}
This example is a valid JMX ObjectName pattern that can match:
-
Any ObjectName that contains a
Name
key with a value that starts withmanaged
-
A
Type
key that exactly matches the valueServerRuntime
-
Any other property pairs
For more examples of valid JMX ObjectName patterns, see the ObjectName API documentation at
http://docs.oracle.com/javase/8/docs/api/javax/management/ObjectName.html
. -
-
If the name is a pattern but is not a JMX ObjectName pattern, WebLogic Server does pattern-matching using the pattern as-is. For example:
${com.bea:*Name=managed*,Type=ServerRuntime,*//OpenSocketCurrentCount}
This example is not a valid JMX ObjectName pattern. This pattern is matched using straight string substitution, where the pattern is matched as-is against the canonical form of the ObjectName for any target MBean instance.
Note:
The ObjectName query pattern syntax supported by the Harvester is determined by whatever is supported by the underlying JMX implementation. The preceding example demonstrates the syntax supported by JDK 5 and later. For information about the full syntax that is supported, see the description of the javax.management.ObjectName
class corresponding to the version of the JDK with which your installation of WebLogic Server is configured.
Parent topic: Using Wildcards in Expressions
Specifying Complex Attributes in Harvester Policies
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 wildcard characters to specify multiple Map keys. The following wildcard characters are available for specifying complex attributes:
-
You can use an asterisk character (
*
) to specify all key values for Map attributes. -
You can use a percent character (
%
) to replace parts of a Map key string and to 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.
For example:
${[com.bea.foo.BarClass]//aList[*].(some%partialKey%).(aValue,bValue)} > 0
The rule in the preceding example examines all elements of the aList
attribute on all instances of 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
are compared to determine 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 cannot determine the type when validating the attribute expression, the expression is not valid. For example, the following expression is not valid:
${ com.bea:Name=myScope, * //MethodInvocationStatistics.(...).(...)
You must explicitly declare the type in this situation, as shown in the following example that shows drilling down into the nested map structure:
$(com.bea:Name=hello,Type=WLDFInstrumentationRuntime,*//MethodInvocationStatistics(*)(*)(*)(count)) >= 1
Parent topic: Using Wildcards in Expressions