A WLDF Query Language

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

• Numeric Relational Operations Supported on String Column Types

• Supported Numeric Constants and String 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:

• Operators. (See Supported Operators.)

• Literals. (See Supported Numeric Constants and String 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.

Table A-1 WLDF Query Language Operators

Operator	Operator Type	Supported Operand Types	Definition
AND	Logical binary	Boolean	Evaluates to true when both expressions are true.
OR	Logical binary	Boolean	Evaluates to true when either expression is true.
NOT	Logical unary	Boolean	Evaluates to true when the expression is not true.
&	Bitwise binary	Numeric, Dye flag	Performs the bitwise AND function on each parallel pair of bits in each operand. If both operand bits are 1, the & function sets the resulting bit to 1. Otherwise, the resulting bit is set to 0. Examples of both the & and the | operators are: 1010 & 0010 = 0010 1010 | 0001 = 1011 ( 1010 & ( 1100 | 1101 )) = 1000
|	Bitwise binary	Numeric, Dye flag	Performs the bitwise OR function on each parallel pair of bits in each operand. If either operand bit is 1, the | function sets the resulting bit to 1. Otherwise, the resulting bit is set to 0. For examples, see the entry for the bitwise & operator, above.
=	Relational	Numeric, String	Equals
!=	Relational	Numeric	Not equals
<	Relational	Numeric	Less than
>	Relational	Numeric	Greater than
<=	Relational	Numeric	Less than or equals
>=	Relational	Numeric	Greater than or equals
LIKE	Match	String	Evaluates to true when a character string matches a specified pattern that can include wildcards. LIKE supports two wildcard characters: A percent sign (%) matches any string of zero or more characters A period (.) matches any single character
MATCHES	Match	String	Evaluates to true when a target string matches the regular expression pattern in the operand String.
IN	Search	String	Evaluates to true when the value of a variable exists in a predefined set, for example: SUBSYSTEM IN ('A','B')

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:

1. ( )

2. NOT

3. &, |

4. =, !=, <, >, <=, >=, LIKE, MATCHES,IN

5. AND

6. OR

Numeric Relational Operations Supported on String Column Types

Numeric relational operations can be performed on String column types when they hold numeric values. For example, if STATUS is a String type, while performing relational operations with a numeric operand, the column value is treated as a numeric value. For instance, in the following comparisons:

STATUS = 100

STATUS != 100

STATUS < 100

STATUS <= 100

STATUS > 100

STATUS >= 100

the query evaluator attempts to convert the string value to appropriate numeric value before comparison. When the string value cannot be converted to a numeric value, the query fails.

Supported Numeric Constants and String Literals

Rules for numeric constants 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.

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.

• An underscore character (_) can be used as a wildcard to stand for any single character.

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

• Chapter 8, "Configuring Watches and Notifications"

• Chapter 9, "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:

Table A-2 Variable Names for Log Event Watch Rule Expressions

Variable	Description	Data Type
CONTEXTID	The request ID propagated with the request.	String
DATE	Date when the message was created.	String
MACHINE	Name of machine that generated the log message.	String
MESSAGE	Message content of the log message.	String
MSGID	ID of the log message (usually starts with "BEA=").	String
RECORDID	The number of the record in the log.	Long
SERVER	Name of server that generated the log message.	String
SEVERITY	Severity of log message. Values are ALERT, CRITICAL, DEBUG, EMERGENCY, ERROR, INFO, NOTICE, OFF, TRACE, and WARNING.	String
SUBSYTEM	Name of subsystem emitting the log message.	String
THREAD	Name of thread that generated the log message.	String
TIMESTAMP	Timestamp when the log message was created.	Long
TXID	JTA transaction ID of thread that generated the log message.	String
USERID	ID of the user that generated the log message.	String

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:

Table A-3 Variable Names for Instrumentation Event Rule Expressions

Variable	Description	Data Type
ARGUMENTS	Arguments passed to the method that was invoked.	String
CLASSNAME	Class name of joinpoint.	String
CONTEXTID	Diagnostic context ID of instrumentation event.	String
CTXPAYLOAD	The context payload associated with this request.	String
DOMAIN	Name of domain.	String
DYES	Dyes associated with this request.	Long
FILENAME	Source file name.	String
LINENUM	Line number in source file.	Integer
METHODNAME	Method name of joinpoint.	String
METHODDSC	Method arguments of joinpoint.	String
MODULE	Name of the diagnostic module.	String
MONITOR	Name of the monitor.	String
PAYLOAD	Payload of instrumentation event.	String
RECORDID	The number of the record in the log.	Long
RETVAL	Return value of joinpoint.	String
SCOPE	Name of instrumentation scope.	String
SERVER	Name of server that created the instrumentation event.	String
TIMESTAMP	Timestamp when the instrumentation event was created.	Long
TXID	JTA transaction ID of thread that created the instrumentation event.	String
TYPE	Type of monitor.	String
USERID	ID of the user that created the instrumentation event.	String

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 harvestable MBean attributes. The expression can specify an MBean type, an instance, and/or an attribute.

Instance-based and type-based expressions can contain an optional namespace component, which is the namespace of the metric being watched. It can be set to either Server Runtime or DomainRuntime. If omitted, it defaults to ServerRuntime.

If included and set to DomainRuntime, you should limit the usage to monitoring only DomainRuntime-specific MBeans, such as the ServerLifeCycleRuntimeMBean. Monitoring remote managed server MBeans through the DomainRuntime MBeanServer is possible, but is discouraged for performance reasons. It is a best practice to use the resident watcher in each managed server to monitor metrics related to that managed server instance.

You can also use wildcards in instance names in Harvester watch rule expressions, as well as specify complex attributes in Harvester watch rule expressions. See Appendix C, "Using Wildcards in Expressions."

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:

      ${namespace//[type_name]//attribute_name}

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

      ${com.bea:namespace//instance_name//attribute_name}

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

      ${domain_name:instance_name//attribute_name}

Note:

The domain_name is not required for a WebLogic Server domain 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.

Table A-4 Naming Conventions for Log Types

Log Type	Optional Identifiers	Example
ConnectorLog	The JNDI name of the connection factory	ConnectorLog/eis/ 900eisaBlackBoxXATxConnectorJNDINAME where eis/900eisaBlackBoxXATxConnectorJNDINAME is the JNDI name of the connection factory specified in the weblogic-ra.xml deployment descriptor.
DomainLog	None	DomainLog
EventsDataArchive	None	EventsDataArchive
HarvestedDataArchive	None	HarvestedDataArchive
HTTPAccessLog	Virtual host name	HTTPAccessLog - For the default web server's access log. HTTPAccessLog/MyVirtualHost - For the Virtual host named MyVirtualHost deployed to the current server. Note: In the case of HTTPAccessLog logs with extended format, the number of columns are user-defined.
JMSMessageLog	The name of the JMS Server.	JMSMessageLog/MyJMSServer
ServerLog	None	ServerLog
WebAppLog	Web server name + Root servlet context name	WebAppLog/MyWebServer/MyRootServletContext

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.

Table A-5 Column Names for Log Types

Log Type	Column Names
ConnectorLog	LINE, RECORDID
DomainLog	CONTEXTID, DATE, MACHINE, MESSAGE, MSGID, RECORDID, SERVER, SEVERITY, SUBSYSTEM, THREAD, TIMESTAMP, TXID, USERID
EventsDataArchive	ARGUMENTS, CLASSNAME, CONTEXTID, CTXPAYLOAD, DOMAIN, DYES, FILENAME, LINENUM, METHODNAME, METHODDSC, MODULE, MONITOR, PAYLOAD, RECORDID, RETVAL, SCOPE, SERVER, THREADNAME, TIMESTAMP, TXID, TYPE, USERID
HarvestedDataArchive	ATTRNAME, ATTRTYPE, ATTRVALUE, DOMAIN, NAME, RECORDID, SERVER, TIMESTAMP, TYPE
HTTPAccessLog	AUTHUSER, BYTECOUNT, HOST, RECORDID, REMOTEUSER, REQUEST, STATUS, TIMESTAMP
JDBCLog	Same as DomainLog
JMSMessageLog	CONTEXTID, DATE, DESTINATION, EVENT, JMSCORRELATIONID, JMSMESSAGEID, MESSAGE, MESSAGECONSUMER, NANOTIMESTAMP, RECORDID, SELECTOR, TIMESTAMP, TXID, USERID
ServerLog	Same as DomainLog
WebAppLog	Same as DomainLog

An example of a Data Accessor query is:

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

In this example, the Accessor retrieves all messages that include the string "Failed" from the Deployer subsystem.

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 Chapter 13, "Accessing Diagnostic Data With 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 you use 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 for Oracle WebLogic Server.

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 (MSGID = '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.