1. How To Install, Setup And Use The AQ Performance Monitor Package DBMS_AQ_MONITOR [ID 1163083.1]
Modified: 22-Mar-2012 Type: BULLETIN Status: PUBLISHED Priority: 3
In this Document
Purpose
Scope and Application
How To Install, Setup And Use The AQ Performance Monitor Package DBMS_AQ_MONITOR
Purpose
Overview
Design Description
Package Specification
AQMonitor Files
Usage
Notes and Restrictions
Plotting the Data Generated
Sample Results
Applies to:
Oracle Server - Enterprise Edition - Version: 10.2.0.1 to 11.2.0.3 - Release: 10.2 to 11.2
Information in this document applies to any platform.
Purpose
The purpose of this document is to provide an overview of the dbms_aq_monitor package which can be used to monitor queue performance and provide statistics on Advanced Queueing (AQ) queue operations within a single instance or Real
Application Cluster (RAC) environment.
Scope and Application
This is intended for anyone who needs to monitor or tune performance in an Advanced Queueing database.
The procedure can be executed in a 10.2 database onwards but note this procedure will only gather detailed performance information on buffered queues in this version. In 11.1 onwards the procedure will gather detailed performance
information for persistent and buffered queues and this information is further enhanced in 11.2 to include notification and Queue Monitor statistics.
How To Install, Setup And Use The AQ Performance Monitor Package DBMS_AQ_MONITOR
Purpose
The purpose of the dbms_aq_monitor package is to provide a comprehensive overview of the AQ setup for specific AQ users within a database and to gather snapshot information in order to assist with tuning and performance issues within
customer systems.
Examples of typical problems would be
1. AQ queries/operations becoming more expensive over time.
2. Unable to scale up performance or unable to meet peak performance numbers.
3. Best-practices for tuning/improving an existing AQ setup.
4. RAC performance problems.
Overview
The PL/SQL package dbms_aq_monitor is designed to monitor AQ queue performance over a certain time duration. A user can define a start and end time during which specific queues can be monitored. The monitor can generate three types of
reports:
A summary report for all queues: The report will display all queue configuration information (such as queue id, queue owner, etc.). It also gives a performance summary for each queue, and sorts queues with different metrics (e.g.,
enqueue rate and dequeue rate).
A detailed report for a certain queue: The report will show the performance of the queue in a time-series manner. It also gives information of other components related to the queue, such as queue monitor cache (11.2) and subscribers.
Furthermore, it shows top SQL associated with the queues and segment usage related to the queue.
In 11.2 onwards a report for subscription/registration statistics: The report will show subscription/registration statistics in a time-series manner.

2. Design Description
The monitor periodically collects statistics from the following AQ views
- dba_queues, dba_queue_tables, dba_queue_subscribers
- gv$persistent_queues, gv$persistent_subscribers, gv$persistent_qmn_cache
- gv$buffered_queues, gv$buffered_subscribers
- gv$subscr_registration_stats
It also collects statistics from the following additional views
- dba_hist_sqlstat, dba_hist_sqltext, dba_hist_seg_stat_obj, dba_hist_seg_stat
- dba_hist_snapshot, dba_hist_sys_time_model, dba_hist_system_event, dba_hist_sysstat
- dba_tables, dba_tablespaces, dba_segments, dba_indexes, dba_lobs, dba_rules, dba_rule_set_rules
- dba_subscr_registrations
The monitor creates 12 tables to store the statistics gathered from these views, in particular:
1. For persistent queues
- aqmon_pqueues_tab
- aqmon_pqueues_accum_tab
- aqmon_psubscribers_tab
- aqmon_pqmncache_tab
2. For buffered queues
- aqmon_bqueues_tab
- aqmon_bqueues_accum_tab
- aqmon_bsubscribers_tab
3. For notification
- aqmon_subreg_tab
4. General Information
- aqmon_queue_config_tab
- aqmon_subscriber_config_tab
- aqmon_queue_owners_tab
- aqmon_params_tab
Package Specification
Set/get Monitor Configuration Procedures
ADD_QUEUE_OWNER Procedure
This procedure adds a queue owner to the monitoring list. The owner name will be automatically capitalized. All queues belonging to that owner will be monitored.
dbms_aq_monitor.add_queue_owner(owner_name IN VARCHAR2 DEFAULT NULL);
add_queue_owner parameters
owner_name - The schema name of the AQ Queue owner.
REMOVE_QUEUE_OWNER Procedure
This procedure removes a queue owner from the monitoring list. The owner name will be automatically capitalized.

