Add API for new Cronet metrics

components/cronet/android/api/src/org/chromium/net/RequestFinishedInfo.java

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package org.chromium.net;
 
 import android.support.annotation.Nullable;
 
 import java.util.Collection;
+import java.util.Date;
 import java.util.concurrent.Executor;
 
 /**
  * Information about a finished request. Passed to {@link RequestFinishedInfo.Listener}.
  *
  * {@hide} as it's a prototype.
  */
 public final class RequestFinishedInfo {
     /**
      * Listens for finished requests for the purpose of collecting metrics.
@@ skipping 22 matching lines @@
          * @return this listener's {@link java.util.concurrent.Executor}
          */
         public Executor getExecutor() {
             return mExecutor;
         }
     }
 
     /**
      * Metrics collected for a single request.
      *
+     * Most timing metrics are taken from
+     * {@link https://cs.chromium.org/chromium/src/net/base/load_timing_info.h LoadTimingInfo}.
+     * See that file for more information about how to interpret them.
+     *
+     * Start times are reported as the time when a request started blocking on event, not when the
+     * event actually occurred, with the exception of push start. If a metric is not meaningful or
+     * not available, start and end times will be null. If no time was spent blocking on an event,
+     * start and end will be the same time.
+     *
      * {@hide} as it's a prototype.
      */
     public static class Metrics {
         @Nullable
+        private final long mProxyStartMs;
+        @Nullable
+        private final long mProxyEndMs;
+        @Nullable
+        private final long mDnsStartMs;
+        @Nullable
+        private final long mDnsEndMs;
+        @Nullable
+        private final long mConnectStartMs;
+        @Nullable
+        private final long mConnectEndMs;
+        @Nullable
+        private final long mSslStartMs;
+        @Nullable

[mef, 2016/08/10 03:03:37]

Is simple long nullable or do you need to use Long for that?

[mgersh, 2016/08/29 18:05:44]

I didn't actually want to make these nullable, they'll just be 0 and then get
turned into null when converted to Date. Deleted all the @Nullable annotations.

+        private final long mSslEndMs;
+        @Nullable
+        private final long mSendingStartMs;
+        @Nullable
+        private final long mSendingEndMs;
+        @Nullable
+        private final long mPushStartMs;
+        @Nullable
+        private final long mPushEndMs;
+        @Nullable
+        private final long mResponseStartMs;
+        @Nullable
+        private final long mResponseEndMs;
+        private final boolean mSocketReused;
+
+        @Nullable
         private final Long mTtfbMs;
         @Nullable
         private final Long mTotalTimeMs;
         @Nullable
         private final Long mSentBytesCount;
         @Nullable
         private final Long mReceivedBytesCount;
 
+        /**
+         * Old-style constructor
+         */
         public Metrics(@Nullable Long ttfbMs, @Nullable Long totalTimeMs,
                 @Nullable Long sentBytesCount, @Nullable Long receivedBytesCount) {
             mTtfbMs = ttfbMs;
             mTotalTimeMs = totalTimeMs;
             mSentBytesCount = sentBytesCount;
             mReceivedBytesCount = receivedBytesCount;
+
+            // Everything else is 0 for now
+            mProxyStartMs = 0;
+            mProxyEndMs = 0;
+            mDnsStartMs = 0;
+            mDnsEndMs = 0;
+            mConnectStartMs = 0;
+            mConnectEndMs = 0;
+            mSslStartMs = 0;
+            mSslEndMs = 0;
+            mSendingStartMs = 0;
+            mSendingEndMs = 0;
+            mPushStartMs = 0;
+            mPushEndMs = 0;
+            mResponseStartMs = 0;
+            mResponseEndMs = 0;
+            mSocketReused = false;
         }
 
         /**
+         * New-style constructor
+         */
+        public Metrics(long proxyStartMs, long proxyEndMs, long dnsStartMs, long dnsEndMs,
+                long connectStartMs, long connectEndMs, long sslStartMs, long sslEndMs,
+                long sendingStartMs, long sendingEndMs, long pushStartMs, long pushEndMs,
+                long responseStartMs, long responseEndMs, boolean socketReused, long sentBytesCount,
+                long receivedBytesCount) {
+            mProxyStartMs = proxyStartMs;
+            mProxyEndMs = proxyEndMs;

[mef, 2016/08/10 03:03:37]

shouldall these constructors and member variables go into implementation and
just keep abstract public methods here?

Consider what would happen if app is build with Cronet v.55 and later on in
Cronet.v65 we would want to add another metrics value. In current scenario
Cronet.v65 in GMS Core will be unable to do that as metrics are implemented in
api. If we just keep definition here, then we could update Metrics
implementation and new apps aware of v.65 will be able to use that, while v.55
will keep working as before.

[mgersh, 2016/08/29 18:05:44]

Done.

+            mDnsStartMs = dnsStartMs;
+            mDnsEndMs = dnsEndMs;
+            mConnectStartMs = connectStartMs;
+            mConnectEndMs = connectEndMs;
+            mSslStartMs = sslStartMs;
+            mSslEndMs = sslEndMs;
+            mSendingStartMs = sendingStartMs;
+            mSendingEndMs = sendingEndMs;
+            mPushStartMs = pushStartMs;
+            mPushEndMs = pushEndMs;
+            mResponseStartMs = responseStartMs;
+            mResponseEndMs = responseEndMs;
+            mSocketReused = socketReused;
+            mSentBytesCount = sentBytesCount;
+            mReceivedBytesCount = receivedBytesCount;
+
+            // Don't care about these anymore
+            mTtfbMs = null;
+            mTotalTimeMs = null;
+        }
+
+        @Nullable
+        private static Date toDate(long timestamp) {
+            if (timestamp != 0) {
+                return new Date(timestamp);
+            }
+            return null;
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when proxy resolution started. Null if there
+         * is no PAC.
+         */
+        @Nullable
+        public Date getProxyStart() {
+            return toDate(mProxyStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when proxy resolution finished. Null if there
+         * is no PAC.
+         */
+        @Nullable
+        public Date getProxyEnd() {
+            return toDate(mProxyEndMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when DNS lookup started.
+         */
+        @Nullable
+        public Date getDnsStart() {
+            return toDate(mDnsStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when DNS lookup finished.
+         */
+        @Nullable
+        public Date getDnsEnd() {
+            return toDate(mDnsEndMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when connection establishment started.
+         */
+        @Nullable
+        public Date getConnectStart() {
+            return toDate(mConnectStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when connection establishment finished.
+         */
+        @Nullable
+        public Date getConnectEnd() {
+            return toDate(mConnectEndMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when SSL handshake started.
+         */
+        @Nullable
+        public Date getSslStart() {
+            return toDate(mSslStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when SSL handshake finished.
+         */
+        @Nullable
+        public Date getSslEnd() {
+            return toDate(mSslEndMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when sending HTTP request headers started.
+         */
+        @Nullable
+        public Date getSendingStart() {
+            return toDate(mSendingStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when sending HTTP request body finished.
+         */
+        @Nullable
+        public Date getSendingEnd() {
+            return toDate(mSendingEndMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when the first byte of an HTTP2 server push
+         * was received.
+         */
+        @Nullable
+        public Date getPushStart() {
+            return toDate(mPushStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when the last byte of an HTTP2 server push
+         * was received.

[mef, 2016/08/10 03:03:37]

For all @Nullable results we need to explain the situation when they could be
null.

+         */
+        @Nullable
+        public Date getPushEnd() {
+            return toDate(mPushEndMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when the first byte of the response was
+         * received.
+         */
+        @Nullable
+        public Date getResponseStart() {
+            return toDate(mResponseStartMs);
+        }
+
+        /**
+         * @return {@link java.util.Date} representing when the last byte of the response was
+         * received.
+         */
+        @Nullable
+        public Date getResponseEnd() {
+            return toDate(mResponseEndMs);
+        }
+
+        /**
+         * @return whether the socket was reused. When true, DNS, connection, and SSL times will be
+         * null.
+         */
+        @Nullable
+        public boolean getSocketReused() {
+            return mSocketReused;
+        }
+
+        /**
          * Returns milliseconds between request initiation and first byte of response headers,
          * or null if not collected.
          */
         @Nullable
         public Long getTtfbMs() {
             return mTtfbMs;
         }
 
         /**
          * Returns milliseconds between request initiation and finish,
@@ skipping 14 matching lines @@
 
         /**
          * Returns total bytes received over the network transport layer, or null if not collected.
          */
         @Nullable
         public Long getReceivedBytesCount() {
             return mReceivedBytesCount;
         }
     }
 
+    public static final int SUCCEEDED = 0;
+    public static final int FAILED = 1;
+    public static final int CANCELED = 2;
+
     private final String mUrl;
     private final Collection<Object> mAnnotations;
     private final Metrics mMetrics;
+    // One of SUCCEEDED, FAILED, or CANCELED
+    private final int mFinishedReason;
     @Nullable
     private final UrlResponseInfo mResponseInfo;
+    @Nullable
+    private final UrlRequestException mException;
 
     /**
      * @hide only used by internal implementation.
      */
     public RequestFinishedInfo(String url, Collection<Object> annotations, Metrics metrics,
-            @Nullable UrlResponseInfo responseInfo) {
+            int finishedReason, @Nullable UrlResponseInfo responseInfo,
+            @Nullable UrlRequestException exception) {
         mUrl = url;
         mAnnotations = annotations;
         mMetrics = metrics;
+        mFinishedReason = finishedReason;
         mResponseInfo = responseInfo;
+        mException = exception;
     }
 
     /** Returns the request's original URL. */
     public String getUrl() {
         return mUrl;
     }
 
     /** Returns the objects that the caller has supplied when initiating the request. */
     public Collection<Object> getAnnotations() {
         return mAnnotations;
     }
 
     // TODO(klm): Collect and return a chain of Metrics objects for redirect responses.
+    // TODO(mgersh): Update this javadoc when new metrics are fully implemented
     /**
      * Returns metrics collected for this request.
      *
      * <p>The reported times and bytes account for all redirects, i.e.
      * the TTFB is from the start of the original request to the ultimate response headers,
      * the TTLB is from the start of the original request to the end of the ultimate response,
      * the received byte count is for all redirects and the ultimate response combined.
      * These cumulative metric definitions are debatable, but are chosen to make sense
      * for user-facing latency analysis.
      *
      * @return metrics collected for this request.
      */
     public Metrics getMetrics() {
         return mMetrics;
     }
 
     /**
+     * Returns the reason why the request finished.
+     * @return one of {@link #SUCCEEDED}, {@link #FAILED}, or {@link #CANCELED}
+     */
+    public int getFinishedReason() {
+        return mFinishedReason;
+    }
+
+    /**
      * Returns a {@link UrlResponseInfo} for the request, if its response had started.
      * @return {@link UrlResponseInfo} for the request, if its response had started.
      */
     @Nullable
     public UrlResponseInfo getResponseInfo() {
         return mResponseInfo;
     }
+
+    /**
+     * If the request failed, returns the same {@link UrlRequestException} provided to
+     * {@link UrlRequest.Callback#onFailed}.
+     *
+     * @return the request's {@link UrlRequestException}, if the request failed
+     */
+    @Nullable
+    public UrlRequestException getException() {
+        return mException;
+    }
 }