Gathering a StatsPack snapshot

  Doc ID:Note:149121.1 Type:TROUBLESHOOTING

Last Revision Status:
  18-MAY-2004 PUBLISHED
Date:
PURPOSE
-------

This note is intended to provide information about the steps required to take a
StatsPack snapshot of current database performance levels and how to capture
different granularities of performance information at both the instance and
session levels. This note also discusses how to automate the process of
capturing a StatsPack snapshot. These snapshots can be used as a starting or
ending point for generating a performance summary.

SCOPE & APPLICATION

-------------------

This note is applicable for Oracle RDBMS releases 8.1.6 and greater, and is
related to the task of gathering database and session level performance
information by using the StatsPack package. This note assumes that the
StatsPack package has already been loaded into the database. This process is
described in Note 149113.1: "Installing and Configuring StatsPack Package".

Gathering a StatsPack snapshot

------------------------------

The simplest interactive way to take a snapshot is to login to SQL*Plus as the

PERFSTAT user, and execute the procedure statspack.snap:

e.g.
SQL> connect perfstat/perfstat
SQL> execute statspack.snap;

Note: In an OPS environment, you must connect to the instance you wish to
collect data for. A snapshot must be taken on each instance so that later
comparisons can be made. A snapshot taken on one instance can only be
compared to another snapshot taken on the same instance.

Although statistics are cumulative ,this will store the current values for the
performance statistics in the StatsPack schema tables, and can be used as a
baseline snapshot for comparison with another snapshot taken at a later time.

For easier performance analysis, set the init.ora parameter timed_statistics to

true; this way, statspack data collected will include important timing
information. The timed_statistics parameter is also dynamically changeable
using the 'alter system' command. Timing data is important and often required
by Oracle support to diagnose performance problems.
Note 30824.1: "Init.ora Parameter "TIMED_STATISTICS" Reference Note"
states that the small amount of overhead from tuning this tracing on is worth
the benefits gained.

Parameters able to be passed in to the statspack.snap and

statspack.modify_statspack_parameter procedures
---------------------------------------------------------

===========================================================================
== Range of Default
Parameter Name Valid Values Value Meaning
===========================================================================
==
i_snap_level 0, 5, 6, 10 5 Snapshot Level
*Level 6 NOT VALID in 8i
*Level 7 is available in 9.2
------------------------------------------------------------------------------
i_ucomment Text Blank Comment to be stored with Snapshot
------------------------------------------------------------------------------
i_executions_th Integer >=0 100 SQL Threshold: number of times
the statement was executed
------------------------------------------------------------------------------
i_disk_reads_th Integer >=0 1,000 SQL Threshold: number of disk reads
the statement made
------------------------------------------------------------------------------
i_parse_calls_th Integer >=0 1,000 SQL Threshold: number of parse
calls the statement made
------------------------------------------------------------------------------
i_buffer_gets_th Integer >=0 10,000 SQL Threshold: number of buffer
gets the statement made
------------------------------------------------------------------------------
i_session_id Valid sid 0 (no Session Id of the Oracle Session
from session) to capture session granular
v$session statistics for
------------------------------------------------------------------------------
i_modify_parameter True, False False Save the parameters specified for
future snapshots?
===========================================================================
==

Configuring the amount of data captured

---------------------------------------

- Snapshot Level

It is possible to change the amount of information gathered by the package,

by specifying a different snapshot 'level'. In other words, the level
chosen (or defaulted) will decide the amount of data collected.

Levels = 0 General performance statistics

Statistics gathered:
This level and any level greater than 0 collects general
performance statistics, such as: wait statistics, system events,
system statistics, rollback segment data, row cache, SGA,
background events, session events, lock statistics,
buffer pool statistics, parent latch statistics.

Levels = 5 Additional data: SQL Statements

This level includes all statistics gathered in the lower level(s),
and additionally gathers the performance data on high resource
usage SQL statements.

SQL 'Thresholds'
The SQL statements gathered by Statspack are those which exceed one of
four predefined threshold parameters:
- number of executions of the SQL statement (default 100)
- number of disk reads performed by the SQL statement (default 1,000)
- number of parse calls performed by the SQL statement (default 1,000)
- number of buffer gets performed by the SQL statement (default 10,000)

The values of each of these threshold parameters are used when

 deciding which SQL statements to collect - if a SQL statement's
resource usage exceeds any one of the above threshold values, it
is captured during the snapshot.

The SQL threshold levels used are either those stored in the table
stats$statspack_parameter, or by the thresholds specified when
the snapshot is taken.

Levels = 6
This level includes all statistics gathered in the lower level(s).
Additionally, it gathers SQL plans and plan usage data for each of the
high resource usage SQL statements captured. Therefore, level 6 snapshots
should be used whenever there is the possibility that a plan may change.
To gather the plan for a SQL statement, the statement must be in the shared
pool at the time the snapshot is taken, and it must exceed one of the SQL
thresholds. To gather plans for all statements in the shared pool, specify
the executions threshold to be zero (0) for those snapshots.

