Merge pull request #624 from zhenlineo/4.0-metrics

Improved java doc for metrics

Author: zhenlineo

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

@@ -22,93 +22,89 @@
 
 public interface ConnectionPoolMetrics
 {
-    enum PoolStatus
-    {
-        OPEN, CLOSED
-    }
 
     /**
-     * An unique name that identifies this connection pool metrics among all others
+     * An unique id that identifies this pool metrics.
      * @return An unique name
      */
     String id();
 
     /**
-     * The status of the pool.
-     * @return The status of the pool.
-     */
-    PoolStatus poolStatus();
-
-    /**
-     * The amount of connections that are currently in-use (borrowed out of the pool).
+     * The amount of connections that are currently in-use (borrowed out of the pool). The amount can increase or decrease over time.
      * @return The amount of connections that are currently in-use
      */
     int inUse();
 
     /**
-     * The amount of connections that are currently idle (buffered inside the pool).
+     * The amount of connections that are currently idle (buffered inside the pool). The amount can increase or decrease over time.
      * @return The amount of connections that are currently idle.
      */
     int idle();
 
     /**
-     * The amount of connections that are currently waiting to be created.
+     * The amount of connections that are currently in the process of being created.
      * The amount is increased by one when the pool noticed a request to create a new connection.
      * The amount is decreased by one when the pool noticed a new connection is created successfully or failed to create.
+     * The amount can increase or decrease over time.
      * @return The amount of connections that are waiting to be created.
      */
     int creating();
 
     /**
-     * An increasing-only number to record how many connections have been created by this pool successfully since the pool is created.
+     * A counter to record how many connections have been successfully created with this pool since the pool is created.
+     * This number increases every time when a connection is successfully created.
      * @return The amount of connections have ever been created by this pool.
      */
     long created();
 
     /**
-     * An increasing-only number to record how many connections have been failed to create.
-     * @return The amount of connections have been failed to create by this pool.
+     * A counter to record how many connections that have failed to be created.
+     * This number increases every time when a connection failed to be created.
+     * @return The amount of connections have failed to be created by this pool.
      */
     long failedToCreate();
 
     /**
-     * An increasing-only number to record how many connections have been closed by this pool.
+     * A counter to record how many connections have been closed by this pool.
+     * This number increases every time when a connection is closed.
      * @return The amount of connections have been closed by this pool.
      */
     long closed();
 
     /**
-     * The current count of application requests to wait for acquiring a connection from the pool.
-     * The reason to wait could be waiting for creating a new connection, or waiting for a connection to be free by application when the pool is full.
-     * @return The current amount of application request to wait for acquiring a connection from the pool.
+     * The number of connection acquisition requests that are currently in progress.
+     * These requests can be waiting or blocked if there are no connections immediately available in the pool.
+     * A request will wait for a new connection to be created, or it will be blocked if the pool is at its maximum size but all connections are already in use.
+     * The amount can increase or decrease over time.
+     * @return The number of connection acquisition requests that are currently in progress.
      */
     int acquiring();
 
     /**
-     * An increasing-only number to record how many connections have been acquired from the pool since the pool is created.
-     * The connections acquired could hold either a newly created connection or a reused connection from the pool.
+     * A counter to record how many connections have been acquired from the pool since the pool is created.
+     * This number increases every time when a connection is acquired.
      * @return The amount of connections that have been acquired from the pool.
      */
     long acquired();
 
     /**
-     * An increasing-only number to record how many times that we've failed to acquire a connection from the pool within configured maximum acquisition timeout
+     * A counter to record how many times that we've failed to acquire a connection from the pool within configured maximum acquisition timeout
      * set by {@link Config.ConfigBuilder#withConnectionAcquisitionTimeout(long, TimeUnit)}.
-     * The connection acquired could hold either a newly created connection or a reused connection from the pool.
+     * This number increases every time when a connection is timed out when acquiring.
      * @return The amount of failures to acquire a connection from the pool within maximum connection acquisition timeout.
      */
     long timedOutToAcquire();
 
     /**
-     * The total acquisition time in milliseconds of all connection acquisition requests since the pool is created.
+     * A counter to record the total acquisition time in milliseconds of all connection acquisition requests since the pool is created.
+     * This number increases every time when a connection is acquired.
      * See {@link ConnectionPoolMetrics#acquired()} for the total amount of connection acquired since the driver is created.
      * The average acquisition time can be calculated using the code below:
      * <h2>Example</h2>
      * <pre>
      * {@code
-     * ConnectionPoolMetrics previous = ConnectionPoolMetrics.EMPTY;
+     * ConnectionPoolMetrics previous, current;
      * ...
-     * ConnectionPoolMetrics current = poolMetrics.snapshot();
      * double average = computeAverage(current.totalAcquisitionTime(), previous.totalAcquisitionTime(), current.acquired(), previous.acquired());
      * previous = current;
      * ...
@@ -124,15 +120,15 @@ enum PoolStatus
     long totalAcquisitionTime();
 
     /**
-     * The total time in milliseconds spent to establishing new socket connections since the pool is created.
+     * A counter to record the total time in milliseconds spent to establishing new socket connections since the pool is created.
+     * This number increases every time when a connection is established.
      * See {@link ConnectionPoolMetrics#created()} for the total amount of connections established since the pool is created.
      * The average connection time can be calculated using the code below:
      * <h2>Example</h2>
      * <pre>
      * {@code
-     * ConnectionPoolMetrics previous = ConnectionPoolMetrics.EMPTY;
+     * ConnectionPoolMetrics previous, current;
      * ...
-     * ConnectionPoolMetrics current = poolMetrics.snapshot();
      * double average = computeAverage(current.totalConnectionTime(), previous.totalConnectionTime(), current.created(), previous.created());
      * previous = current;
      * ...
@@ -148,15 +144,16 @@ enum PoolStatus
     long totalConnectionTime();
 
     /**
-     * The total time in milliseconds connections are borrowed out of the pool, such as the time spent in user's application code to run cypher queries.
+     * A counter to record the total time in milliseconds connections are borrowed out of the pool,
+     * such as the time spent in user's application code to run cypher queries.
+     * This number increases every time when a connection is returned back to the pool.
      * See {@link ConnectionPoolMetrics#totalInUseCount()} for the total amount of connections that are borrowed out of the pool.
      * The average in-use time can be calculated using the code below:
      * <h2>Example</h2>
      * <pre>
      * {@code
-     * ConnectionPoolMetrics previous = ConnectionPoolMetrics.EMPTY;
+     * ConnectionPoolMetrics previous, current;
      * ...
-     * ConnectionPoolMetrics current = poolMetrics.snapshot();
      * double average = computeAverage(current.totalInUseTime(), previous.totalInUseTime(), current.totalInUseCount(), previous.totalInUseCount());
      * previous = current;
      * ...
@@ -173,13 +170,8 @@ enum PoolStatus
 
     /**
      * The total amount of connections that are borrowed outside the pool since the pool is created.
+     * This number increases every time when a connection is returned back to the pool.
      * @return the total amount of connection that are borrowed outside the pool.
      */
     long totalInUseCount();
-
-    /**
-     * Returns a snapshot of this connection pool metrics.
-     * @return a snapshot of this connection pool metrics.
-     */
-    ConnectionPoolMetrics snapshot();
 }

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

