DB2 10.5 for Linux, UNIX, and Windows

DB2SystemMonitor interface

The com.ibm.db2.jcc.DB2SystemMonitor interface is used for collecting system monitoring data for a connection. Each connection can have one DB2SystemMonitor instance.

DB2SystemMonitor fields

The following fields are defined only for the IBM® Data Server Driver for JDBC and SQLJ.

public final static int RESET_TIMES
public final static int ACCUMULATE_TIMES
These values are arguments for the DB2SystemMonitor.start method. RESET_TIMES sets time counters to zero before monitoring starts. ACCUMULATE_TIMES does not set time counters to zero.

DB2SystemMonitor methods

The following methods are defined only for the IBM Data Server Driver for JDBC and SQLJ.

enable
Format: 
public void enable(boolean on) 
  throws java.sql.SQLException

Enables the system monitor that is associated with a connection. This method cannot be called during monitoring. All times are reset when enable is invoked.

getApplicationTimeMillis
Format: 
public long getApplicationTimeMillis()
  throws java.sql.SQLException

Returns the sum of the application, JDBC driver, network I/O, and database server elapsed times. The time is in milliseconds.

A monitored elapsed time interval is the difference, in milliseconds, between these points in the JDBC driver processing:
Interval beginning
When start is called.
Interval end
When stop is called.

getApplicationTimeMillis returns 0 if system monitoring is disabled. Calling this method without first calling the stop method results in an SQLException.

getCoreDriverTimeMicros
Format: 
public long getCoreDriverTimeMicros()
  throws java.sql.SQLException

Returns the sum of elapsed monitored API times that were collected while system monitoring was enabled. The time is in microseconds.

A monitored API is a JDBC driver method for which processing time is collected. In general, elapsed times are monitored only for APIs that might result in network I/O or database server interaction. For example, PreparedStatement.setXXX methods and ResultSet.getXXX methods are not monitored.

Monitored API elapsed time includes the total time that is spent in the driver for a method call. This time includes any network I/O time and database server elapsed time.

A monitored API elapsed time interval is the difference, in microseconds, between these points in the JDBC driver processing:
Interval beginning
When a monitored API is called by the application.
Interval end
Immediately before the monitored API returns control to the application.

getCoreDriverTimeMicros returns 0 if system monitoring is disabled. Calling this method without first calling the stop method, or calling this method when the underlying JVM does not support reporting times in microseconds results in an SQLException.

getNetworkIOTimeMicros
Format: 
public long getNetworkIOTimeMicros()
  throws java.sql.SQLException

Returns the sum of elapsed network I/O times that were collected while system monitoring was enabled. The time is in microseconds.

Elapsed network I/O time includes the time to write and read DRDA® data from network I/O streams. A network I/O elapsed time interval is the time interval to perform the following operations in the JDBC driver:
  • Issue a TCP/IP command to send a DRDA message to the database server. This time interval is the difference, in microseconds, between points immediately before and after a write and flush to the network I/O stream is performed.
  • Issue a TCP/IP command to receive DRDA reply messages from the database server. This time interval is the difference, in microseconds, between points immediately before and after a read on the network I/O stream is performed.

Network I/O time intervals are captured for all send and receive operations, including the sending of messages for commits and rollbacks.

The time spent waiting for network I/O might be impacted by delays in CPU dispatching at the database server for low-priority SQL requests.

getNetworkIOTimeMicros returns 0 if system monitoring is disabled. Calling this method without first calling the stop method, or calling this method when the underlying JVM does not support reporting times in microseconds results in an SQLException.

getServerTimeMicros
Format: 
public long getServerTimeMicros()
  throws java.sql.SQLException

Returns the sum of all reported database server elapsed times that were collected while system monitoring was enabled. The time is in microseconds.

The database server reports elapsed times under these conditions:
  • The database server supports returning elapsed time data to the client.

    DB2® for Linux, UNIX, and Windows Version 9.5 and later and DB2 for z/OS® support this function.

  • The database server performs operations that can be monitored. For example, database server elapsed time is not returned for commits or rollbacks.
For IBM Data Server Driver for JDBC and SQLJ type 2 connectivity to DB2 for Linux, UNIX, and Windows, and IBM Data Server Driver for JDBC and SQLJ type 4 connectivity: The database server elapsed time is defined as the elapsed time to parse the request data stream, process the command, and generate the reply data stream at the database server. Network time to receive or send the data stream is not included. The database server elapsed time interval is the difference, in microseconds, between these points in the database server processing:
Interval beginning
When the operating system dispatches the database server to process a TCP/IP message that is received from the JDBC driver.
Interval end
When the database server is ready to issue the TCP/IP command to return the reply message to the client.
For IBM Data Server Driver for JDBC and SQLJ type 2 connectivity to DB2 for z/OS: The database server elapsed time interval is the difference, in microseconds, between these points in the JDBC driver native processing:
Interval beginning
The z/OS Store Clock (STCK) value when a JDBC driver native method calls the RRS attachment facility to process an SQL request.
Interval end
The z/OS Store Clock (STCK) value when control returns to the JDBC driver native method following an RRS attachment facility call to process an SQL request.

getServerTimeMicros returns 0 if system monitoring is disabled. Calling this method without first calling the stop method results in an SQLException.

start
Format: 
public void start (int lapMode) 
  throws java.sql.SQLException

If the system monitor is enabled, start begins the collection of system monitoring data for a connection. Valid values for lapMode are RESET_TIMES or ACCUMULATE_TIMES.

Calling this method with system monitoring disabled does nothing. Calling this method more than once without an intervening stop call results in an SQLException.

stop
Format: 
public void stop()
  throws java.sql.SQLException

If the system monitor is enabled, stop ends the collection of system monitoring data for a connection. After monitoring is stopped, monitored times can be obtained with the getXXX methods of DB2SystemMonitor.

Calling this method with system monitoring disabled does nothing. Calling this method without first calling start, or calling this method more than once without an intervening start call results in an SQLException.

Related concepts:
System monitoring for the IBM Data Server Driver for JDBC and SQLJ