21 End-To-End Metrics Support

21.1 Introduction

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

• Action—String

• ClientId—String

• ExecutionContextId—String and short SequenceNumber)

• Module—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 DMS; although it is also possible to set metrics using JDBC, metrics set using DMS (Dynamic Monitoring Service) override metrics set using JDBC. To use DMS directly, you must be using a DMS-enabled JAR, which is only available as part of Oracle Application Server.

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. (These metric values would have been updated through the JDBC interface, not through DMS.)

  If DMS metrics are set, then JDBC ignores the end-to-end metric 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.

21.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, the JDBC API is used.

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

• String[] getEndToEndMetrics()throws SQLException;

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

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

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