@@ -155,6 +155,14 @@ public interface Driver extends AutoCloseable
     @Experimental
     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.
+     */
+    @Experimental
+    boolean isMetricsEnabled();
+
     /**
      * This will return the type system supported by the driver.
      * The types supported on a particular server a session is connected against might not contain all of the types defined here.

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

@@ -20,10 +20,10 @@
 
 import java.net.URI;
 
+import org.neo4j.driver.exceptions.ServiceUnavailableException;
 import org.neo4j.driver.internal.DriverFactory;
 import org.neo4j.driver.internal.cluster.RoutingSettings;
 import org.neo4j.driver.internal.retry.RetrySettings;
-import org.neo4j.driver.exceptions.ServiceUnavailableException;
 
 import static org.neo4j.driver.internal.DriverFactory.BOLT_ROUTING_URI_SCHEME;
 

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

@@ -18,20 +18,17 @@
  */
 package org.neo4j.driver;
 
-import java.util.Map;
+import java.util.Collection;
+
+import org.neo4j.driver.util.Experimental;
 
 public interface Metrics
 {
     /**
-     * A map of connection pool metrics.
-     * The {@link ConnectionPoolMetrics#id()} are used as the keys of the map.
-     * @return The connection pool metrics.
-     */
-    Map<String, ConnectionPoolMetrics> connectionPoolMetrics();
-
-    /**
-     * Returns a snapshot of this metrics.
-     * @return a snapshot of this metrics.
+     * Connection pool metrics records metrics of connection pools that are currently in use.
+     * As the connection pools are dynamically added and removed while the server topology changes, the metrics collection changes over time.
+     * @return Connection pool metrics for all current active pools.
      */
-    Metrics snapshot();
+    @Experimental
+    Collection<ConnectionPoolMetrics> connectionPoolMetrics();
 }

