Skip Headers

Oracle® Application Server Performance Guide 10g Release 3 (10.1.3) B25213-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# A Monitoring Using Built-in Performance Tools

This appendix includes the following sections:

- Summary of Oracle Application Server Built-in Performance Metrics

- Viewing Performance Metrics Using AggreSpy

- Viewing Performance Metrics Using dmstool

- Viewing Performance Metrics Using AggreSpy (for Standalone OC4J)

- Using Built-in Performance Metrics on Windows Systems

## A.1 Summary of Oracle Application Server Built-in Performance Metrics

You can monitor performance using the Application Server Control Console Performance secondary tab, using the System MBean Browser from the JMX area of the Administration secondary tab, or by viewing the Oracle Application Server built-in performance metrics.

This appendix describes how to view the built-in performance metrics using the Oracle Application Server `AggreSpy` servlet or using the `dmstool` command.

Table A-1 summarizes the built-in tools that allow you to view performance metrics.

Table A-1 Oracle Application Server Built-in Monitoring Commands

Command | Description
--- | ---
`AggreSpy` | `AggreSpy` is a pre-packaged servlet that reports performance metrics for an Oracle Application Server instance. You can only run `AggreSpy` when the home OC4J instance is running. By default the OC4J instance named home supports `AggreSpy`. Note: in some cases the home instance needs to be started to use `AggreSpy`.
`dmstool` | Allows you to monitor a specific performance metric, a set of performance metrics, or all performance metrics. Options allow you to specify a reporting interval to report the requested metrics. This command also allows you to show a text report listing all the built-in performance metrics available on the site. The `dmstool` command is located in the directory `$ORACLE_HOME/bin` on UNIX systems and in `%ORACLE_HOME%`\bin on Windows systems.

See Also: Appendix C, "Performance Metrics"

## A.2 Viewing Performance Metrics Using AggreSpy

The `AggreSpy` Servlet displays metrics for Oracle Application Server processes, including: Oracle HTTP Server, OC4J, Oracle Process Manager and Notification Server, and other Oracle Application Server component processes.

This section covers the following topics:

- Using the AggreSpy Display

- AggreSpy URL With a Proxy Server

- AggreSpy URL and Access Control

- AggreSpy Limitation When Using Load Balancing With Multiple Instances

### A.2.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.

Note: To view DMS metrics using `AggreSpy`, you may need to configure your browser to disable the use of a proxy for the localhost, if your system is configured to use proxies. By default Oracle Application Server only allows access for the localhost. See "AggreSpy URL With a Proxy Server" for details.

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 `7777`.

Note: You can only run `AggreSpy` when the home OC4J instance is running. By default, the OC4J instance named home supports `AggreSpy`. Using an OracleAS Infrastructure, the home instance needs to be started to use `AggreSpy`, since by default the home instance is installed with OracleAS Infrastructure, but it is not started.

Figure A-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.

Note: The OC4J home instance must be running to use `AggreSpy`. When the home instance is down, requests to `AggreSpy`, http://<`host`>:<`port`>:/dms0/AggreSpy, report an HTTP 500 Internal Server error. In the J2EE install, the home instance starts up with the command, `opmnctl startall`, or by clicking Start using Application Server Control Console.

Figure A-1 AggreSpy Performance Metric Display

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

### A.2.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.

### A.2.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 A-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.

Example A-1 Sample dms.conf File for localhost Access for DMS Metrics

    # 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://127.0.0.1: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.

Caution: Modifying `dms.conf` has security implications. Only modify this file if you understand the security implications for your site. By exposing metrics to systems other than the localhost, you allow other sites to potentially view critical Oracle Application Server internal status and runtime information.

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 A-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 A-2 shows a sample updated `dms.conf` that allows access from a system other than the localhost (127.0.0.1).

   Example A-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 `opmnctl` command. For example,

       %opmnctl restartproc process-type=HTTP_Server

   or

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

See Also: Oracle Application Server Security Guide for information on Oracle HTTP Server access control

### A.2.4 AggreSpy Limitation When Using Load Balancing With Multiple Instances

`AggreSpy` does not work as expected when using Oracle Application Server with multiple instances. When the Oracle HTTP Server `mod_oc4j` component load balances OC4J requests across multiple instances, `AggreSpy` may report results for systems that are not the localhost (127.0.0.1).

Note: In this case it is recommended that you use `dmstool` instead of `AggreSpy`.

## A.3 Viewing Performance Metrics Using dmstool

The `dmstool` command allows you to view a specific performance metric, a set of performance metrics, or all performance metrics for an Oracle Application Server instance. The `dmstool` command also supports an option that allows you to set a reporting interval, specified in seconds, to report updated metrics every t seconds.

For example, you can monitor the performance of a specific servlet, JSP, EJB, EJB method, or database connection and you can request periodic snapshots of metrics specific to these components.

The format for using `dmstool` to display built-in performance metrics is:

    % dmstool [options] metric metric ...

or

    % dmstool [options] –list

or

    % dmstool [options] –dump

Table A-2 lists the `dmstool` command-line `options`. Following Table A-2 this section presents examples that show sample usage with specific performance metrics. The `dmstool` command is located in the `$ORACLE_HOME/bin` directory on UNIX or in `%ORACLE_HOME%\bin` directory on Windows.

Note: You can use `dmstool` in scripts or in combination with other monitoring tools to gather performance data, to check application performance, or to build tools that modify your system based on the values of performance metrics.

See Also: "Using dmstool to List the Names of All Metrics" Appendix C, "Performance Metrics" for a list and description of the DMS metrics

### A.3.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`.

See Also: "AggreSpy URL and Access Control"

Table A-2 dmstool Command-line Options

