E Using Wildcards in Expressions

The WebLogic Diagnostics Framework (WLDF) supports the ability to use wildcards in expressions. 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 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. Specifically, 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 asterisk (*) wildcard characters in any of the values in the property list of an ObjectName, such as Name=*.

  • 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.

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>

Specifying Complex and Nested Harvester Attributes

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, 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,keyN)

  • 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,*,keyN)

  • 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.

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 Foo.

<harvested-attribute>MyMap(Foo,Bar)</harvested-attribute>

Harvesting the value from the map with keys Foo and Bar.

<harvested-attribute>MyMap(Foo%Bar)</harvested-attribute>

Using the percent (%) wildcard 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(*)</harvested-attribute>

Harvesting all values from a map by using the asterisk (*) wildcard character.

<harvested-attribute>MyBeanMyMap(Foo)</harvested-attribute>

The MBean has a JavaBean attribute MyBean, which has a nested map type attribute MyMap. This example harvests this value from the map that has the key Foo.

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"

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 with managed

    • A Type key that exactly matches the value ServerRuntime

    • 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.

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. 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 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