implement OpenTelemetry stable semantic conventions

Author: MouhsinElmajdouby

ojdbc-provider-observability/README.md

@@ -12,29 +12,112 @@ will publish these events into Open Telemetry. These events include:
  * AC begin and success
  * VIP down event
 
-The following attributes are added the traces for each event:
- * **Roundtrips**
-    * Connection ID
-    * Database Operation
-    * Database User
-    * Database Tenant
-    * SQL ID
-    * Original SQL Text *(only present if sensitive data is enabled)*
-    * Actual SQL Text *(only present if sensitive data is enabled)*
-  * **AC begin and success**
-    * Error Message
-    * Error code
-    * SQL state
-    * Current replay retry count
-  * **VIP down event**
-    * Error message
-    * VIP address
-    * Protocol *(only present if sensitive data is enabled)*
-    * Host *(only present if sensitive data is enabled)*
-    * Port *(only present if sensitive data is enabled)*
-    * Service name *(only present if sensitive data is enabled)*
-    * SID *(only present if sensitive data is enabled)*
-    * Connection data *(only present if sensitive data is enabled)*
+## Semantic Conventions (OpenTelemetry Tracer)
+
+The OpenTelemetry tracer supports both **stable** and **experimental** (legacy)
+OpenTelemetry semantic conventions for Oracle Database instrumentation.
+
+### Semantic Convention Migration
+
+The OpenTelemetry tracer supports three modes controlled by the `OTEL_SEMCONV_STABILITY_OPT_IN`
+environment variable:
+
+* **Empty/Not Set (default)** - Emits only experimental (legacy) conventions for backward compatibility
+* **`database`** - Emits only the new stable Oracle Database semantic conventions
+* **`database/dup`** - Emits both old and new conventions (dual mode for gradual migration)
+
+This configuration can be set via environment variable or changed at runtime through the MBean interface.
+
+See the [OpenTelemetry Database Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/)
+for details on the stable conventions.
+
+### Roundtrip Events
+
+#### Stable Conventions
+When `OTEL_SEMCONV_STABILITY_OPT_IN=database` or `database/dup`:
+
+* **Required/Recommended Attributes**
+    * `db.system.name` - Always set to `"oracle.db"`
+    * `db.namespace` - Format: `{instance_name}|{database_name}|{service_name}`
+    * `db.operation.name` - Database operation being executed
+    * `db.query.summary` - Low cardinality query summary (SQL type)
+    * `server.address` - Database server hostname
+    * `server.port` - Database server port (if non-default, i.e., not 1521)
+    * `oracle.db.query.sql.id` - Oracle SQL_ID
+    * `oracle.db.session.id` - Oracle session ID
+    * `oracle.db.server.pid` - Oracle server process ID
+    * `oracle.db.shard.name` - Oracle shard name (if applicable)
+    * `thread.id` - Current thread ID
+    * `thread.name` - Current thread name
+
+* **Opt-In Attributes** *(only present if sensitive data is enabled)*
+    * `db.user` - Database user name
+    * `db.query.text` - Actual SQL query text
+    * `db.response.returned_rows` - Number of rows returned
+
+* **Error Attributes** *(only present on errors)*
+    * `error.type` - Exception class name (e.g., `java.sql.SQLSyntaxErrorException`)
+    * `db.response.status_code` - Oracle error code (format: `ORA-XXXXX`)
+
+#### Legacy Conventions
+When `OTEL_SEMCONV_STABILITY_OPT_IN` is empty/not set or `database/dup`:
+
+* `Connection ID`
+* `Database Operation`
+* `Database Tenant`
+* `SQL ID`
+* `thread.id`
+* `thread.name`
+* `Database User` *(only present if sensitive data is enabled)*
+* `Original SQL Text` *(only present if sensitive data is enabled)*
+* `Actual SQL Text` *(only present if sensitive data is enabled)*
+
+### Application Continuity (AC) Replay Events
+
+#### Stable Conventions
+When `OTEL_SEMCONV_STABILITY_OPT_IN=database` or `database/dup`:
+
+* `db.system.name` - Always set to `"oracle.db"`
+* `error.type` - Error message that triggered replay
+* `db.response.status_code` - Oracle error code (format: `ORA-XXXXX`)
+* `db.operation.batch.size` - Current replay retry count
+
+#### Legacy Conventions
+When `OTEL_SEMCONV_STABILITY_OPT_IN` is empty/not set or `database/dup`:
+
+* `Error Message`
+* `Error code`
+* `SQL state`
+* `Current replay retry count`
+
+### VIP Retry Events 
+
+#### Stable Conventions
+When `OTEL_SEMCONV_STABILITY_OPT_IN=database` or `database/dup`:
+
+* `db.system.name` - Always set to `"oracle.db"`
+* `error.type` - Error message that triggered VIP retry
+* `server.address` - VIP address being retried
+
+**Opt-In VIP Debug Attributes** *(only present if sensitive data is enabled)*:
+* `server.port` - Server port number
+* `oracle.db.vip.protocol` - Connection protocol
+* `oracle.db.vip.failed_host` - Host that failed during VIP retry
+* `oracle.db.vip.service_name` - Oracle service name
+* `oracle.db.vip.sid` - Oracle System Identifier (SID)
+* `oracle.db.vip.connection_descriptor` - Full connection descriptor
+
+#### Legacy Conventions
+When `OTEL_SEMCONV_STABILITY_OPT_IN` is empty/not set or `database/dup`:
+
+* `Error message`
+* `VIP Address`
+* `Protocol` *(only present if sensitive data is enabled)*
+* `Host` *(only present if sensitive data is enabled)*
+* `Port` *(only present if sensitive data is enabled)*
+* `Service name` *(only present if sensitive data is enabled)*
+* `SID` *(only present if sensitive data is enabled)*
+* `Connection data` *(only present if sensitive data is enabled)*
 
 ## Installation
 
