DB2 Version 9.7 for Linux, UNIX, and Windows

Governor log files

Whenever a governor daemon performs an action, it writes a record to its log file.

Actions include the following:

Starting or stopping the governor
Reading the governor configuration file
Changing an application's priority
Forcing an application
Encountering an error or warning

Each governor daemon has a separate log file, which prevents file-locking bottlenecks that might result when many governor daemons try to write to the same file simultaneously. To query the governor log files, use the db2govlg command.

The log files are stored in the log subdirectory of the sqllib directory, except on Windows operating systems, where the log subdirectory is located under the Common Application Data directory that Windows operating systems use to host application log files. You provide the base name for the log file when you start the governor with the db2gov command. Ensure that the log file name contains the database name to distinguish log files on each database partition that is governed. To ensure that the file name is unique for each governor in a partitioned database environment, the number of the database partition on which the governor daemon runs is automatically appended to the log file name.

Log file record format

Each record in the log file has the following format:

   Date Time DBPartitionNum RecType Message

The format of the Date and Time fields is yyyy-mm-dd-hh.mm.ss. You can merge the log files for each database partition by sorting on this field. The DBPartitionNum field contains the number of the database partition on which the governor is running.

The RecType field contains different values, depending on the type of record being written to the log. The values that can be recorded are:

ACCOUNT: the application accounting statistics
ERROR: an error occurred
FORCE: an application was forced
NICE: the priority of an application was changed
READCFG: the governor read the configuration file
SCHEDGRP: a change in agent priorities occurred
START: the governor was started
STOP: the governor was stopped
WARNING: a warning occurred

Some of these values are described in more detail below.

ACCOUNT

An ACCOUNT record is written in the following situations:

The value of the agent_usr_cpu_time or agent_sys_cpu_time monitor element for an application has changed since the last ACCOUNT record was written for this application.
An application is no longer active.

The ACCOUNT record has the following format:

<auth_id> <appl_id> <applname> <connect_time> <agent_usr_cpu_delta>
  <agent_sys_cpu_delta>

ERROR

An ERROR record is written when the governor daemon needs to shut down.

FORCE

A FORCE record is written when the governor forces an application, based on rules in the governor configuration file. The FORCE record has the following format:

<appl_name> <auth_id> <appl_id> <coord_partition> <cfg_line>
  <restriction_exceeded>

where:

coord_partition

Specifies the number of the application's coordinator database partition.

cfg_line

Specifies the line number in the governor configuration file where the rule causing the application to be forced is located.

restriction_exceeded

Provides details about how the rule was violated. Valid values are:

CPU: the total application USR CPU plus SYS CPU time, in seconds
Locks: the total number of locks held by the application
Rowssel: the total number of rows selected by the application
Rowsread: the total number of rows read by the application
Idle: the amount of time during which the application was idle
ET: the elapsed time since the application's current unit of work started (the uowtime setlimit was exceeded)

NICE

A NICE record is written when the governor changes the priority of an application, based on rules in the governor configuration file. The NICE record has the following format:

<appl_name> <auth_id> <appl_id> <nice_value> <cfg_line>
  <restriction_exceeded>

where:

nice_value

Specifies the increment or decrement that will be made to the priority value for the application's agent process.

cfg_line

Specifies the line number in the governor configuration file where the rule causing the application's priority to be changed is located.

restriction_exceeded

Provides details about how the rule was violated. Valid values are:

CPU: the total application USR CPU plus SYS CPU time, in seconds
Locks: the total number of locks held by the application
Rowssel: the total number of rows selected by the application
Rowsread: the total number of rows read by the application
Idle: the amount of time during which the application was idle
ET: the elapsed time since the application's current unit of work started (the uowtime setlimit was exceeded)

SCHEDGRP

A SCHEDGRP record is written when an application is added to a scheduling group or an application is moved from one scheduling group to another. The SCHEDGRP record has the following format:

<appl_name> <auth_id> <appl_id> <cfg_line> <restriction_exceeded>

where:

cfg_line

Specifies the line number in the governor configuration file where the rule causing the application to be scheduled is located.

restriction_exceeded

Provides details about how the rule was violated. Valid values are:

CPU: the total application USR CPU plus SYS CPU time, in seconds
Locks: the total number of locks held by the application
Rowssel: the total number of rows selected by the application
Rowsread: the total number of rows read by the application
Idle: the amount of time during which the application was idle
ET: the elapsed time since the application's current unit of work started (the uowtime setlimit was exceeded)

START

A START record is written when the governor starts. The START record has the following format:

Database = <database_name>

STOP

A STOP record is written when the governor stops. It has the following format:

Database = <database_name>

WARNING

A WARNING record is written in the following situations:

The sqlefrce API was called to force an application, but it returned a positive SQLCODE.
A snapshot call returned a positive SQLCODE that was not 1611 (SQL1611W).
A snapshot call returned a negative SQLCODE that was not -1224 (SQL1224N) or -1032 (SQL1032N). These return codes occur when a previously active instance has been stopped.
In a Linux or UNIX-based environment, an attempt to install a signal handler has failed.

Because standard values are written, you can query the log files for different types of actions. The Message field provides other nonstandard information that depends on the type of record. For example, a FORCE or NICE record includes application information in the Message field, whereas an ERROR record includes an error message.

A governor log file might look like the following example:

2007-12-11-14.54.52    0 START      Database = TQTEST
2007-12-11-14.54.52    0 READCFG    Config = /u/db2instance/sqllib/tqtest.cfg
2007-12-11-14.54.53    0 ERROR      SQLMON Error: SQLCode = -1032
2007-12-11-14.54.54    0 ERROR      SQLMONSZ Error: SQLCode = -1032