Observability provider

.github/workflows/run-tests.yaml

@@ -119,6 +119,12 @@ jobs:
           JACKSON_OSON_PASSWORD=${{ secrets.TEST_JACKSON_OSON_PASSWORD }}\n
           " >> ojdbc-provider-jackson-oson/test.properties
 
+          # Generate ojdbc-provider-observability/test.properties
+          echo -e "OBSERVABILITY_URL=${{ secrets.TEST_JACKSON_OSON_URL }}\n
+          OBSERVABILITY_USERNAME=${{ secrets.TEST_JACKSON_OSON_USERNAME }}\n
+          OBSERVABILITY_PASSWORD=${{ secrets.TEST_JACKSON_OSON_PASSWORD }}\n
+          " >> ojdbc-provider-observability/test.properties
+
       - name: Run tests with Maven
         run: mvn -B test --file pom.xml
 
@@ -133,3 +139,4 @@ jobs:
           rm ojdbc-provider-azure/test.properties
 
           rm ojdbc-provider-jackson-oson/test.properties
+          rm ojdbc-provider-observability/test.properties

ojdbc-provider-observability/README.md

@@ -0,0 +1,122 @@
+# Oracle JDBC Observability Provider
+
+This module contains a provider that adds tracing capabilities to the Oracle 
+JDBC driver. Two tracers are available:
+  * OTEL: adds Open Telemetry tracing capabilities.
+  * JFR: exports events to Java Flight Recorder.
+
+This provider implements the TraceEventListener interface provided by the JDBC
+driver which will be notified whenever events are generated in the driver and 
+will publish these events into Open Telemetry. These events include:
+ * roundtrips to the database server
+ * AC begin and sucess
+ * VIP down event
+
+The following attributes are added the 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)*
+
+## Installation
+
+This provider is distributed as single jar on the Maven Central Repository. The 
+jar is compiled for JDK 8, and is forward compatible with later JDK versions. 
+The coordinates for the latest release are:
+
+```xml
+<dependency>
+  <groupId>com.oracle.database.jdbc</groupId>
+  <artifactId>ojdbc-provider-observability</artifactId>
+  <version>1.0.3</version>
+</dependency>
+```
+
+## Usage 
+
+To use the Oracle JDBC observability provider just add the artifact to the
+application's classpath and set the following connection property:
+
+```java
+oracle.jdbc.provider.traceEventListener=observability-trace-event-listener-provider
+```
+
+## Configuration
+
+The provider can be configured by: 
+* using the singleton configuration class,
+```java
+ObservabilityConfiguration.getInstance().setEnabledTracers("OTEL,JFR");
+ObservabilityConfiguration.getInstance().setSensitiveDataEnabled(true);
+```
+* using system properties,
+```java
+System.setProperty("oracle.jdbc.provider.observability.enabledTracers", "OTEL,JFR");
+System.setProperty("oracle.jdbc.provider.observability.sensitiveDataEnabled", "true");
+```
+* or using the MBean.
+```java
+ObjectName objectName = new ObjectName(
+    "com.oracle.jdbc.provider.observability:type=ObservabilityConfiguration");
+MBeanServer server = ManagementFactory.getPlatformMBeanServer();
+server.setAttribute(objectName, new Attribute("EnabledTracers", "OTEL,JFR"));
+server.setAttribute(objectName, new Attribute("SensitiveDataEnabled", "true"));
+```
+
+## Backward compatibility
+
+### Usage
+
+The provider can also be used by setting the following connection property:
+
+```java
+oracle.jdbc.provider.traceEventListener=open-telemetry-trace-event-listener-provider
+```
+
+When this property is used only the OTEL tracer can be used.
+
+### Configuration
+
+To ensure backward compatibility Oracle JDBC provider for Open Telemetry configuration
+properties and MBean have been kept. When these properties and MBean are used only
+the Open Telemetry tracer will be enabled.
+
+The Oracle JDBC provider for Open Telemetry can be configured using system properties 
+or a MBean. Two parameters can be configured: 
+  * **Enabled**: when enabled (*true*) traces will be exported to Open 
+ Telemetry. This property is **enabled by default**.
+  * **Sensitive data enabled**: when enabled (*true*) attributes containing
+ sensitive information like SQL statements and connection URL will be included
+ in the traces. This property is **disabled by default**.
+
+The system properties are "oracle.jdbc.provider.opentelemetry.enabled" and 
+"oracle.jdbc.provider.opentelemetry.sensitive-enabled" respectively and the MBean 
+with object name "com.oracle.jdbc.extension.opentelemetry:type=OpenTelemetryTraceEventListener"
+exposes two attributes "Enabled" and "SensitiveDataEnabled".
+
+ The sample code below shows how to retrieve the value of an attribute:
+```java
+ObjectName objectName = new ObjectName(
+    "com.oracle.jdbc.extension.opentelemetry:type=OpenTelemetryTraceEventListener");
+MBeanServer server = ManagementFactory.getPlatformMBeanServer();
+boolean isEnabled = Boolean.valueOf(server.getAttribute(objectName, "Enabled").toString())
+    .booleanValue(); 
+```

