Skip Headers
Oracle® Database JDBC Developer's Guide and Reference,
11g Release 1 (11.1)

Part Number B31224-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

31 JDBC DMS Metrics

There are two kinds of metrics, end-to-end metrics and Dynamic Monitoring Service (DMS) metrics. End-to-end metrics are used for tagging application activity from the entry into the application code through JDBC to the database and back. DMS metrics are used to measure the performance of application components. Customer use of end-to-end metrics in JDBC is generally discouraged.

This chapter discusses the DMS metrics generated by Oracle JDBC 11.1 in following sections:


Starting with Oracle Database 10g, Oracle Java Database Connectivity (JDBC) supports end-to-end metrics. In Oracle Database 11g Release 1 (11.1), the end-to-end metrics can be set directly by an application only when it is not using a DMS-enabled JAR. But, if your application is using a DMS-enabled JAR, the end-to-end metrics can be set only through DMS. All DMS metrics are available in the following DMS-enabled JARs:

Any other JDBC JAR files do not generate any DMS metrics. The metrics generated in Oracle JDBC 11.1 release are different from 10.2, 10.1, 9.2, and earlier versions of Oracle JDBC as it makes no attempt to retain compatibility with earlier versions. There are also no compatibility modes. A system that is dependent on the exact details of the DMS metrics generated by earlier versions of JDBC may have unexpected behavior when processing the metrics generated by Oracle JDBC 11.1. This is by design and cannot be changed.

Statement metrics can be reported consolidated for all statements in a connection or individually for each statement. All DMS metrics, except those related to individual statements, are enabled at all times.


You can enable or disable the SQLText statement metric. It is disabled by default. If enabled, it is enabled for all statements.

Determining the Type of Metric to be Generated

To determine whether to use consolidated or individual metrics, JDBC checks the DMSConsole sensor weight. If the sensor weight is less than or equal to DMSConsole.NORMAL, then JDBC generates consolidated statement metrics. If the sensor weight is greater than DMSConsole.NORMAL, then JDBC generates individual statement metrics.

JDBC checks the DMSConsole sensor weight when creating a Prepared or Callable statement and depending on the sensor weight at the time the statement is created, the metrics are generated. Changing the value of the sensor weight, after the statement has been created, does not cause a statement to switch between consolidated and individual metrics.


In the presence of statement caching, it may appear that changing sensor weight has no impact as statements are retrieved from the cache rather than created anew.

There is only one list of statement metrics that is generated for both consolidated and individual statement metrics. The only difference between these two lists is the aggregation of the statements. When individual statement metrics are generated, one set of metrics is generated for each distinct statement object created by the JDBC driver. On the other hand, when consolidated statement metrics are generated, all statements created by a given connection use the same set of statement metrics. For example, consider an 'execute' phase event. If individual statement metrics are used, then each statement created will have a distinct 'execute' phase event. So, from two such statements, it will be possible to distinguish the execution statistics for the two separate statements. If one has an execution time of 1 second and the other an execution time of 3 seconds, then there will be two distinct 'execute' phase events, one with a total time and average of 1 second and the other with a total time and average of 3 seconds. But, if consolidated statement metrics are used, all statements will use the single 'execute' phase event common to the connection. So, from two such statements created by the same connection, it will not be possible to distinguish the execution statistics for the two statements. If one has an execution time of 1 second and the other an execution time of 3 seconds, then the common 'execute' phase event will report a total execution time of 4 seconds and an average of 2 seconds.

Generating the SQLText Metric

Depending on the version of DMS, there are two mechanisms for determining the generating of the SQLText statement metrics:

Whether SQLText metric will be generated or not, is independent on the use of the type of statement metrics used, that is, individual statement metrics or consolidated statement metrics

Accessing DMS Metrics Using JMX

JMX (Java Management Extensions) is a Java technology that supplies tools for managing and monitoring applications, system objects, devices, service-oriented networks, and the JVM (Java Virtual Machine). You can easily access DMS metrics at run time using a management application that supports JMX. For more information about using JMX to access DMS data, visit the following link: