Measuring Performance With the Oracle Dynamic Monitoring System (DMS)

Oracle DMS is a library that enables application and system developers to use a variety of DMS sensors to measure and export customized performance metrics for specific software components (called nouns).

TopLink includes DMS instrumentation in essential objects to provide efficient monitoring of run-time data in TopLink-enabled applications, including both J2EE and non-J2EE applications.

By enabling DMS profiling in a TopLink application (see "Configuring the Oracle DMS Profiler"), you can collect and easily access run-time data that can help you with application administration tasks and performance tuning.

Note:

You should also consider using general performance profilers such as JDeveloper or JProbe to analyze performance problems. These tools can provide more detail that may be required to properly diagnose a problem.

Table 11-1 lists the many performance and status metrics TopLink provides through DMS.

Table 11-2 lists the various profiling levels you can use to adjust the level of profiling to the amount of monitoring information you require. Levels are listed in order of increasing system overhead.

You can easily access DMS data at run time using a management application that supports the Java Management Extensions (JMX) API (see "Accessing Oracle DMS Profiler Data Using JMX") or using any Web browser and the DMS Spy servlet (see "Accessing Oracle DMS Profiler Data Using the DMS Spy Servlet").

Table 11-1 TopLink DMS Metrics

DMS Noun Name^Foot 1	Sensor Name	Level^Foot 2	Description
`Cache`	`CacheHits`	`HEAVY`	Number of times an object looked up in the cache was found.
	`CacheMisses`	`HEAVY`	Number of times an object looked up in the cache was not found.
	`Caching`	`ALL`	Time spent adding, looking up, and removing objects in the cache.
`RCM`^Foot 3	`ChangesNotProcessed`	`ALL`	Number of coordinated cache `ObjectChangeSets` discarded because the object was not found in the cache and was not merged.
	`ChangesProcessed`	`ALL`	Number of coordinated cache `ObjectChangeSets` for which an object was found in the cache and merged.
	`MessagesReceived`	`HEAVY`	Number of cache coordination messages received.
	`MessagesSent`	`HEAVY`	Number of cache coordination messages sent.
	`RemoteChangeSets`	`HEAVY`	Number of change sets received from remote machines and processed.
	`RCMStatus`	`HEAVY`	Cache coordination status: one of `not configured`, `started`, or `stopped`.
`Connection`	`ConnectCalls`	`HEAVY`	Total number of connect calls made.
	`ConnectionsInUse(POOL_NAME)`	`HEAVY`	Number of connections in use for the given connection pool.
	`DisconnectCalls`	`HEAVY`	Total number of disconnect calls made.
	`ConnectionManagement`	`ALL`	Time spent managing connections including connecting, reconnecting, and disconnecting from a data source.
`Query`	`DatabaseExecute`	`ALL`	Time spent in calls to the JDBC `Statement`. Includes time spent in calls to: `close`, `executeUpdate`, and `executeQuery`.
	`DeleteQueries`	`HEAVY`	Time spent executing delete queries, including time spent in JDBC calls.
	`ObjectBuilding`	`ALL`	Time spent building persistent objects from database rows.
	`QueryPreparation`	`ALL`	Time spent preparing a query. Does not include time spent doing SQL prepare.
	`ReadQueries`	`HEAVY`	Time spent executing read queries, including time spent in JDBC calls.
	`RowFetch`	`ALL`	Time spent fetching the JDBC result set from the database and building `DatabaseRecord` objects from the JDBC result set. Includes regular SQL calls and stored procedure calls.
	`SqlGeneration`	`ALL`	Time spent generating SQL. In the case of TopLink expressions, includes time spent converting `Expression` to SQL.
	`SqlPrepare`	`ALL`	Time spent in JDBC preparing the `Statement`. Includes the time spent in EIS creating an `Interaction` associated with a connection, and creating input and output `Record` objects.
	`UpdateQueries`	`HEAVY`	Time spent executing update queries, including time spent in JDBC calls.
	`WriteQueries`	`HEAVY`	Time spent executing write queries, including time spent in JDBC calls.
`Session`	`ClientSession`	`HEAVY`	Number of `ClientSessions` currently logged in.
	`loginTime`	`NORMAL`	Time at which the session was logged in. Once the session is logged out, the sensor no longer appears.
	`SessionName`	`NORMAL`	Name of the session.
	`UnitOfWork`	`HEAVY`	Number of `UnitOfWork` objects acquired from this session.