3. dbms_aq_monitor.remove_queue_owner(owner_name IN VARCHAR2 DEFAULT NULL);
add_queue_owner parameters
owner_name - The schema name of the AQ Queue owner.
SET_LOG_DIR Procedure
This procedure sets the directory for dumping log files
dbms_aq_monitor.set_log_dir(
dir_name IN VARCHAR2 DEFAULT NULL,
overwrite_file IN BOOLEAN DEFAULT FALSE);
set_log_dir parameters
dir_name - The location where the Monitor log files will be stored
overwrite_file - whether to overwrite existing file if log file 'aqmon_report.log' already exists in the log directory.
SET_MONITORING_PARAM Procedure
This procedure sets thet monitoring parameters
dbms_aq_monitor.set_monitoring_param(param_name IN VARCHAR2 DEFAULT NULL,
param_value IN PLS_INTEGER DEFAULT NULL);
set_monitoring_param parameters
param_name param_value (Default) Usage
CONFIG_COLLECT_FREQ 300(seconds) frequency for collecting queue configuration info
RUNTIME_COLLECT_FREQ 60(seconds) frequency for collecting queue runtime stats
AWR_DUMP_FREQ 300(seconds) frequency for generating AWR
report
ACCUM_DUMP_FREQ 300(seconds) frequency for dumping
accumulative stats in log file
FILE_PLOT 0 whether dump per-queue stats file
for gnuplot. Value could be 0 or 1.
SHARED_SUBSQL_LENGTH 150 AQ generated SQL which shares the same first SHARED_SUBSQL_LENGTH
characters and
SHARED_MEMORY_BOUND 1 in total consume more
than SHARED_MEMORY_BOUND MBytes of memory
SHOW_CONFIG Procedure
The procedure displays the monitor configuration parameters
dbms_aq_monitor.show_config
Monitor Control Procedures
START_MONITOR Procedure

4. This procedure starts the Monitor. When started, the monitor will clear up all previously
collected statistics. It will also overwrite log files in the log directory.
dbms_aq_monitor.start_monitor
(start_time IN NUMBER DEFAULT 0);
start_monitor parameters
start_time - number of minutes after which the monitor will be started
STOP_MONITOR Procedure
This procedure stops all the statistics collecting processes associated with the Monitor. Existing statistics are still kept in database. The monitor will not stop until this procedure is executed.
dbms_aq_monitor.stop_monitor(stop_time IN NUMBER DEFAULT 0);
stop_monitor parameters
stop_time - number of minutes after which the monitor will be stopped
DESTROY_MONITOR Procedure
This procedure clears all the tables and data used by the monitor.
dbms_aq_monitor.destroy_monitor
CLEAR_SCHEDULE_JOB Procedure
This procedure clears the scheduled job. There are two types of scheduled jobs, 'start_monitor'
or 'stop_monitor'. Each type of job could be scheduled only once. If you want to re-schedule the job at a different time, you need to first clear the job and then re-execute the operation.
dbms_aq_monitor.clear_scheduled_job(job_name IN VARCHAR2 DEFAULT NULL);
clear_schedule_job parameters
job_name - can be either 'start_monitor' or 'stop_monitor'
GET_REPORT Procedure
This procedure generates a summary monitoring report for all queues on all instances. The
report file is named 'aqmon_report.log', in the log directory.
dbms_aq_monitor.get_report(final_collect IN BOOLEAN DEFAULT TRUE);
get_report parameters
final_collect - whether to collect one final snapshot before generating the report (only effective when the monitor is still running).
GET_QUEUE_REPORT Procedure
This procedure generates a detailed report for a specific queue on a specific instance.
dbms_aq_monitor.get_queue_report(queue_id IN NUMBER DEFAULT NULL,
inst_number IN NUMBER DEFAULT NULL,
final_collect IN BOOLEAN DEFAULT TRUE,
single_logfile IN BOOLEAN DEFAULT FALSE);
get_queue_report parameters

