feat(observability): add Observation SPI (#1682)

BREAKING CHANGE: the experimental driver `Metrics` and `ConnectionPoolMetrics` have been replaced with `ObservationProvider`.

 ## Observation SPI

NOTE: This is a feature preview.

The Observation SPI is used by the driver to instrument points of interest in its implementation. For instance, an observation is created around connection acquisition - it starts when acquisition begins and stops when acquisition ends. These observations may be used by SPI implementations to produce some useful output, like: metrics, traces, etc. Importantly, this resposibility is outside the instrumentation itself.

Driver configuration example:

```java
var config = Config.builder()
        .withObservationProvider(implementation) // null by default, meaning no-op implementation
        .build()
```

At present, the SPI is not expected to be implemented by users directly. Instead, 2 new implementation modules are introduced alongside the driver. Their versions will be managed by the driver BOM (`neo4j-java-driver-bom`). Both are described below.

 ### Neo4j Java Driver (Metrics)

NOTE: This is a feature preview.

Artifact ID: `neo4j-java-driver-observation-metrics`

A basic in-memory implementation with dedicated API - `Metrics` and `ConnectionPoolMetrics`, the effectively relocated interfaces from the driver.

Driver configuration example:

```java
var provider = MetricsObservationProvider.newInstance();
var config = Config.builder()
        .withObservationProvider(provider) // enable by registering the provider
        .build();
var metrics = provider.metrics();
```

 ### Neo4j Java Driver (Micrometer Observation)

NOTE: This is a feature preview.

Artifact ID: `neo4j-java-driver-observation-micrometer`

An implementation based Micrometer Observation API.

Driver observations are represented as dedicated Micrometer types:
- `Observation.Context`
    - For example, `SessionRunContext`.
- `ObservationConvention`
    - For example, `SessionRunConvention`.
- Default `ObservationConvention`
    - For example, `DefaultSessionRunConvention`.

The dedicated types enable users to benefit from Micrometer features, including high level of customisation of handling, naming and tagging.

While the naming used in this module was guided by the OpenTelemetry semantic conventions 1.36.0, it was also adapted to Micrometer naming convention.

Driver configuration example:

```java
var provider = MicrometerObservationProvider.builder(observationRegistry) // requires Micrometer ObservationRegistry instance
        .build(); // extra options are omitted for brevity
var config = Config.builder()
        .withObservationProvider(provider) // enable by registering the provider
        .build();
```

In addition, it includes `ConnectionPoolMetricsHandler` that implements Micrometer `ObservationHandler`. It manages several additional Micrometer metrics and may be optionally instantiated and registered by users.

Author: injectives

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.