2 Monitoring Oracle Application Server

2.2.1.1 Using the AggreSpy Display

AggreSpy organizes metrics into two areas: DMS Spies and Metric Tables.

• DMS Spies show the available metrics by parent process type and parent process number. By selecting individual DMS Spies, you can view, in text form, all metrics collected for the associated process.

• Metric Tables show the available metrics by metric table type and when multiple OC4Js are running include OC4J metrics from multiple OC4J instances. By selecting individual metric tables you can view, in table form, all metrics of a specified type. For example, metric tables allow you to view the metrics associated with OC4J Servlets, Oracle HTTP Server Modules, and Oracle Process Manager and Notification Server processes.

DMS metric tables are identified by a name, such as ohs_server for the Oracle HTTP Server metrics. In AggreSpy, the term metric table refers to the built-in performance metric table names.

You can access performance metrics using AggreSpy from the following URL:

http://host:port/dms0/AggreSpy

where:

host is the Oracle HTTP Server host, for example, tv.us.oracle.com.

port is the Oracle HTTP Server listener port, for example 7778.

Figure 2-1 shows a sample AggreSpy display. The display shows two frames, one containing a list of DMS Spies and DMS Metric Tables, and one showing selected values for the DMS Spies or the Metric Tables.

AggreSpy provides navigation and display options, including:

• Access DMS Spies and Metric Tables using the links in the left frame.

• Sort rows in metric tables by clicking on the column headings.

• Display a table containing the descriptions of a Metric Table's metrics by clicking the Metric Definitions link shown on each metric table.

You need to refresh your browser to display built-in metric data after you start AggreSpy. When you first use AggreSpy many of the fields, and the complete list of DMS Spies may not contain all of the current Metric Tables. If you wait a short time, and then refresh the display, the data is available and AggreSpy shows the complete list of Metric Tables.

Figure 2-1 AggreSpy Performance Metric Display

Description of "Figure 2-1 AggreSpy Performance Metric Display"

2.2.1.2 AggreSpy URL With a Proxy Server

If your browser is configured to use a proxy server, then to access AggreSpy on the localhost, you need to configure the browser to disable the use of proxies for the localhost. The exact steps required to disable the use of a proxy server for the localhost depends on the browser you use.

2.2.1.3 AggreSpy URL and Access Control

By default, the dms0/AggreSpy URL is redirected and the redirect location is protected, allowing only the localhost (127.0.0.1) to access the AggreSpy Servlet.

To view metrics from a system other than the localhost you need to change the DMS configuration for the system that is running the Oracle Application Server that you want to monitor by modifying the file $ORACLE_HOME/Apache/Apache/conf/dms.conf on UNIX, or %ORACLE_HOME%\Apache\Apache\conf\dms.conf on Windows systems.

Example 2-1 shows a sample default configuration from dms.conf. This configuration limits AggreSpy to access metrics on the localhost (127.0.0.1). The port shown, 7200, may differ on your installation.

# proxy to DMS AggreSpy
Redirect /dms0/AggreSpy http://localhost:7200/dmsoc4j/AggreSpy
#DMS VirtualHost for access and logging control
Listen 127.0.0.1:7200
OpmnHostPort http://localhost:7200
<VirtualHost 127.0.0.1:7200>
ServerName 127.0.0.1

By changing the dms.conf configuration to specify the host that provides, or serves DMS metrics, you can allow users on systems other than the localhost to access the DMS metrics from the location http://host:port/dms0/AggreSpy.

To view metrics from a system other than the localhost (127.0.0.1), do the following:

1. Modify dms.conf by changing the entries with the value for localhost "127.0.0.1" shown in Example 2-1 to the name of the server providing the metrics (obtain the server name from the ServerName directive in the httpd.conf file, for example tv.us.oracle.com).

2. Example 2-2 shows a sample updated dms.conf that allows access from a system other than the localhost (127.0.0.1).

   Example 2-2 Sample dms.conf File for Remote Host Access for DMS Metrics

   # proxy to DMS AggreSpy
   Redirect /dms0/AggreSpy http://tv.us.oracle.com:7200/dmsoc4j/AggreSpy
   #DMS VirtualHost for access and logging control
   Listen tv.us.oracle.com:7200
   OpmnHostPort http://tv.us.oracle.com:7200
   <VirtualHost tv.us.oracle.com:7200>
   ServerName tv.us.oracle.com
   
   

3. Restart, or stop and start the Oracle HTTP Server using Application Server Control Console or using the Oracle Process Manager and Notification Server opmnctl command. For example,

   %opmnctl restartproc process-type=HTTP_Server
   
   
   

   or

   %opmnctl stopproc process-type=HTTP_Server
   %opmnctl startproc process-type=HTTP_Server
   
   
   

2.2.1.4 AggreSpy Limitation When Using Load Balancing With Clusters

AggreSpy does not work as expected when using Oracle Application Server Clusters. When using a cluster, the Oracle HTTP Server mod_oc4j component load balances OC4J requests across Oracle Application Server instances. In this case, AggreSpy may report results for systems that are not the localhost (127.0.0.1).

2.2.2.1 Access Control for dmstool