5. Parameter Description
inst_number If inst_number is not specified (i.e., inst_number IS NULL), then automatically fetch the current instance number. If
inst_number = -1, then generate reports for the queue on all instances.
For other cases, inst_number should be >= 0.
In Oracle database 10.2, inst_number cannot be -1.
final_collect whether to collect one final snapshot before generating report (only effective when the monitor is still running).
single_logfile If set to true, then all output will be written to a
single logfile 'aqmon_all_queues.log'. Otherwise, each queue will have its own log file. The file is named
'aqmon_queue_ABC_XXYY.log', in the log directory, where ABC is the instance number and XXYY is the queue id. Note
that the 'aqmon_report.log' file contains all queue ids information.
GET_ALL_QUEUES_REPORTS Procedure
This procedure generates a detailed report for each of the monitored queues on the specified
instance. Each report name follows that in procedure get_queue_report.
dbms_aq_monitor.get_all_queues_reports(
inst_number IN NUMBER DEFAULT NULL,
final_collect IN BOOLEAN DEFAULT TRUE,
single_logfile IN BOOLEAN DEFAULT FALSE);
Parameter Description
inst_number If inst_number is not specified (i.e., inst_number IS NULL), then automatically fetch the current instance number. If
inst_number = -1, then generate reports for the queue on all instances.
For other cases, inst_number should be >= 0.
In Oracle database 10.2, inst_number cannot be -1
final_collect whether to collect one final snapshot before generating report (only effective when the monitor is still running).
single_logfile If set to true, then all output will be written to a
single logfile 'aqmon_all_queues.log'. Otherwise, each queue will have its own log file. The file is named
'aqmon_queue_ABC_XXYY.log', in the log directory, where ABC is the instance number and XXYY is the queue id. Note
that the 'aqmon_report.log' file contains all queue ids information.
GET_SUBREG_REPORT Procedure
This procedure will generate a report for subscription and registration statistics. The report file is named 'aqmon_subreg.log', in the log directory. This procedure is valid only for Oracle Database version 11.1 or 11.2.
dbms_aq_monitor.get_subreg_report(
final_collect IN BOOLEAN DEFAULT TRUE);
get_subreg_report parameters
final_collect - whether collect one snapshot before generating report (only effective when the monitor is still running)
AQMonitor Files
The Advanced Queueing Monitor files are located in $ORACLE_HOMErdbmsdemo from 11.2.0.2 onwards. The version contained within the zip file which can be downloaded from the following link AQMonitor contains the latest version.
Usage
Connect to the database and load the monitor package as follows
sqlplus /nolog

