Descriptions of properties for pureQuery component logging and tracing

For Java™ applications, you can control log levels for different pureQuery components such as pureQuery Runtime API, pureQuery client optimization, CMX monitoring. You can also send database log events that are monitored by pureQuery Runtime to a repository.

pureQuery uses the java.util.logging framework. For information about pureQuery logging and the java.util.logging framework, see Java application usage notes.

pureQuery component logging parameters

pureQuery component based logging supports the following log levels. In order from the least to the most detail, the levels are as follow:

OFF
SEVERE
WARNING
INFO
CONFIG
FINE
FINER
FINEST
ALL

The default level is OFF.

The following pureQuery Runtime properties control pureQuery component based logging:

com.ibm.pdq

Specify the log level for all pureQuery components when a more specific component is not specified.

com.ibm.pdq.api

Specify the log level when running inline method or DAO style pureQuery API

com.ibm.pdq.api.static

Specify the log level pureQuery Runtime DAO is running static

com.ibm.pdq.api.dynamic

Specify the log level pureQuery Runtime DAO style is running dynamic

com.ibm.pdq.co

Specify the log level when pureQuery client optimization is running an SQL statement.

com.ibm.pdq.co.static

Specify the log level when pureQuery client optimization is running an SQL statement statically.

com.ibm.pdq.co.dynamic

Specify the log level when pureQuery client optimization is running an SQL statement dynamically.

com.ibm.pdq.cmx

Specify the log level for CMX client monitoring.

com.ibm.pdq.database

Specify the log level to log database events recorded by pureQuery Runtime. The log level setting must be explicitly set for this property. The property is not a child property of the com.ibm.pdq property.

The following table lists the database events logged for the com.ibm.pdq.database property.

Table 1. Log level for pureQuery database event logging
Log level	Database event
CONFIG	SQL errors listed in dumpLogsOnSqlCodes and not listed in dumpLogsExcludedSqlCodes
FINE	Refresh of pureQuery properties from a repository
FINER	Dynamic PREPARE of an SQL statement by pureQuery client optimization
FINEST	Static PREPARE of an SQL statement by pureQuery client optimization

If the application is configured to use a repository for pureQuery data, pureQuery Runtime can store a small subset of the log records in the repository. The repository must be specified in the global pdq.properties file. Repository locations that are specified at the application level or data source level are ignored for logging purposes.

The log records are stored in the IBMPDQ.LOG table. To view all log records stored in the repository you can issue the following SQL statement:

 select * from ibmpdq.log

Note: Before you can store the log records in an existing repository, you might need to upgrade the repository. See the -upgrade option of the ManageRepository utility.

Usage notes

For stand-alone Java users, log levels can be managed with the pureQuery Runtime pdq.properties file and in other ways. If the application manages pureQuery component logging with the pdq.properties, the log file can reside on disk or the contents of the log can be stored in a repository. To control log levels for pureQuery component logging, JRE supports logging.properties file in the JRE/lib folder.

For the pureQuery component logging properties, the child log properties inherit the log setting of the parent level. You can override the parent level log setting by explicitly setting child log setting.

For example, if you set only the log level of the com.ibm.pdq.co property to FINE, the log level of the child properties com.ibm.pdq.co.static and com.ibm.pdq.co,dynamic are also FINE.

You can use the methods provided by java.util.logging to set log levels. Other applications might have other methods to manage java.util.logging loggers as well.

If you do not set a log level on any of the pureQuery component log properties, they inherit the level of their parent (for example com.ibm) in a WebSphere® environment.

The following WebSphere Application Server example sets pureQuery component log properties to ALL:

com.ibm.pdq.*=all

Specifying the trace level for pureQuery Runtime component properties

In order to set log levels for the pureQuery component tracing, you can use the following syntax in a global pdq.properties file:

pdq.traceLevel=OFF
pdq.traceLevel.com.ibm.pdq.co=FINER
pdq.traceLevel.com.ibm.pdq.co.static=FINE

These pureQuery Runtime properties can be specified in a pdq.properties file on disk or in a repository. When pureQuery Runtime refreshes the properties from the repository at refresh interval, the log levels are applied to the pureQuery loggers.

There is no equivalent to pdq.traceFile for the pureQuery component logging properties.

Specifying pureQuery Runtime trace properties from a repository

The pureQuery Runtime properties that are used for tracing pdq.traceLevel and pdq.traceLevel.com.ibm.pdq.*, and the property dumpLogsOnSqlCodes can be specified in a repository. You set the pureQuery Runtime properties in a pdq.properties file and upload information in the file to a repository. If a repository refresh interval is specified, the updated log properties are read from the repository at the specified time and are applied to the application enabled with pureQuery Runtime.

The repository must be specified in the global pdq.properties file. Repository locations that are specified at the application or data source level are ignored for logging purposes.

You can use the ManageRepository utility with the -pureQueryProperties option to upload a pureQuery Runtime properties file to a repository. The following command is run from a script, and uploads the file pdq.properties that contains trace levels into a repository:

java -cp %PQ_USER_CLASSPATH% com.ibm.pdq.tools.ManageRepository 
   -update runtimeGroup 
   -pureQueryProperties pdqrep.properties 
   -runtimeGroupID %1 -runtimeGroupVersion %2 
   -repositoryURL %PQ_REP_URL% 
   -repositoryUsername %PQ_REP_USERNAME% 
   -repositoryPassword %PQ_REP_PASSWORD% 
   -repositoryDriverClass com.ibm.db2.jcc.DB2Driver

When the script is run from the command line, the variables %1 and %1 are replaced with values specified when the script is run. The variables such as %PQ_USER_CLASSPATH% are replaced by values specified by environment variables.

Feedback