oratop

A Database Monitoring Tool

Jan 2019
 oratop
A text-based user interface utility using Oracle Call Interface (OCI) API that resembles Unix “top”
utility in appearance. Its data gathering is solely from the database using internal views. The
utility can be run against Real Application Cluster (RAC) or non-RAC databases. It provides a
user the ability to monitor the database in near real time and it is not intended to replace Unix
“top”, EMGC, EM Database Express, or server manageability tools like ASH, AWR, ADDM, etc.,
that provides in-depth and granular details.

oratop v15.0.0
INTRODUCTION............................................................................................................................ 3

VISUAL LAYOUT........................................................................................................................... 3

I. COMMAND LINE MODE............................................................................................................. 4

II. INTERACTIVE MODE................................................................................................................ 6

TECHNICAL DETAILS................................................................................................................... 8

CONCLUSION................................................................................................................................ 8

Abstract

oratop can be used to monitor Oracle databases on any platform but the executable
must run on supported Unix platforms with an Oracle compatible client. To monitor
databases on other platforms like Windows, simply define an alias in tnsnames.ora on
a Unix client and connect to the remote database as you would with sqlplus.

Minimum supported Oracle release is 11gR2. A standalone oratop compatible with 11gR2
and 12cR1 Oracle releases is available in MOS Note (Doc ID 1500864.1). For later Oracle
releases it is available under the folder $ORACLE_HOME/suptools/oratop. Also, it is bundled
with Oracle Trace File Analyzer (TFA).

Release 15.0.0

In addition to some bug fixes, some minor columns name, placement, replacement and new
addition changes mostly in the instance section, section2.
Obsoleted Features: Multitenant’s pluggable database (pdb container level) monitoring and
RAC service-based monitoring. Reason is the limited server stats available to the tool.
Security: Login with visible password on the command line or redirection (FIFO pipe) is no
longer permissible, its allowed only at the prompt (hidden).
INTRODUCTION

The Oracle program named oratop allows privileged users to monitor oracle database activities.
It runs dynamically in near real time and provides a live window to a running database. It is
Single instance and RAC aware utility. (see sample snapshot shown in Figure 1 below)

Key motivations include:

• Monitoring current database activities,

• Database performance,
• Identifying contentions and bottleneck

Features Highlights

◦ Process & SQL Monitoring

◦ Real time wait events
◦ Active Data Guard support
◦ Multitenant Database (CDB) support (seed level only)

VISUAL LAYOUT

The “oratop” displays relevant database activity information presented in four sections.

◦ Section 1 DATABASE: Global database information

◦ Section 2 INSTANCE: Database instance Activity
◦ Section 3 EVENT: AWR like “Top 5 Timed Events“
◦ Section 4 PROCESS | SQL: Processes or SQL mode information

Figure 1. oratop text-based user interface (default mode)

Oracle Client Home Environment

Shell environment settings:

$ export ORACLE_HOME=<path>
$ export LD_LIBRARY_PATH=$ORACLE_HOME/lib
$ export PATH=$ORACLE_HOME/bin:$ORACLE_HOME/suptools/oratop:$PATH

Help and Input arguments options

Specific detail of the various options and selection can be obtained using help (or ‘-h’) at the
command line or interactively at runtime (keyboard key press ‘h’).

I. COMMAND LINE MODE

Command line synopsis can be obtained by invoking the utility with “-h” option as shown in
Figure 2.

Figure 2. Command line help

Logon

Connection method is largely similar to sqlplus, however, passwords are not allowed
at the command line, rather the user will be prompted for it. See Figure 2 for tool
usage.

Examples,

$ oratop

User will be prompted to enter credentials.

 • Bequeath1

export ORACLE_SID=<sid>
oratop / as sysdba

• Remote Connection2

TNS
export TNS_ADMIN and connect with a TNS alias name as defined in tnsnames.ora,
or set TWO_TASK to the tns alias and connect without alias name

EZConnect
user will be prompted to enter password

oratop system@rmtdbhost:1530/db1.domain.com

Batch Mode

Batch mode is applicable at the command line with the relevant input options. See Figure 3
below shows output from batch run of 2 cycles in sql mode (section 4).

$ ./oratop / as sysdba -sbn2

Connecting ..
Cycle 1 - oratop: Release 15.0.0 Production on Wed Nov 7 23:58:44 2018

Oracle 19c - sh1 23:58:42 up: 6.2d, 2 ins, 4 sn, 1 us, 10G sga, 2.2%db
ID %CPU %DCP LOAD AAS ASC ASI ASW IDL MBPS %FR PGA UTPS RT/X DCTR DWTR
-------------------------------------------------------------------------------
2 1.8 0.8 2.4 1.1 1 1 0 0 17.5 9 2.3G 85 14m 37 63
1 1.9 0.8 1.3 1.1 1 0 0 1 12.6 6 2.2G 76 13m 37 62

EVENT (C) TOT WAITS TIME(s) AVG_MS PCT WAIT_CLASS

-------------------------------------------------------------------------------
enq: TT - contention 1358 837576 6.2E+05 40 Other
buffer busy waits 3365925 346476 76.9 17 Concurrency
log file sync 27099791 340382 11.9 16 Commit
DB CPU 292332 14
gc buffer busy acquire 17062446 273475 14.9 13 Cluster

ID USER SQL_ID SQL_TEXT X ELAP EXEC ROWS BH% LOAD