`Transaction`	`DistributedMerge`	`ALL`	Time spent merging remote transaction changes into the local shared cache.
	`JtsAfterCompletion`	`ALL`	Time spent on JTS `afterCompletion` method.
	`JtsBeforeCompletion`	`ALL`	Time spent on JTS `beforeCompletion` method.
	`MergeTime`	`ALL`	Time spent merging changes into the shared cache.
	`OptimisticLocks`	`HEAVY`	Number of optimistic lock exceptions thrown.
	`Sequencing`	`ALL`	Time spent maintaining the sequence number mechanism and setting the sequence number on objects.
	`UnitOfWorkRegister`	`ALL`	Time spent in registering objects with the `UnitOfWork`.
	`UnitOfWorkCommits`	`ALL`	Time spent in the `UnitOfWork` commit process.
	`UnitOfWorkRollBacks`	`HEAVY`	Number of `UnitOfWork` commits that were rolled back.
`Miscellanous`	`DescriptorEvents`	`ALL`	Time spent by the `DescriptorEventManager` executing a descriptor event.
	`Logging`	`ALL`	Time spent logging TopLink activities.
	`SessionEvents`	`ALL`	Time spent by the SessionEvent manager executing a session event.

^Footnote 1DMS noun names are followed by the name of the session to which they belong. For example, Cache(SESSION_NAME).

^Footnote 2See Table 11-2 for a description of each level setting.

^Footnote 3Cache Coordination

Table 11-2 DMS Metric Collection Levels

Level	Description
`NONE`	Disable collection of all DMS metrics.
`NORMAL`	Enable collection of TopLink DMS metrics. Adds very low overhead. This is the default setting.
`HEAVY`	Enable collection of basic TopLink DMS metrics. Adds about 1 percent overhead.
`ALL`	Enable all possible TopLink DMS metrics. Adds about 3 percent overhead.

Configuring the Oracle DMS Profiler

You configure DMS support in your TopLink application differently depending on the type of application it is:

OC4J Applications
Non-OC4J Applications

OC4J Applications

By default, DMS metric collection is enabled for TopLink CMP applications deployed to OC4J. For BMP or non-CMP applications deployed to OC4J, you must configure DMS metric collection (see "Configuring a Performance Profiler").

TopLink EJB deployed in OC4J are subject to the DMS configuration specified by the OC4J command line-property -Doracle.dms.sensors=<level> where <level> is one of the values listed in Table 11-2.

Non-OC4J Applications

To enable DMS metric collection for TopLink applications deployed to an application sever other than OC4J do the following:

Ensure that the dms.jar file is in your application classpath.

By default, the dms.jar file is located in <ORACLE_HOME>\lib directory.
Set system property oracle.dms.sensors=<level> where <level> is one of the values listed in Table 11-2.
To enable the DMS profiler, select the DMS profiler option when configuring your TopLink session (see "Configuring a Performance Profiler").

Accessing Oracle DMS Profiler Data Using JMX

Using the Java Management Extensions (JMX) API, you can publish DMS profiler run-time data from a managed application (TopLink) to a JMX-compliant management application, by way of EJB-like MBean components.

When you configure your TopLink application to enable run-time services (see "Configuring a Performance Profiler") and you deploy your application to OC4J, the TopLink runtime will deploy a JMX MBean so that a JMX management application can access the DMS profiler run-time data your application publishes.

For code examples that illustrates how to use DMS and JMX, see http://www.oracle.com/technology/tech/java/oc4j/1003/how_to/jmx-enabled-demo.html.

Accessing Oracle DMS Profiler Data Using the DMS Spy Servlet

Once your DMS enabled TopLink application is running, you can access the DMS data it is collecting.

The DMS Spy servlet is available in all Java processes that use DMS. It lets you monitor metrics for a single Java process from a Web browser.

To access DMS data directly using the DMS Spy servlet, do the following:

Ensure that the dms.jar file is in your application classpath.

By default, the dms.jar file is located in <ORACLE_HOME>\lib.
Set the following system properties for the DMS enabled Java process you want to monitor:
```
oracle.dms.publisher.classes=oracle.dms.http.Httpd
oracle.dms.httpd.port.start=<port>
```
where <port> is the HTTP port on which DMS accepts requests (the default value is 46080).
Apply the system property changes by restarting the Java process you want to monitor.
Using a Web browser, connect to the Java process and access the Spy servlet by entering the following URL:
```
http://<host>:<port>/dms0/Spy
```
where <host> is the host name of your Java process and <port> is the value specified by the oracle.dms.httpd.port.start system property.

The Spy servlet displays all TopLink DMS-enabled objects appropriate for the current DMS level setting. Figure 11-1 shows an example of the DMS Spy servlet display.

Figure 11-1 DMS Spy Servlet Display

Description of "Figure 11-1 DMS Spy Servlet Display"