Option | Description
--- | ---
`-a[ddress] opmn://` `host``[:``port`] | By default, without the -`a` option, `dmstool` gets metrics from the Oracle Application Server instance with the same $ORACLE_HOME as `dmstool`. When `dmstool` runs in the same $ORACLE_HOME as the Oracle Process Manager and Notification Server, OPMN, the `-a` option is not required. You can specify –`a` with the `opmn://` prefix and the arguments shown to monitor the Oracle Application Server processes under OPMN control that produce DMS metrics (some OPMN controlled processes, for example Oracle Application Server Web Cache, do not expose DMS metrics). Where: `host` is the domain name or IP address of the host on which the OPMN process is running. `port` specifies the OPMN request port that supplies metrics. The request port is specified in `$ORACLE_HOME/opmn/conf/opmn.xml.` For example, the following shows the specification in `opmn.xml` for a request port (request="6003"):
    <notification-server>
    <port local="6100" remote="6200" request="6003"/>
    .
    .
    </notification-server>
Note, if you use dmstool -a to request metrics from a remote system, the system must be configured to provide metrics (by default you can access DMS metrics on the localhost). See Also: "AggreSpy URL and Access Control"
`-c[ount]` `num` | Specifies the number of times to retrieve values when monitoring metrics. If not specified, `dmstool` continues retrieving metric values until the process is stopped. The –`count` option is not used with the –`list` option.
`-dump [format=xml]` | Using `dmstool` with the -`dump` option reports all the available metrics on the standard output. Oracle recommends that you run with the -`dump` option periodically, such as every 15 to 20 minutes, to capture and save a record of performance data for your Oracle Application Server server. The -dump option also supports the `format=xml` query. Using this query at the end of the command line supplies the metric output in XML format.
`-help` | List the `dmstool` command-line options.
`-i[nterval]` `secs` | Specifies the number of seconds to wait between metric retrievals. The default is 5 seconds. The `interval` argument is not used with the –`list` option. The interval specified is approximate. Note: if the system load is high, the actual interval may vary from the interval specified using the –`interval` option.
`-l[ist] [-table]` | Generates a list of all metrics available. Use the `-list` option with the `-table` option to display a list of all the metric table names. Note, including metric names on the command-line is not valid when using the –`list` option with `dmstool`.
`-reset [-table` `metric_table``]` | Resets the specified metrics or with the -table option, all of the metrics contained in the specified metric table. Event and phaseEvent metrics are reset to 0 (as if they were never updated). State metrics are reset to the current value (as if they started with the current value). Note: The `reset` option may reset information that Application Server Control Console uses to compute and report values.
`-table` `metric_table` | Includes all the performance metrics for the specified metric table with the name, `metric_table`. See Appendix C, "Performance Metrics" or run `AggreSpy` for a list of metric table names.

### A.3.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.

See Also: Appendix C, "Performance Metrics"

### A.3.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:12502:6100/JVM/upTime.value

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

       % dmstool /system1/OC4J:12502:6100/JVM/upTime.value
         Wed Dec 21 15:37:08 PST 2005
       /system1/OC4J:12502:6100/JVM/upTime.value   159312  msecs

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

For example:

    % dmstool /system1/OC4J:12502:6100/JVM/upTime.value -count 2Wed Dec 21 15:39:38 PST 2005/system1/OC4J:12502:6100/JVM/upTime.value   310031  msecsWed Dec 21 15:39:43 PST 2005/system1/OC4J:12502:6100/JVM/upTime.value   314516  msecs

Note: In some cases, the full path of a metric name may contain a space. If the path contains a space, the space must be quoted on the `dmstool` command line, so that the shell sends the metric name to `dmstool` as a single argument.

### A.3.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
    .
    .
    .

### A.3.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.

### A.3.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

### A.3.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

Note: The `reset` option may reset information that Application Server Control Console uses to compute and report values.

### A.3.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.

Note: By default the Oracle Application Server only allows `dmstool` to access metrics from the localhost. You need to modify `dms.conf` to support access from systems other than the localhost. See "AggreSpy URL and Access Control" for information on DMS access control.

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.

See Also: "AggreSpy URL and Access Control"

## A.4 Viewing Performance Metrics Using AggreSpy (for Standalone OC4J)

When you are using OC4J in standalone mode, without the Oracle Application Server, the `AggreSpy` Servlet allows you to access OC4J metrics.

When running OC4J standalone, access performance metrics using `AggreSpy` from the following URL:

    http://myhost:myport/dms0/AggreSpy

Note: You can only run `AggreSpy` when OC4J is configured to support it, and OC4J is running. By default, OC4J supports `AggreSpy`.

Table A-3 covers the dmstool option that only applies to OC4J standalone mode. In addition, the options shown in Table A-2 also apply to dmstool (except the -a option with the `opmn://` prefix.

Table A-3 dmstool Command-line Options (for Standalone OC4J only)

Option | Description
--- | ---
`-a[ddress]` `host``[:``port`][`path`],... | For a standalone OC4J system, use the -`a` option. This specifies the http:// protocol, where: `host` is the domain name or IP address of the host on which the Oracle HTTP Server is running and `port` specifies the associated port.

## A.5 Using Built-in Performance Metrics on Windows Systems

Using Oracle Application Server on Windows systems, statistics collection needs to be enabled to view certain DMS metrics. If some DMS metrics report the value "0" for values that you expect to be other than 0, then statistics collection may be disabled on your system. To enable statistics collection on Windows systems where statistics collection is disabled, set the value of the following registry entry to 0.

    HKEY_LOCAL MACHINE\SYSTEM\CurrentControlSet\Services\PerfProc\Performance\Disable Performance Counters

Note: Incorrectly editing the registry may severely damage your system. At the very least, you should back up any valued data on the computer before making changes to the registry.