30 End-To-End Metrics Support

30.1 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.

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.

30.2 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.

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();