@@ -69,6 +152,17 @@ oracle.jdbc.provider.traceEventListener.unique_identifier=<unique identifier>
 
 If no unique identifier is provided, the unique idetifier "default" is used.
 
+### Enabling Stable Semantic Conventions (OpenTelemetry)
+
+To use the new stable OpenTelemetry semantic conventions, set the environment variable:
+```bash
+# Use only stable conventions
+export OTEL_SEMCONV_STABILITY_OPT_IN=database
+
+# OR use both old and new conventions (dual mode for migration)
+export OTEL_SEMCONV_STABILITY_OPT_IN=database/dup
+```
+
 ## Configuration
 
 The provider can be configured by: 

ojdbc-provider-observability/src/main/java/oracle/jdbc/provider/observability/ObservabilityConfiguration.java

@@ -108,12 +108,32 @@ public class ObservabilityConfiguration implements ObservabilityConfigurationMBe
    */
   public static final String OPEN_TELEMETRY_TRACE_EVENT_LISTENER_SENSITIVE_ENABLED = "oracle.jdbc.provider.opentelemetry.sensitive-enabled";
 
+  /**
+   * OpenTelemetry semantic convention stability opt-in environment variable.
+   * Accepts a comma-separated list of values including:
+   * "database" (new stable conventions only),
+   * "database/dup" (both old and new conventions),
+   * or empty/null (old conventions only)
+   */
+  public static final String OTEL_SEMCONV_STABILITY_OPT_IN = "OTEL_SEMCONV_STABILITY_OPT_IN";
+
+
   /**
    * Default values
    */
   private static final String DEFAULT_ENABLED_TRACERS = "OTEL,JFR";
   private static final String DEFAULT_SENSITIVE_DATA_ENABLED = "false";
   private static final String DEFAULT_OPEN_TELEMETRY_ENABLED = "true";
+  private volatile String semconvOptIn = "";
+
+  public String getSemconvOptIn() {
+    return semconvOptIn == null ? "" : semconvOptIn;
+  }
+
+  public void setSemconvOptIn(String optIn) {
+    this.semconvOptIn = optIn == null ? "" : optIn;
+  }
+
 
   /**
    * Lock used to ensure that only one thread can access the configuration at a time.
@@ -173,6 +193,8 @@ public ObservabilityConfiguration() {
   ObservabilityConfiguration(ObservabilityConfigurationType configurationType) {  
     String enabledTracers = DEFAULT_ENABLED_TRACERS;
     String sensitiveDataEnabled = DEFAULT_SENSITIVE_DATA_ENABLED;
+    String optIn = System.getenv(OTEL_SEMCONV_STABILITY_OPT_IN);
+
     if (ObservabilityConfigurationType.OBSERVABILITY.equals(configurationType)) {
       enabledTracers = System.getProperty(ENABLED_TRACERS, DEFAULT_ENABLED_TRACERS);
       sensitiveDataEnabled = System.getProperty(SENSITIVE_DATA_ENABLED, DEFAULT_SENSITIVE_DATA_ENABLED);
@@ -190,6 +212,8 @@ public ObservabilityConfiguration() {
 
     setEnabledTracers(enabledTracers);
     setSensitiveDataEnabled(Boolean.parseBoolean(sensitiveDataEnabled));
+    this.setSemconvOptIn(optIn);
+
   }
 
   /**

ojdbc-provider-observability/src/main/java/oracle/jdbc/provider/observability/ObservabilityConfigurationMBean.java

@@ -93,4 +93,8 @@ public interface ObservabilityConfigurationMBean {
    * @param sensitiveDataEnabled true to enable sensitive data, otherwise false.
    */
   void setSensitiveDataEnabled(boolean sensitiveDataEnabled);
+
+  String getSemconvOptIn();
+  void setSemconvOptIn(String optIn);
+
 }