ojdbc-provider-observability/example-test.properties

@@ -0,0 +1,86 @@
+################################################################################
+# Copyright (c) 2024 Oracle and/or its affiliates.
+#
+# The Universal Permissive License (UPL), Version 1.0
+#
+# Subject to the condition set forth below, permission is hereby granted to any
+# person obtaining a copy of this software, associated documentation and/or data
+# (collectively the "Software"), free of charge and under any and all copyright
+# rights in the Software, and any and all patent rights owned or freely
+# licensable by each licensor hereunder covering either (i) the unmodified
+# Software as contributed to or provided by such licensor, or (ii) the Larger
+# Works (as defined below), to deal in both
+#
+# (a) the Software, and
+# (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+# one is included with the Software (each a "Larger Work" to which the Software
+# is contributed by such licensors),
+#
+# without restriction, including without limitation the rights to copy, create
+# derivative works of, display, perform, and distribute the Software and make,
+# use, sell, offer for sale, import, export, have made, and have sold the
+# Software and the Larger Work(s), and to sublicense the foregoing rights on
+# either these or other terms.
+#
+# This license is subject to the following condition:
+# The above copyright notice and either this complete permission notice or at
+# a minimum a reference to the UPL must be included in all copies or
+# substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+################################################################################
+
+# This file provides examples of properties that configure tests in this
+# module.
+#
+# QUICK GUIDE TO RUNNING TESTS:
+#   1. Create a copy of this file named "test.properties":
+#      cp example-test.properties test.properties
+#   2. In test.properties, replace example values with real values (the file is
+#      .gitignore'd, so sensitive info won't be checked in to the repo)
+#   3. Comment out any lines for which a value can not be provided (tests are
+#      skipped if no value is configured).
+#   4. mvn clean verify
+#
+# CONFIGURING TEST PROPERTIES
+#   Test properties are read from a properties file by the TestProperties class.
+#   The TestProperties class can be found in:
+#   ojdbc-provider-common/src/testFixtures/java/oracle/jdbc/provider/TestProperties.java
+#   The default behavior of TestProperties is to read a file named
+#   "test.properties" in the current directory. A non-default location may be
+#   specified as a JVM system property:
+#   mvn clean verify -Doracle.jdbc.provider.TestProperties=/path/to/my-test.properties
+#
+# MAINTAINING THIS FILE
+#   Project maintainers should add an example to this file anytime they write a
+#   test which requires a new property. Not doing so will inflict pain and
+#   suffering upon our fellow programmers, and will also lead to increased
+#   maintenance costs.
+#
+# IGNORING UNCONFIGURED PROPERTIES
+#   No test should cause a build failure due to an unconfigured property.
+#   Using JUnit terminology: A test should "abort" rather than "fail" when a
+#   property is not configured. This means that the test does not pass, but it
+#   does not cause the build to fail either.
+#   Methods of the TestProperties class will automatically abort a test if a
+#   property is not configured. The org.junit.jupiter.api.Assumptions class may
+#   also be used directly to abort a test.
+#   There is NO environment in which ALL tests can be run. Some tests may
+#   require authentication as a managed identity in an Azure VM, while other
+#   tests require authentication as an instance principal in an OCI compute
+#   instance; These environments are mutually exclusive. This is one reason why
+#   tests can not fail the build if a required property is not set.
+#   A more practical reason is that developers may not need to run all tests if
+#   their changes are isolated to single module. For instance, a developer
+#   working on an OCI provider should not need to set up an Azure tenancy to test
+#   their changes.
+
+OBSERVABILITY_URL=<url>
+OBSERVABILITY_USERNAME=<username>
+OBSERVABILITY_PASSWORD=<password>

ojdbc-provider-observability/pom.xml

