DB2 10.5 for Linux, UNIX, and Windows

db2top - DB2 monitoring tool command

The db2top command provides a unified, single-system view of a multi-partition database or single-partition database on the AIX®, Linux, HP-UX, and Solaris operating systems. Quickly identifies global problems, or specific database partition problems in the system. By combining snapshot information from each database partition, a dynamic realtime view of a running DB2® system is provided.

Scope

db2top can be run in interactive mode or in batch mode.

Authorization

One of the following authorities:

sysadm
sysctrl
sysmaint
sysmon

Required connection

Instance. A connection is not required in replay or client mode.

Command syntax


>>-db2top--+- -A----------------------------+------------------><
           +- -a----------------------------+   
           +- -B----------------------------+   
           +- -b -suboption-----------------+   
           +- -C--suboption-----------------+   
           +- -D--delimiter-----------------+   
           +- -d--database name-------------+   
           +- -f--file </HH:MM:SS><+offset>-+   
           +- -h----------------------------+   
           +- -i--interval in seconds-------+   
           +- -k----------------------------+   
           +- -L----------------------------+   
           +- -m--duration in minutes-------+   
           +- -n--node name-----------------+   
           +- -o--outfile-------------------+   
           +- -P--member_number-------------+   
           +- -p--password------------------+   
           +- -R----------------------------+   
           +- -s--number--------------------+   
           +- -u--username------------------+   
           +- -V--schema--------------------+   
           '- -x----------------------------'

Command parameters

-A

Enables automatic performance analysis. The db2top command produces a top five performance report. Use this option in replay and background mode (-b parameter). Typical usage includes:

Running db2top in collection mode for a long period (for example, 4 hours):

db2top -f collect.file -C -m 240

Running db2top in replay mode with automatic performance analysis. Automatic performance analysis is available for any functions supported in background mode and is based on the default sort criteria specified in the .db2toprc configuration file for the selected suboption (automatic performance analysis is also available in background mode, even when not replaying). As an example, to analyze the most active sessions, issue the following command:

db2top -f collect.file -b l -A

Running db2top in replay mode, jumping to the required point in time to analyze further:

db2top -f collect.file /HH:MM:SS

-a

Specifies that only active objects are displayed.

-B

Displays active objects in bold (reverse) color. This is helpful when the screen does not support colors and colors are set to off in the .db2toprc configuration file.

-b suboption

Runs db2top in background mode. When using the -b parameter, the db2top command displays information in CSV format. db2top can be run in background mode in combination with reading snapshot data from a collection file using the -f file parameter. Issuing multiple sub-options for background mode (-b) is not supported. The -b parameter takes one of the following sub-option values:

d: database
l: sessions
t: tablespaces
b: bufferpools
T: tables
D: Dynamic SQL
s: Statements
U: Locks
u: Utilities
F: Federation
m: Memory pools

The following parameters can only be used with the -b parameter: -X, -L, -A, -s, -D, -o.

-C

Runs db2top in snapshot collector mode. Raw snapshot data is saved in <db2snap-<dbname>-<Machine><bits><.bin> by default (unless -f is specified). Pipe can also be specified for output instead of file. Specifying multiple sub-options for collector mode (-C) are supported. To include locks information in the collection file, use -x along with -C. The -C parameter takes one of the following sub-option values:

b : buffer pools
D : Dynamic SQL
d : database
F : Federation
l : sessions
s : Statements
T : Tables
t : tablespaces
U : Locks

The db2top command runs in replay mode if the -C command parameter is not specified.

-D delimiter

Specifies the field delimiter (single character). Use in background mode (-b parameter).

-d database name

Specifies the database to monitor.

-f file </HH:MM:SS><+offset>

If the -f parameter is not specified, db2top is run in replay mode. If the -f parameter is specified, it indicates output filename. The database name specified with the -d parameter does not need to exist. It is only referenced if you want to issue explains or Dump DB Struct.

