C WLDF Query Language
- Components of a Query Expression
A query expression may include operators, literals, and variables. - Supported Operators
The WLDF query language supports a set of operators and, for each operator, corresponding operator and operand types. - Operator Precedence
The WLDF query language has six levels of precedence among its operators. - Numeric Relational Operations Supported on String Column Types
Numeric relational operations can be performed on String column types when they hold numeric values. - Supported Numeric Constants and String Literals
The WLDF query language has two sets of rules: one set for numeric constants, and another for string literals. - About Variables in Expressions
Variables represent the dynamic portion of a query expression that is evaluated at run time. - Creating Policy Expressions
You can create policies based on log events, instrumentation events, and harvested attributes. - 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. - Creating Log Filter Expressions
The query language can be used to filter what is written to the server log. - Building Complex Expressions
You can build complex query expressions using subexpressions containing variables, binary comparisons, and other complex subexpressions.
Components of a Query Expression
The query language is case-sensitive.
Parent topic: WLDF Query Language
Supported Operators
Table C-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') |
Parent topic: WLDF Query Language
Operator Precedence
The WLDF query language has six levels of precedence among its operators.
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
Parent topic: WLDF Query Language
Numeric Relational Operations Supported on String Column Types
For instance, in the following comparisons, the query evaluator attempts to convert the string value to appropriate numeric value before comparison:
STATUS = 100
STATUS != 100
STATUS < 100
STATUS <= 100
STATUS > 100
STATUS >= 100
When the string value cannot be converted to a numeric value, the query fails.
Parent topic: WLDF Query Language
Supported Numeric Constants and String Literals
The WLDF query language has two sets of rules: one set for numeric constants, and another for string literals.
The 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.
The 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. See the documentation for the java.lang.String.compareTo(String str) method.
Parent topic: WLDF Query Language
About Variables in Expressions
Note:
When specifying a wildcard pattern in a variable for a policy expression that matches custom MBean ObjectName instances, make sure the pattern is sufficiently explicit. If you exclude an MBean type name and use an ambiguous instance pattern, the following may result:
-
Only WebLogic Server runtime MBean instances are matched to the pattern.
-
The desired custom MBean instances are ignored.
For example, the following ObjectName pattern does not explicitly declare a type and uses an ambiguous ObjectName pattern that can match a WebLogic Server runtime MBean instance:
${ServerRuntime//com.b*:Type=Server*,*}
The preceding pattern matches the WebLogic Server runtime MBean instances, and causes any custom MBeans matching the same pattern to be ignored.
Parent topic: WLDF Query Language
Creating Policy Expressions
For complete documentation about configuring and using WLDF policies, see:
The variables supported for creating the expressions are different for each type of policy, as described in the following sections:
- Creating Log Event Policy Expressions
- Creating Instrumentation Event Policy Expressions
- Creating Harvester Policy Expressions
Parent topic: WLDF Query Language
Creating Log Event Policy Expressions
A log event policy 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 C-2:
Table C-2 Variable Names for Log Event Policy Expressions
Variable | Description | Data Type |
---|---|---|
|
The request ID propagated with the request. |
String |
|
Date when the message was created. |
String |
|
Name of machine that generated the log message. |
String |
|
Message content of the log message. |
String |
|
ID of the log message (usually starts with "BEA="). |
String |
|
The number of the record in the log. |
Long |
|
Name of server that generated the log message. |
String |
|
Severity of log message. Values are |
String |
|
Name of subsystem emitting the log message. |
String |
|
Name of thread that generated the log message. |
String |
|
Timestamp when the log message was created. |
Long |
|
JTA transaction ID of thread that generated the log message. |
String |
|
ID of the user that generated the log message. |
String |
An example log event policy expression is:
(SEVERITY = 'Warning') AND (MSGID = 'BEA-320012')
Parent topic: Creating Policy Expressions
Creating Instrumentation Event Policy Expressions
An instrumentation event policy 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 C-3:
Table C-3 Variable Names for Instrumentation Event Policy Expressions
Variable | Description | Data Type |
---|---|---|
|
Arguments passed to the method that was invoked. |
String |
|
Class name of joinpoint. |
String |
|
Diagnostic context ID of instrumentation event. |
String |
|
The context payload associated with this request. |
String |
|
Name of domain. |
String |
|
Dyes associated with this request. |
Long |
|
Source file name. |
String |
|
Line number in source file. |
Integer |
|
Method name of joinpoint. |
String |
|
Method arguments of joinpoint. |
String |
|
Name of the diagnostic module. |
String |
|
Name of the monitor. |
String |
|
Payload of instrumentation event. |
String |
|
The number of the record in the log. |
Long |
|
Return value of joinpoint. |
String |
|
Name of instrumentation scope. |
String |
|
Name of server that created the instrumentation event. |
String |
|
Timestamp when the instrumentation event was created. |
Long |
|
JTA transaction ID of thread that created the instrumentation event. |
String |
|
Type of monitor. |
String |
|
ID of the user that created the instrumentation event. |
String |
An example instrumentation event data policy expression is:
(USERID = 'weblogic')
Parent topic: Creating Policy Expressions
Creating Harvester Policy Expressions
A Harvester policy expression is based upon one or more harvestable MBean attributes. The expression can specify an MBean type, an instance, an attribute, or an instance and an attribute.
Instance-based and type-based expressions can contain an optional namespace component, which is the namespace of the metric being monitored by the policy. It can be set to either Server Runtime or DomainRuntime. If omitted, it defaults to ServerRuntime.
If the namespace component is 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 policy in each Managed Server to monitor metrics related to that Managed Server instance.
You can also use wildcards in instance names in Harvester policy expressions, as well as specify complex attributes in Harvester policy expressions. See Using Wildcards in Expressions.
The syntax for constructing a Harvester policy 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
Parent topic: Creating Policy Expressions
Creating Data Accessor Queries
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 C-4.
Table C-4 Naming Conventions for Log Types
Log Type | Optional Identifiers | Example |
---|---|---|
ConnectorLog |
The JNDI name of the connection factory |
ConnectorLog/eis/
900eisaBlackBoxXATxConnectorJNDINAME In this
example, |
DataSourceLog |
None |
|
DomainLog |
None |
DomainLog |
EventsDataArchive |
None |
EventsDataArchive |
HarvestedDataArchive |
None |
HarvestedDataArchive |
HTTPAccessLog |
Virtual host name |
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 |
JMSSAFMessageLog |
The name of the SAF agent. |
|
ServerLog |
None |
ServerLog |
WebAppLog |
Web server name + Root servlet context name |
WebAppLog/MyWebServer/MyRootServletContext |
Parent topic: Creating Data Accessor Queries
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 C-5.
Table C-5 Column Names for Log Types
Log Type | Column Names |
---|---|
ConnectorLog |
LINE, RECORDID |
DataSourceLog |
RECORDID, DATASOURCE, PROFILETYPE, TIMESTAMP, USER, PROFILEINFORMATION, SUPP_ATTRS |
DomainLog |
CONTEXTID, DATE, MACHINE, MESSAGE, MSGID, RECORDID, SERVER, SEVERITY, SUBSYSTEM, THREAD, TIMESTAMP, TXID, USERID, SUPP_ATTRS, SEVERITY_VALUE |
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, WLDFMODULE |
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 |
JMSSAFMessageLog |
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 Accessing Diagnostic Data With the Data Accessor.
Parent topic: Creating Data Accessor Queries
Creating Log Filter Expressions
-
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.
Parent topic: WLDF Query Language
Building Complex Expressions
-
Nest queries by surrounding subexpressions 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 consecutive forward slashes (
//
) in the policy variable name.
Parent topic: WLDF Query Language