driver/src/main/java/org/neo4j/driver/internal/DriverFactory.java

@@ -123,7 +123,7 @@ protected static MetricsProvider createDriverMetrics( Config config, Clock clock
     {
         if( config.isMetricsEnabled() )
         {
-            return new InternalMetricsProvider( clock );
+            return new InternalMetricsProvider( clock, config.logging() );
         }
         else
         {

driver/src/main/java/org/neo4j/driver/internal/InternalDriver.java

@@ -99,6 +99,12 @@ public Metrics metrics()
         return metricsProvider.metrics();
     }
 
+    @Override
+    public boolean isMetricsEnabled()
+    {
+        return metricsProvider.isMetricsEnabled();
+    }
+
     @Override
     public boolean isEncrypted()
     {

driver/src/main/java/org/neo4j/driver/internal/async/NetworkConnection.java

@@ -41,6 +41,7 @@
 import org.neo4j.driver.internal.util.ServerVersion;
 
 import static java.util.Collections.emptyMap;
+import static org.neo4j.driver.internal.async.connection.ChannelAttributes.poolId;
 import static org.neo4j.driver.internal.async.connection.ChannelAttributes.setTerminationReason;
 
 /**
@@ -76,7 +77,7 @@ public NetworkConnection( Channel channel, ChannelPool channelPool, Clock clock,
         this.clock = clock;
         this.metricsListener = metricsListener;
         this.inUseEvent = metricsListener.createListenerEvent();
-        metricsListener.afterConnectionCreated( this.serverAddress, this.inUseEvent );
+        metricsListener.afterConnectionCreated( poolId( this.channel ), this.inUseEvent );
     }
 
     @Override
@@ -166,7 +167,7 @@ public CompletionStage<Void> release()
                     channelPool, messageDispatcher, clock, releaseFuture );
 
             writeResetMessageIfNeeded( handler, false );
-            metricsListener.afterConnectionReleased( this.serverAddress, this.inUseEvent );
+            metricsListener.afterConnectionReleased( poolId( this.channel ), this.inUseEvent );
         }
         return releaseFuture;
     }
@@ -180,7 +181,7 @@ public void terminateAndRelease( String reason )
             channel.close();
             channelPool.release( channel );
             releaseFuture.complete( null );
-            metricsListener.afterConnectionReleased( this.serverAddress, this.inUseEvent );
+            metricsListener.afterConnectionReleased( poolId( this.channel ), this.inUseEvent );
         }
     }
 

driver/src/main/java/org/neo4j/driver/internal/async/connection/ChannelAttributes.java

@@ -30,6 +30,7 @@
 public final class ChannelAttributes
 {
     private static final AttributeKey<String> CONNECTION_ID = newInstance( "connectionId" );
+    private static final AttributeKey<String> POOL_ID = newInstance( "poolId" );
     private static final AttributeKey<Integer> PROTOCOL_VERSION = newInstance( "protocolVersion" );
     private static final AttributeKey<BoltServerAddress> ADDRESS = newInstance( "serverAddress" );
     private static final AttributeKey<ServerVersion> SERVER_VERSION = newInstance( "serverVersion" );
@@ -52,6 +53,16 @@ public static void setConnectionId( Channel channel, String id )
         setOnce( channel, CONNECTION_ID, id );
     }
 
+    public static String poolId( Channel channel )
+    {
+        return get( channel, POOL_ID );
+    }
+
+    public static void setPoolId( Channel channel, String id )
+    {
+        setOnce( channel, POOL_ID, id );
+    }
+
     public static int protocolVersion( Channel channel )
     {
         return get( channel, PROTOCOL_VERSION );