6. The dbms_aq_monitor package has dependencies on AWR views. If they do not exist then ORA-942 errors will be reported when loading the package. To resolve this run catawr.sql (11.1 onwards) or catsvrm.sql (10.2) as sys with sysdba
privileges and then re-run @aqmonitor.
The script will create up a monitor user (which can be modified as required), create tables used to store AQ performance information and load the monitor package. After this has been completed connect as the monitor user. Add queue owners
to the monitoring list and set any monitoring parameters before starting the monitor. For example, if you are going to run the monitor for several days, you could set relatively large frequency values. In the following example the monitor sets the
log directory to /home/jerry/test (the oracle software owner will require read/write privileges on the directory). If the directory contains old log files, the monitor will overwrite them. The monitor will collect runtime statistics every 600 seconds
and queue configuration statistics every 3600 seconds. It will also dump an AWR report every 3000 seconds, and dump accumulative statistics in log files every 1800 seconds.
SQL> set serveroutput on
SQL> EXEC dbms_aq_monitor.add_queue_owners('A1');
SQL> EXEC dbms_aq_monitor.set_log_dir('/home/jerry/test', TRUE);
SQL> EXEC dbms_aq_monitor.set_monitoring_param('config_collect_freq',3600);
SQL> EXEC dbms_aq_monitor.set_monitoring_param('runtime_collect_freq',600);
SQL> EXEC dbms_aq_monitor.set_monitoring_param('awr_dump_freq', 3000);
SQL> EXEC dbms_aq_monitor.set_monitoring_param('accum_dump_freq', 1800);
SQL> EXEC dbms_aq_monitor.show_config;
SQL> EXEC dbms_aq_monitor.start_monitor
The final step immediately starts the monitor jobs in the background, and all the queues belonging to the user A1 are monitored. You can stop the monitor after a set period of time
SQL > exec dbms_aq_monitor.stop_monitor(60);
The monitor will be automatically stopped after 60 minutes. Alternatively, you could run "exec dbms_aq_monitor.stop_monitor" at any time when you want to stop the monitor.
At any time after the monitor has been started, you can run the following commands to generate reports. You do not need to stop the monitor in order to generate reports.
SQL> exec dbms_aq_monitor.get_report;
SQL> exec dbms_aq_monitor.get_all_queues_reports;
The above commands generate the summary report for all queues, and generate detailed reports for all queues on the current instance.
NOTE: It is recommended to use set serveroutput on when using the above APIs. They will print execution information to the screen.
Notes and Restrictions
1. The queue owner must be added before the monitor is started. Otherwise statistics for new owners will not be collected.
2. Once a monitor is started, all previously collected statistics will be cleared. When the monitor is stopped, collected statistics will not be cleared.
3. At most one monitor instance is allowed at all time. It means that, if start_monitor procedure is successfully executed (in any session), a new monitor instance will be started and all previous monitoring results will be cleared.
4. The monitor instance works across multiple sessions. For example, you could start the monitor in one session, and stop it in another session. A monitor operation can be executed in any session and will have the same effect.
5. Reports could be generated without stopping the monitor. Generating reports doesn't affect ongoing monitoring.
Plotting the Data Generated
If the file_plot parameter is set
SQL > exec dbms_aq_monitor.set_monitoring_param('file_plot', 1);
Then, for each of the queues that detailed queue reports are generated, there is an additional data file. The data file is named 'aqmon_queue_ABC_XXYY.S.T.gnuplot', where ABC stands for the instance number, XXYY stands for the queue id, S
could be '11.1' or '11.2' (depending on the database version), and T could be 'persistent' or 'buffered' (depending on the queue type).
The shell script 'aqmon.plot' can be used to plot monitoring results based on above data files. In order to do this put all the data files into the directory which contains the shell script, and then run the shell script. The script will generate one plot
file for each of the data files. The name of a plot file is the name of the corresponding data file appended by '.png'. Alternatively the data can be loaded into spreadsheet software for further analysis.
Sample Results
Here is a sample plot generated by gnuplot

7. The same data could be imported in a spreadsheet package as an alternative to gnuplot.
Still have questions ?
To discuss this information further with Oracle experts and industry peers, we encourage you to review, join or start a discussion in the My Oracle Support Streams and Distributed Database Community.
The goal of this community is to exchange knowledge and concepts about Oracle Streams Advanced Queuing (AQ) and distributed databases, with special consideration for the components listed below:
- Distributed Databases
- Streams Replication and Advanced Queuing
- Advanced Replication
- XA
To provide feedback on this note, click on the "Rate this document" link above.