Levels = 10 Additional statistics: Child latches

This level includes all statistics gathered in the lower levels, and
additionally gathers high Child Latch information. Data gathered at
this level can sometimes cause the snapshot to take longer to complete
i.e. this level can be resource intensive, and should only be used
when advised by Oracle personnel.

- Snapshot SQL thresholds

There are other parameters which can be configured in addition to the level.
These parameters are used as thresholds when collecting SQL statements;
if any SQL statements breach the threshold, these are the statements which
are captured during the snapshot.

Snapshot level and threshold information used by the package is stored

in the stats$statspack_parameter table.

- Changing the default values for Snapshot Level and SQL Thresholds

The default parameters used for taking snapshots can be adjusted/modified so

that they better capture data about an instance's workload.

This can be done either by:

o Taking a snapshot, and specifying the new defaults to be saved to the

database (using statspack.snap, and using the i_modify_parameter
input variable).

SQL> execute statspack.snap -

(i_snap_level=>10, i_modify_parameter=>'true');

Setting the i_modify_parameter value to true will save the new

thresholds in the stats$statspack_parameter table; these thresholds
will be used for all subsequent snapshots.

If the i_modify_parameter was false or omitted, the snapshot taken at

that point will use the specified values, any subsequent snapshots
use the preexisting values in the stats$statspack_parameter table.

o Changing the defaults immediately without taking a snapshot, using the

statspack.modify_statspack_parameter procedure. For example to change
 the snapshot level to 10, and the SQL thresholds for buffer_gets and
disk_reads, the following statement can be issued:

SQL> execute statspack.modify_statspack_parameter -

(i_snap_level=>10, i_buffer_gets_th=>10000, i_disk_reads_th=>1000);

This procedure changes the values permananently, but does not

take a snapshot.

The full list of parameters which can be passed into the

modify_statspack_parameter procedure are the same as those for
the snap procedure.

- Specifying a Session Id

If session statistics are needed for a particular session, it is possible to

specify the session id in the call to StatsPack. The statistics gathered for
the session will include session statistics, session events and lock activity.
The default behavior is to not to gather session level statistics.

SQL> execute statspack.snap(i_session_id=>3);

How to automatically gather StatsPack snapshots:

------------------------------------------------

To be able to make comparisons of performance from one day, week or year to

the next, there must be multiple snapshots taken over a period of time. A
minimum of two snapshots are required before any performance characteristics of
the application and database can be made.

The best method to gather snapshots is to automate the collection on a

regular time interval. It is possible to do this:

- Within the database, using the Oracle dbms_job procedure to schedule the
snapshots

- Using Operating System utilities (such as 'cron' on Unix or 'at' on NT) to

schedule the snapshot. Please contact the System Administrator for more
information about using the OS utilities for automating this data collection.

- Scheduling StatsPack snapshots using DBMS_JOB package

To use an Oracle-automated method for collecting statistics, you can use

dbms_job. A sample script on how to do this is supplied in spauto.sql,
which schedules a snapshot every hour, on the hour.

In order to use dbms_job to schedule snapshots, the job_queue_processes

initialization parameter must be set to greater than 0 in the configuration
file used to start the instance for the job to be run automatically.

Example of an init<SID>.ora entry:

# Set to enable the job queue process to start. This allows dbms_job
# to schedule automatic statistics collection using STATSPACK
job_queue_processes=1

If using statsauto.sql in OPS environment, the statsauto.sql script must be

run once on each instance in the cluster. Similarly, the job_queue_processes
 parameter must also be set for each instance.

Changing the interval of statistics collection

-----------------------------------------------
To change the interval of statistics collection use the dbms_job.interval
procedure

e.g.
execute dbms_job.interval(<job number>,'SYSDATE+(1/48)');

Where 'SYSDATE+(1/48)' will result in the statistics being gathered each 1/48
hours (i.e. every half hour).

To force the job to run immediately,

execute dbms_job.run(<job number>);

To remove the autocollect job,

execute dbms_job.remove(<job number>);

For more information on dbms_job, see the Supplied Packages Reference Manual.

To gather a STATSPACK report :

==============================

SQL> connect perfstat/perfstat

SQL> @?/rdbms/admin/spreport

You will be prompted for:

1. The beginning snapshot Id
2. The ending snapshot Id
3. The name of the report text file to be created

Please see Note 149124.1 Creating a StatsPack performance report

for more information

RELATED DOCUMENTS
-----------------
Note 94224.1 - FAQ - STATSPACK COMPLETE REFERENCE
Note 149113.1 - "Installing and Configuring StatsPack Package"
Note 30824.1 - "Init.ora Parameter "TIMED_STATISTICS" Reference Note"