Configuring and Using the WebLogic Diagnostics Framework
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.
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
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:
- 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:
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 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 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}
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.
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%')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 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
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.
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} >= 1Notice that the object name and the attribute name are separated by '//' in the watch variable name.