@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+        <groupId>com.oracle.database.jdbc</groupId>
+        <artifactId>ojdbc-extensions</artifactId>
+        <version>1.0.3</version>
+  </parent>
+
+  <name>Oracle JDBC Observability Provider</name>
+  <groupId>com.oracle.database.jdbc</groupId>
+  <artifactId>ojdbc-provider-observability</artifactId>
+  <version>1.0.3</version>    
+
+  <properties>
+      <opentelemetry.version>1.44.1</opentelemetry.version>
+      <maven.compiler.source>11</maven.compiler.source>
+      <maven.compiler.target>11</maven.compiler.target>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.oracle.database.jdbc</groupId>
+      <artifactId>ojdbc11</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-api</artifactId>
+      <version>${opentelemetry.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <artifactId>ojdbc-provider-common</artifactId>
+      <groupId>com.oracle.database.jdbc</groupId>
+      <version>1.0.2</version>
+      <classifier>tests</classifier>
+      <type>test-jar</type>
+    </dependency>
+  </dependencies>
+  <build>
+      <plugins>
+          <plugin>
+              <groupId>org.apache.maven.plugins</groupId>
+              <artifactId>maven-surefire-plugin</artifactId>
+              <configuration>
+              <!-- 
+                ObservabilityConfigurationTest must run first and alone since it depends on
+                ObservabilityConfiguration being started with system properties set on the 
+                test.
+                Running tests alphabetical and single threaded ensures that.
+              -->
+                <parallel>none</parallel>
+                <runOrder>alphabetical</runOrder>
+              </configuration>
+          </plugin>
+      </plugins>
+  </build>
+</project>

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

@@ -0,0 +1,90 @@
+package oracle.jdbc.provider.observability;
+
+import oracle.jdbc.TraceEventListener;
+import oracle.jdbc.provider.observability.configuration.ObservabilityConfiguration;
+import oracle.jdbc.provider.observability.tracers.TracerType;
+
+/**
+ * <p>
+ * TraceEventListener implementaiton that receives notifications whenever events
+ * are generated in the driver and publishes these events different tracers 
+ * depending on the configuraiton.
+ * </p>
+ * <p>
+ * These events include:
+ * </p>
+ * <ul>
+ * <li>roundtrips to the database server</li>
+ * <li>AC begin and success</li>
+ * <li>VIP down event</li>
+ * </ul>
+ * <p>
+ * The available tracers are defined in the enumeration {@link TracerType}, and
+ * can be enabled using the method 
+ * {@link ObservabilityConfiguration#setEnabledTracers(String)}. The method
+ * {@link ObservabilityConfiguration#setSensitiveDataEnabled(boolean)} allows
+ * to enabled/disable exporting sensitive data to the tracers.
+ * </p>
+ */
+public class ObservabilityTraceEventListener implements TraceEventListener {
+
+  /**
+   * Private constructor.
+   */
+  private ObservabilityTraceEventListener() { }
+
+  /**
+   * Singleton instance.
+   */
+  private static final ObservabilityTraceEventListener INSTANCE = 
+      new ObservabilityTraceEventListener();
+
+  /**
+   * Returns the singleton instance of {@link ObservabilityTraceEventListener}.
+   * @return the singleton instance of {@link ObservabilityTraceEventListener}.
+   */
+  public static final ObservabilityTraceEventListener getInstance() {
+    return INSTANCE;
+  }
+
+  @Override
+  public Object roundTrip(Sequence sequence, TraceContext traceContext, Object userContext) {
+    if (!ObservabilityConfiguration.getInstance().getEnabled()) { return null;}
+    Object[] currentUserContext = getCurrentUserContext(userContext);
+    for (TracerType tracer : ObservabilityConfiguration.getInstance().getEnabledTracersSet()) {
+      Object newUserContext = tracer.getTracer().traceRoundtrip(sequence, traceContext, currentUserContext[tracer.ordinal()]);
+      currentUserContext[tracer.ordinal()] = newUserContext;
+    }
+    return currentUserContext;
+  }
+
+
+  @Override
+  public Object onExecutionEventReceived(JdbcExecutionEvent event, Object userContext, Object... params) {
+    if (!ObservabilityConfiguration.getInstance().getEnabled()) { return null;}
+    Object[] currentUserContext = getCurrentUserContext(userContext);
+    for (TracerType tracer : ObservabilityConfiguration.getInstance().getEnabledTracersSet()) {
+      Object newUserContext = tracer.getTracer().traceExecutionEvent(event, currentUserContext[tracer.ordinal()], params);
+      currentUserContext[tracer.ordinal()] = newUserContext;
+    }
+    return currentUserContext;
+  }
+
+  @Override
+  public boolean isDesiredEvent(JdbcExecutionEvent event) {
+    // Accept all events
+    return true;
+  }
+
+  @SuppressWarnings("unchecked")
+  private Object[] getCurrentUserContext(Object userContext) {
+    Object[] currentUserContext;
+    if (userContext != null && (userContext instanceof Object[])) {
+      currentUserContext = (Object[]) userContext;
+    } else {
+      currentUserContext = new Object[TracerType.values().length];
+    }
+    return currentUserContext;
+  }
+
+}