Skip Headers
Oracle® Fusion Middleware Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24426-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

C Using 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 watch rules, as well as specifying complex attributes in Harvester watch rules.

These capabilities are discussed in the following sections:

Using Wildcards in Harvester Instance Names

When specifying instance names within the <harvested-instance> element, you can:

Examples

The instance specification in Example C-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 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>

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 Example C-3, some of the values in the ObjectName property list contain wildcard characters:

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>

In Example C-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 C-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:

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 also specify a discrete set of key values by using a comma-separated list.

For example:

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:

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

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 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 C-6 shows referencing all elements of URLPatterns using a wildcard character.

Example C-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 Watch and Notifications 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 Watch Rule Instance Names

Within Harvester watch rules, you can use the asterisk (*) wildcard character to specify portions of an ObjectName. This gives 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}

As an alternative, you can use JMX ObjectName query patterns, as in the following example:

${mydomain:Key1=MyMBean,*//simpleAttribute}

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 Watch Rules

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 wildcard characters to specify multiple Map keys. The following wildcard characters are available for specifying complex attributes:

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