-------------------------------------------------------------------------------
2 TPCC 5zbj18g6dz0gk SELECT /*+ INDEX(ord S 8.2m 13k 10 81 1
2 TPCC 98p82tnvq2byn SELECT /*+ USE_NL(cus S 6.2m 5.3k 1 99 1
2 TPCC 8657f3pwh6qax UPDATE STOCK_ITEM SET S 4.3m 2.1k 9 100 1
1 TPCC 4dxgf9wkjvbz8 INSERT INTO ORDL (OL_ S 2.8m 3.1M 9 99 1

Cycle 2 - oratop: Release 15.0.0 Production on Wed Nov 7 23:58:49 2018

Oracle 19c - sh1 23:58:42 up: 6.2d, 2 ins, 4 sn, 1 us, 10G sga, 2.2%db
ID %CPU %DCP LOAD AAS ASC ASI ASW IDL MBPS %FR PGA UTPS RT/X DCTR DWTR
-------------------------------------------------------------------------------

1
Connecting “ / as sysdba“ is allowed only for bequeath connections.
2
The remote database requires setting the parameter “REMOTE_LOGIN_PASSWORDFILE” paired with the
availability of an Oracle password file.
 2 1.8 0.8 2.4 1.1 0 0 1 1 17.5 9 2.3G 85 14m 37 63
1 1.9 0.8 1.3 1.1 0 1 0 1 12.6 6 2.2G 76 13m 37 62

EVENT (C) TOT WAITS TIME(s) AVG_MS PCT WAIT_CLASS

-------------------------------------------------------------------------------
enq: TT - contention 1358 837576 6.2E+05 40 Other
buffer busy waits 3365934 346476 76.9 17 Concurrency
log file sync 27100570 340384 11.9 16 Commit
DB CPU 292351 14
gc buffer busy acquire 17062446 273475 14.9 13 Cluster

ID USER SQL_ID SQL_TEXT X ELAP EXEC ROWS BH% LOAD

-------------------------------------------------------------------------------
1 TPCC 5zbj18g6dz0gk SELECT /*+ INDEX(ord S 18m 1.7k 9 81 1
2 TPCC ah1vrygbhqdry DELETE FROM NORD N WH S 17m 13k 10 100 1
2 TPCC 5zbj18g6dz0gk SELECT /*+ INDEX(ord S 8.2m 13k 10 81 1
2 TPCC awdbudhah7vg3 SELECT /*+ USE_NL(cus S 8.1m 1.1k 1 97 1

Figure 3. Two iterations of batch mode

Note. in RAC environment, while section 2 (instance section) is restricted to the top 5 instances in
the text-based user interface, all of the available instances will be listed in the batch mode.

II. INTERACTIVE MODE

Runtime interactive and detail options can be seen after starting the utility followed by
pressing the keyboard key ‘h’, (See Figure 4 below).

Figure 4. Runtime Options using help (key press ‘h’)

Detailed format (long)

Figure 5. Long format (key press ‘f’) shows expanded and additional information

Miscellaneous

• %DCP

Column “%DCP” (in section 2)

is the database instance cpu
usage as %CPU of the host.

• Values appears in RED color

Values flagged and highlighted in red color are merely a warning or to emphasize
importance

• Exiting3

To quit the program, user may press any of the following keyboard keys: "q" or "Q", or
Esc key or Ctrl+c (to abort)

In all cases, proper OCI session cleanup and logout is performed.

• Unprivileged user
A typical error encountered by a non-privileged user upon connection to the database
using the tool is “ORA-00942: table or view does not exist”

To allow the non-privileged user to use oratop, the system administrator with a DBA role
may issue the following grant: “GRANT SELECT ANY DICTIONARY TO <username>;”
3
Upon exiting the utility and in some situation (corner cases) the program may leave the
terminal (xterm) SHELL environment in an undesirable setting. To restore the terminal to its
original settings is platform specific, e.g. on Linux, the user may issue the command “reset”.
TECHNICAL DETAILS

The “oratop” program is written in C program using Oracle program interface (OCI). It is not
intrusive to a database server, and it leaves small footprints on the server, namely the sqls used
by the program. It employs Unix “termio, “ioctl” libraries, and VT100 escape characters to
achieve cursor control, font colors, program exit control and terminal (xterm) resizing capability.

On the client side, the oratop program is a very light process that uses minimal CPU and
Memory. For the server process, its resources are minimal too but server dependent.

Limitations

• The program is not portable to Windows/NT; it runs on Unix platforms only.

Nevertheless, one can monitor a database running on Windows by connecting remotely
from a compatible Oracle client on Unix.
• The program is compatible with oracle client of the oracle release in use.
oratop from higher Oracle release home can be used also to monitor databases with
lower version.
• Requires server to have been started with the following parameter
statistics_level=TYPICAL4

Caveats

The program may exhibit anomalies at run time, most of which are expected since an event may
occur while the program is in the middle of executing/ fetching operations.

Blank Screen
On a busy server, the following operations may leave the terminal blank for a short period:
 A program initialization
 A terminal resizing (shrink/expand the terminal)
 An instance joining/leaving the cluster
 Quitting interactive keys menus
 Upon exiting the program

Sluggish response to keyboard key press

oratop SQL performance may be impacted on an over loaded systems.
Pressing a keyboard key to interact with the program may appear to have slow response on a
busy server or due to network latency if run remotely. Key press response time may also
depends on the interval/execution state.

Abnormal termination
Like any SQL session, the program may fail due to a server error, and the particular error will
be displayed.

CONCLUSION

The oratop utility provides dba user a quick overview of a running database status and activity. It
aggregates useful diagnostics such as overall database performance from optimal to possible
degradation due bottleneck, badly performing SQLs, potential blocker(s), memory leak, etc.
Furthermore, it can be useful in tuning some aspects of the database, application and user
concurrency.

4
Statistics_level cannot be set to “BASIC” since it will disable the required timed_statistics