feat(observability): add Observation SPI

bom/pom.xml

@@ -32,6 +32,16 @@
         <artifactId>neo4j-java-driver-all</artifactId>
         <version>${project.version}</version>
       </dependency>
+      <dependency>
+        <groupId>org.neo4j.driver</groupId>
+        <artifactId>neo4j-java-driver-observation-metrics</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.neo4j.driver</groupId>
+        <artifactId>neo4j-java-driver-observation-micrometer</artifactId>
+        <version>${project.version}</version>
+      </dependency>
       <dependency>
         <groupId>org.neo4j.bolt</groupId>
         <artifactId>neo4j-bolt-connection-bom</artifactId>

bundle/pom.xml

@@ -20,7 +20,7 @@
   <properties>
     <moduleName>org.neo4j.driver</moduleName>
     <rootDir>${project.basedir}/..</rootDir>
-    <maven.compiler.xlint.extras>,-try</maven.compiler.xlint.extras>
+    <maven.compiler.xlint.extras>,-try,-module</maven.compiler.xlint.extras>
     <maven.deploy.skip>false</maven.deploy.skip>
   </properties>
 
@@ -34,11 +34,6 @@
     </dependency>
 
     <!-- Optional and / or provided dependencies, as they are not transitive to the original driver they must be declared again. -->
-    <dependency>
-      <groupId>io.micrometer</groupId>
-      <artifactId>micrometer-core</artifactId>
-      <optional>true</optional>
-    </dependency>
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
@@ -93,7 +88,6 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-resources-plugin</artifactId>
-        <version>3.2.0</version>
         <executions>
           <execution>
             <id>copy-appCtx</id>

bundle/src/main/jpms/module-info.java

@@ -29,10 +29,14 @@
     exports org.neo4j.driver.util;
     exports org.neo4j.driver.exceptions;
     exports org.neo4j.driver.exceptions.value;
+    exports org.neo4j.driver.mapping;
+    exports org.neo4j.driver.observation;
+    exports org.neo4j.driver.internal.observation to
+            org.neo4j.driver.observation.metrics,
+            org.neo4j.driver.observation.micrometer;
 
     requires transitive java.logging;
     requires transitive org.reactivestreams;
-    requires static micrometer.core;
     requires static org.graalvm.nativeimage;
     requires static org.slf4j;
     requires static java.management;

driver/clirr-ignored-differences.xml

@@ -848,5 +848,62 @@
         <method>java.util.Optional rawClassification()</method>
     </difference>
 
+    <difference>
+        <className>org/neo4j/driver/Config</className>
+        <differenceType>7002</differenceType>
+        <method>boolean isMetricsEnabled()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Config</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.MetricsAdapter metricsAdapter()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Config$ConfigBuilder</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.Config$ConfigBuilder withDriverMetrics()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Config$ConfigBuilder</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.Config$ConfigBuilder withMetricsAdapter(org.neo4j.driver.MetricsAdapter)</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Config$ConfigBuilder</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.Config$ConfigBuilder withoutDriverMetrics()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/ConnectionPoolMetrics</className>
+        <differenceType>8001</differenceType>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7002</differenceType>
+        <method>boolean isMetricsEnabled()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Driver</className>
+        <differenceType>7002</differenceType>
+        <method>org.neo4j.driver.Metrics metrics()</method>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/Metrics</className>
+        <differenceType>8001</differenceType>
+    </difference>
+
+    <difference>
+        <className>org/neo4j/driver/MetricsAdapter</className>
+        <differenceType>8001</differenceType>
+    </difference>
+
 
 </differences>

driver/pom.xml

@@ -19,7 +19,7 @@
   <properties>
     <rootDir>${project.basedir}/..</rootDir>
     <api.classes.directory>${basedir}/target/classes-without-jpms</api.classes.directory>
-    <maven.compiler.xlint.extras>,-try</maven.compiler.xlint.extras>
+    <maven.compiler.xlint.extras>,-try,-module</maven.compiler.xlint.extras>
     <surefire.jpms.args>--add-reads org.neo4j.driver=io.netty.common --add-reads org.neo4j.driver=org.bouncycastle.provider --add-reads org.neo4j.driver=org.bouncycastle.pkix</surefire.jpms.args>
     <failsafe.parallelizable.jpms.args>--add-opens org.neo4j.driver/org.neo4j.driver.internal.util=ALL-UNNAMED --add-opens org.neo4j.driver/org.neo4j.driver.internal.async=ALL-UNNAMED --add-reads org.neo4j.driver=io.netty.common  --add-reads org.neo4j.driver=org.bouncycastle.provider --add-reads org.neo4j.driver=org.bouncycastle.pkix</failsafe.parallelizable.jpms.args>
     <failsafe.sequential.jpms.args>--add-reads org.neo4j.driver=org.bouncycastle.provider --add-reads org.neo4j.driver=org.bouncycastle.pkix</failsafe.sequential.jpms.args>
