Configuring and Using the WebLogic Diagnostic Framework

WLDF Query Language

 

The WebLogic Diagnostic Framework (WLDF) includes a query language for constructing watch rule expressions, Data Accessor query expressions, and log filter expressions. The syntax is a small and simplified subset of SQL syntax.

The language is described in the following sections:

• Components of a Query Expression
• Supported Operators
• Operator Precedence
• Supported Literals
• Creating Watch Rule Expressions
• Creating Data Accessor Queries
• Creating Log Filter Expressions
• Building Complex Expressions

 

---

Components of a Query Expression

A query expression may include any of the following:

• Operators. (See Supported Operators.)
• Literals. (See Supported Literals.)
• Variables. The supported variables differ for each type of expression. (See About Variables in Expressions.)

The query language is case-sensitive.

 

---

Supported Operators

The query language supports the operators listed in Table A-1.

 

---

Operator Precedence

The following list shows the levels of precedence among operators, from the highest precedence to the lowest. Operators listed on the same line have equivalent precedence:

( )
NOT
=, !=, <, >, <=, >=, LIKE. MATCHES,IN
AND
OR

 

---

Supported Literals

Literals can be numeric or string types.

Numeric Literals

Rules for numeric literals are as follows:

• Numeric literals can be integers or floating point numbers.
• Numeric literals are specified the same as in Java. Some examples of numeric literals are 2, 2.0, 12.856f, 2.1934E-4, 123456L and 2.0D.

String Literals

Rules for string literals are as follows:

• String literals must be enclosed in single quotes.
• A percent character (%) can be used as a wildcard inside string literals.
• A backslash character (\) can be used to escape special characters, such as a quote (`) or a percent character (%).
• For watch rule expressions, you can use comparison operators to specify threshold values for String, Integer, Long, Double, Boolean literals.
• The relational operators do a lexical comparison for Strings. For more information, see the documentation for the java.lang.String.compareTo(String str) method.

 

---

About Variables in Expressions

Variables represent the dynamic portion of a query expression that is evaluated at runtime. You must use variables that are appropriate for the type of expression you are constructing, as documented in the following sections:

• Creating Watch Rule Expressions
• Creating Data Accessor Queries
• Creating Log Filter Expressions

 

---

Creating Watch Rule Expressions

You can create watches based on log events, instrumentation events, and harvested attributes. The variables supported for creating the expressions are different for each type of watch, as described in the following sections:

• Creating Log Event Watch Rule Expressions
• Creating Instrumentation Event Watch Rule Expressions
• Creating Harvester Watch Rule Expressions

For complete documentation about configuring and using WLDF watches, see:

• Configuring Watches and Notifications
• Configuring Watches

Creating Log Event Watch Rule Expressions

A log event watch rule expression is based upon the attributes of a log message from the server log.

Variable names for log message attributes are listed and explained in Table A-2:

An example log event watch rule expression is:

  (SEVERITY = 'WARNING') AND (MSGID = 'BEA-320012')

Creating Instrumentation Event Watch Rule Expressions

An instrumentation event watch rule expression is based upon attributes of a data record created by a diagnostic monitor action.

Variable names for instrumentation data record attributes are listed and explained in Table A-3:

An example instrumentation event data rule expression is:

  (USERID = 'weblogic')

Creating Harvester Watch Rule Expressions

A harvester watch rule expression is based upon one or more harvested MBean attributes. The expression can specify an MBean type, an instance, and/or an attribute.

The syntax for constructing a Harvester watch rule expression is as follows:

• To specify an attribute of all instances of a type, use the following syntax:

      ${[type_name]//attribute_name}

• To specify an attribute of an instance of a type, use the following syntax:

      ${com.bea:Name=instance_name//attribute_name}

• To specify an attribute of an instance of a custom MBean type, use the following syntax:

      ${domain_name:Name=instance_name//attribute_name}

The expression must include the complete MBean object name, as shown in the following example:

${com.bea:Name=HarvesterRuntime,Location=myserver,Type=HarvesterRuntime,
      ServerRuntime=myserver//TotalSamplingCycles} > 10

 

---

Creating Data Accessor Queries

Use the WLDF query language with the Data Accessor component to retrieve data from data stores, including server logs, HTTP logs, and harvested metrics. The variables used to build a Data Accessor query are based on the column names in the data store from which you want to extract data.

A Data Accessor query contains the following:

• The logical name of a data store, as described in Data Store Logical Names.
• Optionally, the name(s) of one or more columns from which to retrieve data, as described in Data Store Column Names.

When there is a match, all columns of matching rows are returned.

Data Store Logical Names

The logical name for a data store must be unique. It denotes a specific data store available on the server. The logical name consists of a log type keyword followed by zero or more identifiers separated by the forward-slash (/) delimiter. For example, the logical name of the server log data store is simply ServerLog. However, other log types may require additional identifiers, as shown in Table A-4.

Data Store Column Names

The column names included in a query are resolved for each row of data. A row is added to the result set only if it satisfies the query conditions for all specified columns. A query that omits column names returns all the entries in the log.

All column names from all WebLogic Server log types are listed in Table A-5.

An example of a Data Accessor query is:

SUBSYSTEM = 'Deployer' AND MESSAGE LIKE '%Failed%'

The following example shows an API method invocation. It includes a query for harvested attributes of the JDBC connection pool named MyPool, within an interval between a timeStampFrom (inclusive) and a timeStampTo (exclusive):

  WLDFDataAccessRuntimeMBean.retrieveDataRecords(timeStampFrom, 
    timeStampTo, "TYPE='JDBCConnectionPoolRuntime'  AND NAME='MyPool'")

For complete documentation about the WLDF Data Accessor, see Accessing Diagnostic Data Using the Data Accessor.

 

---

Creating Log Filter Expressions

The query language can be used to filter what is written to the server log. The variables used to construct a log filter expression represent the columns in the log:

• CONTEXTID
• DATE
• MACHINE
• MESSAGE
• MSGID
• RECORDID
• SEVERITY
• SUBSYSTEM
• SERVER
• THREAD
• TIMESTAMP
• TXID
• USERID

Note: These are the same variables that are used to build a Data Accessor query for retrieving historical diagnostic data from existing server logs.

For complete documentation about the WebLogic Server logging services, see Filtering WebLogic Server Log Messages in Configuring Log Files and Filtering Log Messages.

 

---

Building Complex Expressions

You can build complex query expressions using sub-expressions containing variables, binary comparisons, and other complex sub-expressions. There is no limit on levels of nesting. The following rules apply:

• Nest queries by surrounding sub-expressions within parentheses, for example:

  (Severity = 'Warning') AND (Id = 'BEA-320012')

• Enclose a variable name within ${} if it includes special characters, as in an MBean object name. For example:

${mydomain:Name=myserver,
      Type=ServerRuntime//SocketsOpenedTotalCount} >= 1

Notice that the object name and the attribute name are separated by '//' in the watch variable name.

Contact BEA |  Feedback |  Privacy  |