feat(observability): add Observation SPI

[injectives]

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:

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:

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:

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.

[MaxAake]

✅

[MaxAake]

✅

[MaxAake]

✅