@@ -55,11 +55,6 @@
     </dependency>
 
     <!-- Optional and / or provided dependencies -->
-    <dependency>
-      <groupId>io.micrometer</groupId>
-      <artifactId>micrometer-core</artifactId>
-      <optional>true</optional>
-    </dependency>
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
@@ -176,7 +171,6 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-resources-plugin</artifactId>
-          <version>3.3.0</version>
           <executions>
             <execution>
               <id>copy-classes-excluding-jpms</id>

driver/src/main/java/module-info.java

@@ -30,14 +30,17 @@
     exports org.neo4j.driver.exceptions;
     exports org.neo4j.driver.exceptions.value;
     exports org.neo4j.driver.mapping;
+    exports org.neo4j.driver.observation;
+    exports org.neo4j.driver.internal.observation to
+            org.neo4j.driver.observation.metrics,
+            org.neo4j.driver.observation.micrometer;
 
     requires org.neo4j.bolt.connection;
     requires org.neo4j.bolt.connection.pooled;
     requires org.neo4j.bolt.connection.routed;
     requires reactor.core;
     requires transitive java.logging;
     requires transitive org.reactivestreams;
-    requires static micrometer.core;
     requires static org.graalvm.nativeimage;
     requires static org.slf4j;
     requires static java.management;

driver/src/main/java/org/neo4j/driver/Config.java

@@ -36,10 +36,13 @@
 import org.neo4j.driver.internal.InternalNotificationConfig;
 import org.neo4j.driver.internal.RoutingSettings;
 import org.neo4j.driver.internal.SecuritySettings;
+import org.neo4j.driver.internal.observation.DriverObservationProvider;
+import org.neo4j.driver.internal.observation.NoopObservationProvider;
 import org.neo4j.driver.internal.retry.ExponentialBackoffRetryLogic;
 import org.neo4j.driver.net.ServerAddressResolver;
-import org.neo4j.driver.util.Experimental;
+import org.neo4j.driver.observation.ObservationProvider;
 import org.neo4j.driver.util.Immutable;
+import org.neo4j.driver.util.Preview;
 import org.neo4j.driver.util.Resource;
 
 /**
@@ -145,17 +148,19 @@ public final class Config implements Serializable {
      */
     @SuppressWarnings("deprecation")
     private final NotificationConfig notificationConfig;
-    /**
-     * The {@link MetricsAdapter}.
-     */
-    private final MetricsAdapter metricsAdapter;
 
     /**
      * Specify if telemetry collection is disabled.
      * <p>
      * By default, the driver will send anonymous usage statistics to the server it connects to if the server requests those.
      */
     private final boolean telemetryDisabled;