In replay mode (-C parameter is not used), if snapshot data has been previously collected in file, offset jumps to a certain point in time in the file. It can be expressed in seconds (+10s), minutes (+10m) or hours (+10h). /HH:MM:SS skips entries until the specified point in time.
In the collector mode (-C parameter is used), you can specify the output filename. </HH:MM:SS><+offset> will be ignored if you are in collector mode

-h

Displays usage information for the db2top command.

-i interval in seconds

Specifies the delay between screen updates. The delay time cannot be less than one second.

-k

Displays actual or delta values. For all functions in delta mode, delta values are computed and displayed on a per second basis regardless of the specified refresh interval.

-L

Specifies that statements that are currently executing or most recent statements from current sessions are captured at each reporting interval specified by the -i parameter. If an SQL statement starts and finishes between an interval, it will not be included.

In the background mode, use -b l -L parameters to catch SQL statements executed in a session and output them to the ALL.sql file in the current working directory.

Currently executing or the most recent SQL statement for a connected session are captured at each interval (as specified by -i parameter). If a SQL statement starts and finishes between an interval, it will not be caught.

-m duration in minutes

Limits the duration of db2top in minutes for -b and -C parameters.

-n node name

Specifies the node to attach to.

-o

Specifies the output file name. Used in background mode (-b parameter).

-P dbpartition number

Specifies the database partition number on which the snapshot will be issued. If the -P parameter is specified and the dbpartition number is not specified, db2top attaches to the default database partition.

-p

Specifies the password used to access the database. If omitted and the -u parameter has been specified, the user is prompted for the password

-R

Resets snapshot at startup.

-s number

Specifies how many samples will be displayed. Only supported in background mode (-b parameter).

-u

Specifies the username used to access the database.

-V schema

Specifies the default schema used in explains.

-x

Specifies whether to display additional counters on session and application screens (might run slower on session).

-X

Specifies format of output is XML. Use in background mode in conjunction with the -b parameter.

Snapshot data collector

The db2top monitoring utility can be run in replay mode, which means it can run against a saved copy of the raw binary snapshot data. To run in replay mode, db2top must be first run in data collector mode, either in batch mode by running db2top from the command line with the -C parameter, or by activating or deactivating data collection from an interactive session by pressing C. This will create a file <db2snap-hostname.bin> in the current directory. Then, the db2top utility can be run against <db2snap-<dbname>-<Machine><bits>.bin> using the -f arguments. The db2top monitoring utility does not need to attach to the DB2 instance in replay mode, which is convenient for remote monitoring. It is possible to limit the content and size of the stream file by specifying any of the sub-options available to the -C parameter.

Examples (batch mode)

The command parameters are as below:
-b l          --> Run in background mode, while catching the "sessions" related 
                  info in db2top
-C            --> run db2top in snapshot collector mode 
-d CUST       --> database
-i 3          --> 3 second interval
-m 60         --> limit duration of db2top to 60 minutes
-n node       --> node 
-o db2top.xml --> output file db2top.xml
-p password   --> password
-s 10000      --> collect 10000 samples
-u userid     --> userid
-V sv9        --> Schema 
-x            --> display additional counters on session

The following example commands monitor a database called "CUST" on a node called "node" with a schema called "sv9". The user ID for the database is "userid", and the password is "password":

The following example command, monitors the database in background mode in three second intervals for sixty minutes and outputs session information in XML format into a file called db2top.xml:
```
db2top -d CUST -n node -u userid -p password -V sv9 -i 3 -b l -X -o db2top.xml -m 60
```
The following example command, monitors the database in background and snapshot collection mode, collecting 10000 samples of session information in XML format. The output binary file is db2snap-CUST-AIX64.bin:
```
db2top -d CUST -n node -u userid -p password -V sv9 -b l -x -s 10000 -X -f db2snap-CUST-AIX64.bin
```
The following example command replays the output capture in the previous example command:
```
db2top -d CUST -f db2snap-CUST-AIX64.bin 
```

For more information, refer to the DB2 problem determination using db2top utility at http://www.ibm.com/developerworks/data/library/techarticle/dm-0812wang/