By default, dmstool shows metrics only when it is run from the localhost (127.0.0.1). If you want to view metrics from an Oracle Application Server running on a remote host, then you need to use dmstool with the -a option, on the local host, and update the dms.conf file of the remote Oracle Application Server instance in the $ORACLE_HOME/Apache/Apache/conf/ directory on UNIX or %ORACLE_HOME%\Apache\Apache\conf\ directory on Windows.

The configuration changes required to control the access to metrics using dmstool are the same as those for accessing dms0/AggreSpy.

<notification-server>
<port local="6100" remote="6200" request="6003"/>
.
.
</notification-server>

2.2.2.2 Using dmstool to List the Names of All Metrics

Every Oracle Application Server performance metric has a unique name. Using dmstool with the –list option produces a list of all metric names. The –list output contains the metric names that you can use with dmstool to request monitoring information for a specific metric or set of metrics.

Using the following command, dmstool displays a list of all metrics available on the server:

% dmstool –list

This command displays a list of the available metrics.

2.2.2.3 Using dmstool to Report Values for Specific Performance Metrics

To monitor a specific metric or set of metrics, use dmstool and include the metric name on the command-line. For example, to monitor the time the JVM has been running, perform the following steps:

1. Use dmstool with the -list option to find the name of the metric that shows the JVM uptime:

   % dmstool -list | grep JVM/upTime.value
   /system1/OC4J:3000:6004/JVM/upTime.value
   
   

2. Use dmstool and supply the full metric name as an argument to show the metric value:

   % dmstool /system1/OC4J:3000:6004/JVM/upTime.value 
   Mon Jul 26 16:20:05 PDT 2004
   /system1/OC4J:3000:6004/JVM/upTime.value     14022008        msecs
   
   

Using dmstool, the default repeat interval is 5 seconds, so this command shows the updated metric value every 5 seconds. Use the -count option to limit the number of times dmstool reports values.

For example:

% dmstool /system1/OC4J:3000:6004/JVM/upTime.value -count 2
Mon Jul 26 11:18:33 PDT 2004
/system1/OC4J:3000:6004/JVM/upTime.value     14336273        msecs

Mon Jul 26 11:18:38 PDT 2004
/system1/OC4J:3000:6004/JVM/upTime.value     14345881        msecs

2.2.2.4 Using dmstool With the Interval and Count Options

To monitor the requests completed for an application over an interval of one minute, use the following dmstool command, supplying metric names on the command-line:

% dmstool -i 60 -c 120 \ /system1/OC4J:3301:6003/oc4j/default/WEBs/processRequest.completed

This command reports 120 sets of output for the metric listed on the command line, while collecting data at intervals of 60 seconds:

Tue Oct 12 14:43:43 PDT 2004
/system1/OC4J:3301:6003/oc4j/default/WEBs/processRequest.completed    8576 ops

Tue Oct 12 14:44:43 PDT 2004
/system1/OC4J:3301:6003/oc4j/default/WEBs/processRequest.completed    8581 ops

Tue Oct 12 14:45:43 PDT 2004
/system1/OC4J:3301:6003/oc4j/default/WEBs/processRequest.completed    8588 ops
.
.
.

2.2.2.5 Using dmstool to Report All Metrics with Metric Values

Using dmstool with the -dump option displays all the metrics from an Oracle Application Server instance to the standard output.

The following command displays all available metrics:

% dmstool –dump

Oracle recommends that you run dmstool with the -dump option periodically, such as every 15 to 20 minutes, to capture and save a record of performance data. If you save performance data over time, this data can assist you if you need to analyze system behavior to improve performance or when problems occur.

2.2.2.6 Using dmstool to Report All Metrics with Metric Values in XML Format

When you need to process metric data, use the format=xml query on the dmstool command line to report all metric values in XML format.

The following command displays all available metrics using XML format:

% dmstool –dump format=xml

2.2.2.7 Using dmstool to Reset Metric Values

When you want to reset metric values, use the reset option on the dmstool command line to reset values for a set of metrics, or for all metrics in a specified metric table.

Using the reset option, Event and phaseEvent metrics are reset to 0, as if they were never updated, and State metrics are reset to the current value (as if they started with the current value).

The following command resets the specified metric:

% dmstool –reset /system1/OC4J:3000:6004/JVM/upTime.value

The following command resets the specified metric table:

% dmstool –reset /system1/OC4J:3000:6004/JVM/upTime.value

2.2.2.8 Using dmstool to View Metrics on a Remote Oracle Application Server System

Using dmstool with the -a option reports the metrics from a remote Oracle Application Server instance.

The following command displays all available metrics and metric values on the Oracle Application Server Instance, as specified with the –a option:

% dmstool –a opmn://system1:6003 -list

Using the dmstool -a option, supply an argument with the prefix opmn:// and include the host name where you want to obtain metrics, and the OPMN request port number. The port specifies the OPMN request port that supplies metrics for Oracle Application Server which is specified the request attribute under the <notification-server> element in $ORACLE_HOME/opmn/conf/opmn.xml on UNIX and %ORACLE_HOME%\opmn\conf\opmn.xml on Windows.