+    /**
+     * The {@link ObservationProvider} if configured.
+     * @since 6.0.0
+     */
+    @Preview(name = "Observability")
+    private final transient ObservationProvider observationProvider;
 
     private Config(ConfigBuilder builder) {
         this.logging = builder.logging;
@@ -177,8 +182,8 @@ private Config(ConfigBuilder builder) {
         this.notificationConfig = builder.notificationConfig;
 
         this.eventLoopThreads = builder.eventLoopThreads;
-        this.metricsAdapter = builder.metricsAdapter;
         this.telemetryDisabled = builder.telemetryDisabled;
+        this.observationProvider = builder.observationProvider;
     }
 
     /**
@@ -345,6 +350,7 @@ public Optional<NotificationSeverity> minimumNotificationSeverity() {
 
     /**
      * Returns a set of disabled notification classifications.
+     *
      * @return the {@link Set} of disabled {@link NotificationClassification}
      * @since 5.22.0
      */
@@ -367,24 +373,6 @@ public int eventLoopThreads() {
         return eventLoopThreads;
     }
 
-    /**
-     * Returns whether the metrics is enabled or not on this driver.
-     *
-     * @return if the metrics is enabled or not on this driver
-     */
-    public boolean isMetricsEnabled() {
-        return this.metricsAdapter != MetricsAdapter.DEV_NULL;
-    }
-
-    /**
-     * Returns the {@link MetricsAdapter}.
-     *
-     * @return the metrics adapter
-     */
-    public MetricsAdapter metricsAdapter() {
-        return this.metricsAdapter;
-    }
-
     /**
      * Returns the user_agent configured for this driver.
      *
@@ -406,6 +394,16 @@ public boolean isTelemetryDisabled() {
         return telemetryDisabled;
     }
 
+    /**
+     * Returns the {@link ObservationProvider} if it is configured.
+     * @return an {@link Optional} with {@link ObservationProvider} if configured or {@link Optional#empty()} otherwise
+     * @since 6.0.0
+     */
+    @Preview(name = "Observability")
+    public Optional<ObservationProvider> observationProvider() {
+        return Optional.ofNullable(observationProvider);
+    }
+
     /**
      * Used to build new config instances
      */
@@ -425,9 +423,9 @@ public static final class ConfigBuilder {
         private int connectionTimeoutMillis = (int) TimeUnit.SECONDS.toMillis(30);
         private long maxTransactionRetryTimeMillis = ExponentialBackoffRetryLogic.DEFAULT_MAX_RETRY_TIME_MS;
         private ServerAddressResolver resolver;
-        private MetricsAdapter metricsAdapter = MetricsAdapter.DEV_NULL;
         private long fetchSize = 1000;
         private int eventLoopThreads = 0;
+        private ObservationProvider observationProvider;
 
         @SuppressWarnings("deprecation")
         private NotificationConfig notificationConfig = NotificationConfig.defaultConfig();
@@ -744,47 +742,21 @@ public ConfigBuilder withResolver(ServerAddressResolver resolver) {
         }
 
         /**
-         * Enable driver metrics backed by internal basic implementation. The metrics can be obtained afterwards via {@link Driver#metrics()}.
-         *
-         * @return this builder.
-         */
-        public ConfigBuilder withDriverMetrics() {
-            return withMetricsEnabled(true);
-        }
-
-        /**
-         * Disable driver metrics. When disabled, driver metrics cannot be accessed via {@link Driver#metrics()}.
-         *
-         * @return this builder.
+         * Sets the {@link ObservationProvider} that the driver should use.
+         * @param observationProvider the {@link ObservationProvider} or {@code null} to disable
+         * @return this builder
+         * @since 6.0.0
          */
-        public ConfigBuilder withoutDriverMetrics() {
-            return withMetricsEnabled(false);
-        }
-
-        private ConfigBuilder withMetricsEnabled(boolean enabled) {
-            if (!enabled) {
-                withMetricsAdapter(MetricsAdapter.DEV_NULL);
-            } else if (this.metricsAdapter == null || this.metricsAdapter == MetricsAdapter.DEV_NULL) {
-                withMetricsAdapter(MetricsAdapter.DEFAULT);
+        @Preview(name = "Observability")
+        public ConfigBuilder withObservationProvider(ObservationProvider observationProvider) {
+            this.observationProvider =
+                    Objects.requireNonNullElseGet(observationProvider, NoopObservationProvider::getInstance);
+            if (!(observationProvider instanceof DriverObservationProvider)) {
+                throw new IllegalArgumentException("Unssupported observation provider");
             }
             return this;
         }
 
-        /**
-         * Enable driver metrics with given {@link MetricsAdapter}.
-         * <p>
-         * {@link MetricsAdapter#MICROMETER} enables implementation based on <a href="https://micrometer.io">Micrometer</a>. The metrics can be obtained
-         * afterwards via Micrometer means and {@link Driver#metrics()}. Micrometer must be on classpath when using this option.
-         *
-         * @param metricsAdapter the metrics adapter to use. Use {@link MetricsAdapter#DEV_NULL} to disable metrics.
-         * @return this builder.
-         */
-        @Experimental
-        public ConfigBuilder withMetricsAdapter(MetricsAdapter metricsAdapter) {
-            this.metricsAdapter = Objects.requireNonNull(metricsAdapter, "metricsAdapter");
-            return this;
-        }
-
         /**
          * Configure the event loop thread count. This specifies how many threads the driver can use to handle network I/O events
          * and user's events in driver's I/O threads. By default, 2 * NumberOfProcessors amount of threads will be used instead.

driver/src/main/java/org/neo4j/driver/Driver.java

@@ -17,7 +17,6 @@
 package org.neo4j.driver;
 
 import java.util.concurrent.CompletionStage;
-import org.neo4j.driver.exceptions.ClientException;
 import org.neo4j.driver.exceptions.UnsupportedFeatureException;
 
 /**
@@ -256,22 +255,6 @@ default <T extends BaseSession> T session(Class<T> sessionClass, SessionConfig s
      */
     CompletionStage<Void> closeAsync();
 
-    /**
-     * Returns the driver metrics if metrics reporting is enabled via {@link Config.ConfigBuilder#withDriverMetrics()}.
-     * Otherwise, a {@link ClientException} will be thrown.
-     *
-     * @return the driver metrics if enabled.
-     * @throws ClientException if the driver metrics reporting is not enabled.
-     */
-    Metrics metrics();
-
-    /**
-     * Returns true if the driver metrics reporting is enabled via {@link Config.ConfigBuilder#withDriverMetrics()}, otherwise false.
-     *
-     * @return true if the metrics reporting is enabled.
-     */
-    boolean isMetricsEnabled();
-
     /**
      * This verifies if the driver can connect to a remote server or a cluster
      * by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.