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® and Solaris operating systems. It can be used to
quickly identify global problems, or specific database partition problems in the system. By
combining snapshot information from each database partition, the utility can provide a dynamic
real-time view of a running DB2® system.

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

Authorization
One of the following:
 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--delimeter-----------------+   
    +- -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--dbpartition 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 option). 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 .db2toprc 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 desired 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 option, 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> option.
Issuing multiple suboptions for background mode (-b) is not supported. The -b parameter
takes one of the following suboption 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 options can only be used with the -b option: -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 suboptions 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 suboption values:
 b : bufferpools
 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 delimeter
Specifies the field delimiter (single character). Use in background mode (-b option).
-d database name
Specifies the database to monitor.
-f file </HH:MM:SS><+offset>
  If -f is not specified db2top is run in replay mode. If -f is specified it indicates
output filename. The database name specified with -d does not need to exist. It is
only referenced if you want to issue explains or Dump DB Struct.

In replay mode (-C option 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 option 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 option. If an
SQL statement starts and finishes between an interval, it will not be included.

In the background mode, use -b l -L command 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 option). 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.
-nnode name
Specifies the node to attach to.
-o
Specifies the output file name. Used in background mode (-b option).
-P dbpartition number
Specifies the database partition number on which the snapshot will be issued . If -P is
specified and the dbpartition number is not specified, db2top will attach to the default
database partition.
-p
 Specifies the password used to access the database. If omitted and the -u option 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
option).
-u
Specifies the username used to access the database.
-Vschema
Specifies the default schema used in explains.
-x
Specifies whether to display additional counters on session and application screens
(might run slower on session).

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
switch, 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 suboptions available to the -C switch.

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 -f db2snap-CUST-AIX64.bin