30 End-To-End Metrics Support

Oracle Java Database Connectivity (JDBC) now supports end-to-end metrics when used with Oracle Database 10g. This chapter discusses end-to-end metric support. It contains the following sections:

Introduction

JDBC supports four end-to-end metrics, all of which are set on a per-connection basis:

  • Action

    This is a String

  • ClientId

    This is a String

  • ExecutionContextId

    This is a combination of String and short SequenceNumber)

  • Module

    This is a String

All of these metrics are set on a per-connection basis. All operations on a given connection share the same values. Applications normally set these metrics using Dynamic Monitoring Service (DMS). Although it is also possible to set metrics using JDBC, metrics set using DMS override metrics set using JDBC. To use DMS directly, you must be using a DMS-enabled Java Archive (JAR), which is only available as part of Oracle Application Server.

Table 30-1 lists the maximum size for each end-to-end metric.

Note:

If you are using a DMS-enabled JDBC JAR file, then you must include the JAR file for DMS, dms.jar, in your CLASSPATH. The DMS-enabled JDBC JAR file and the DMS JAR file must come from the same Oracle Database release.

Table 30-1 Maximum Lengths for End-to-End Metrics

Metric Maximum length

ACTION

32

CLIENTID

64

ECID (string component)

64

MODULE

48


When a connection is created, the JDBC drivers check DMS for end-to-end metrics. It only makes this check once during the lifetime of the connection.

If DMS metrics are not set, then JDBC never checks DMS for metrics again. Thereafter, each time JDBC communicates with the database, it sends any updated metric values to the database.

If DMS metrics are set, then JDBC ignores the end-to-end metric application programming interface (API) described in this chapter. Thereafter, each time JDBC communicates with the database, it checks with DMS for updated metric values, and, if it finds them, propagates them to the database.

If no metrics are set, then no metrics are sent to the database.

JDBC API For End-To-End Metrics

If DMS is not in use, either because a non-DMS JAR is in use or because no metric values were set in DMS, then the JDBC API is used.

The JDBC API defines the following constants and methods on OracleConnection:

  • String[] getEndToEndMetrics() throws SQLException

    Returns the end-to-end metrics.

  • void setEndToEndMetrics(String[] metrics, short sequenceNumber) throws SQLException

    Sets the end-to-end metrics.

  • END_TO_END_ACTION_INDEX

    The index of the ACTION metric within the String array of metrics.

  • END_TO_END_CLIENTID_INDEX

    The index of the CLIENTID metric within the String array of metrics.

  • END_TO_END_MODULE_INDEX

    The index of the MODULE metric within the String array of metrics.

  • END_TO_END_ECID_INDEX

    The index of the string component of the execution context (ECID) metric within the String array of metrics. This component is not used by Oracle Database 10g.

  • END_TO_END_STATE_INDEX_MAX

    This is the size of the String array containing the metric values.

  • short getEndToEndECIDSequenceNumber()

    Returns the current value of the SequenceNumber component of the ECID. This component is not used by Oracle Database 10g.

To unset the metrics, pass an array of appropriate size with all null values and the value Short.MIN_VALUE as the sequence number.

Example 30-1 illustrates how to use JDBC API for end-to-end metrics.

Example 30-1 Using the JDBC API for End-to-End Metrics

ods.setUrl(
"jdbc:oracle:oci:@(DESCRIPTION=
  (ADDRESS=(PROTOCOL=TCP)(HOST=cluster_alias)
    (PORT=1521))
    (CONNECT_DATA=(SERVICE_NAME=service_name)))");
ods.setUser("scott");
Connection conn = ods.getConnection();  

String metrics[] = new String[OracleConnection.END_TO_END_STATE_INDEX_MAX];
metrics[END_TO_END_ACTION_INDEX] = "Spike";
metrics[END_TO_END_MODULE_INDEX] = "Buffy";
// Set these metrics
conn.setEndToEndMetrics(metrics, (short) 0);
// Do some work
// Update a metric
metrics[END_TO_END_MODULE_INDEX] = "Faith";

conn.setEndToEndMetrics(metrics, (short) 0);
// Retrieve metrics
new String[] newMetrics = conn.getEndToEndMetrics();