Descriptions of properties for logging and tracing

You can set the following properties:

pdq.traceFile

Specifies the physical file where the log information is written. You can use an absolute path or a path that is relative to the directory in which the pureQuery enabled application runs.

If the file exists for a Java™ application, pureQuery deletes the content of the file before using the file for new log entries.

The traceFile property can be specified only in a global pdq.properties file. The property cannot be specified in a pdq.properties file that specifies the properties for an application or an application data source connection.

pdq.traceLevel

Specifies the level of detail to write to the log file. 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.

You can specify the trace level for pureQuery component logging. For information about logging pureQuery component trace information see Specifying the trace level for pureQuery Runtime component properties.

The traceLevel property can be specified only in a global pdq.properties file. The property cannot be specified in a pdq.properties file that specifies the properties for an application or an application data source connection.

pdq.traceBufferRowCount

Specifies the maximum number of log records that are buffered in memory. The value for the traceBufferRowCount property can be a nonnegative integer. The default value, 0 specifies that log records are not buffered in memory.

If the traceBufferRowCount property is enabled, the pureQuery Runtime property dumpLogsOnSqlCodes must also be specified to write log records to a file. The value of the dumpLogsOnSqlCodes property is a list of SQL error codes. When a listed error occurs, the log records that are buffered in memory are written to the log file. The log file is specified by the traceFile property. If a specified error code is not detected or the property dumpLogsOnSqlCodes is not specified and the maximum amount of memory is reached, the oldest records are deleted from memory when new records are buffered in memory.

The property dumpLogsExcludingSqlCodes can be specified with the SQL error codes that do not trigger writing log records to the log file.

The following example buffers a maximum of 8000 log records in memory and specifies an SQL error from the pureQuery Runtime default list of SQL errors causes the log records to be written the log file.

pdq.traceBufferRowCount=8000
pdq.dumpLogsOnSqlCodes=default

The traceBufferRowCount option is designed to be used with stand-alone pureQuery Runtime applications. It is independent of the WebSphere® ring buffer.

pdq.dumpLogsOnSqlCodes

If pureQuery Runtime is buffering log records in memory, this property specifies the SQL error codes that trigger writing the records to the log file.

The value for this property is a list of SQL error codes separated by a pipe character (|). The list can contain the keyword default. The keyword default specifies a list of SQL error codes that pureQuery Runtime uses to trigger writing buffered log records to the log file. When you specify the SQL error code, you must include the leading dash. The following example, lists two SQL error codes that trigger writing buffered log records to the log file:

pdq.traceBufferRowCount=8000
pdq.dumpLogsOnSqlCodes=-805|-810

pureQuery Runtime writes the log records that are in memory to the log file if either SQL error code -805 or -810 occurs or when the number of records specified by the traceBufferRowCount property is buffered in memory.

The following example lists the default list of SQL error codes and the SQL error code -3476 as error codes that trigger writing buffered log records to the log file:

pdq.traceBufferRowCount=8000
pdq.dumpLogsOnSqlCodes=default|-3476

If you use the keyword default, you can specify specific SQL error codes dumpLogsExcludingSqlCodes that do not trigger writing buffered log records to the log file. For a list of pureQuery Runtime default SQL error codes, see List of pureQuery Runtime default SQL error codes that are used with logging.

pdq.dumpLogsExcludingSqlCodes

If pureQuery Runtime buffers log records in memory, this property specifies the SQL error codes that do not trigger writing buffered log records to the log file. The dumpLogsOnSqlCodes property specifies the SQL error codes that trigger writing buffered log records to the log file. The value for this property is a list of SQL error codes separated by a pipe character (|). When you specify the SQL error code, the sign of the SQL error code is significant, for example 805 and -805 are different error codes. You use this property when you specify the default keyword with dumpLogsOnSqlCodes.

In the following example, buffering log records in memory is enabled for a maximum of 8000 records. pureQuery Runtime writes the buffered log records to the log file when an SQL error code in the default list or the error code -3476 is encountered. The default list of SQL error codes contains the error code -805. The dumpLogsExcludingSqlCodes property specified that SQL error code -805 does not trigger the writing buffered log records to the log file.

pdq.traceBufferRowCount=8000
pdq.dumpLogsOnSqlCodes=default|-3476
pdq.dumpLogsExcludingSqlCodes=-805

Java application usage notes

pureQuery Runtime uses the java.util.logging framework. Within that framework, pureQuery Runtime names its parent logger com.ibm.pdq.logger. Using Java logging API conventions and tools, you and your applications can set the log level and log file for the com.ibm.pdq so that pureQuery log messages are forwarded to this logger.

Many application servers provide administrative tools to configure loggers that run under the java.util.logging framework. For example, with WebSphere Application Server, you can configure the com.ibm.pdq logger to control pureQuery logging and tracing. Using an application server tooling is an alternative to configuring pureQuery logging with pureQuery Runtime properties. pureQuery uses the com.ibm.pdq logger level if it is higher than the level that is specified for the pureQuery pdq.traceLevel property and if the com.ibm.pdq logger level is higher than INFO. In the WebSphere Application Server Integrated Solutions Console, you can set the com.ibm.pdq logger level by selecting Troubleshooting > Logs and Trace.

If the com.ibm.pdq logger trace level is set to a level that is more inclusive than INFO, and if pureQuery properties do not specify a level that is more inclusive than the com.ibm.pdq logger trace level, pureQuery inherits the level of the com.ibm.pdq logger.

If you plan to use WebSphere Application Server with your pureQuery application, you must set the level higher than INFO if you want to see pureQuery log entries in the log for WebSphere Application Server.

pureQuery Runtime does not explicitly integrate logging with JDBC driver logs. However, JDBC drivers which also log using the Java logging API can participate in the logging framework integration. This means that pureQuery and JDBC driver log entries are interleaved in the same log file if both the JDBC driver and pureQuery Runtime are configured to log to the WebSphere trace.

Logging the results of calls to the getJccSpecialRegisterProperties() method

If your application uses the IBM® Data Server Driver for JDBC and SQLJ to connect to a supported DB2® database, and calls the getJccSpecialRegisterProperties() method on a Connection object, pureQuery can log the results of the first call to that method on the object. The message that pureQuery writes to the log lists all of the non-null values for the special registers that the driver supports for the database.

To see this message in the log, set the trace level to FINE.

DB2 CLI and IBM Data Server Driver usage notes

When using DB2 Call Level Interface (CLI) or the IBM Data Server Driver with pureQuery Runtime, you can use the pureQuery Runtime properties as configuration keywords.

For information about logging and tracing with CLI applications enabled with pureQuery client optimization, see Logging and tracing with pureQuery Runtime.

IBM CLI keyword syntax

traceFile = path-to-logfile

You can use an absolute path or a relative path to the directory in which the CLI application runs. If the file exists, new log messages are appended to the existing content of the file.

traceLevel = trace-level

IBM Data Server Driver configuration syntax

<parameter name="traceFile" value="path-to-logfile" />

You can use an absolute path or a relative path to the directory in which the CLI application runs. If the file exists, new log messages are appended to the existing content of the file.

<parameter name="traceLevel" value="trace-level" />

Equivalent IBM Data Server Provider for .NET connection string keywords

traceFile=path-to-logfile

You can use an absolute path or a relative path to the directory in which the .NET application runs. If the file exists, new log messages are appended to the existing content of the file.

traceLevel=trace-level

The following lines set the traceFile to /user/CLIOPTtraces.log and the traceLevel to INFO in a db2cli.ini file:

traceFile=/user/CLIOPTtraces.log
traceLevel=INFO