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

A query expression may include:

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

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:

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

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:

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.