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},
+     * which holds the information for {@link http://w3c.github.io/navigation-timing/} and
+     * {@link https://www.w3.org/TR/resource-timing/}.
+     *
+     * Events happen in this order:
+     * request start
+     * proxy start
+     * proxy end
+     * dns start
+     * dns end
+     * connect start
+     * ssl start
+     * ssl end
+     * connect end
+     * send start
+     * send end
+     * response start
+     * response end
+     *
+     * 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 and end. If a metric is not
+     * meaningful or not available, including cases when a request finished before reaching that
+     * stage, 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 {
+    public abstract static class Metrics {
+        /**
+         * @return {@link java.util.Date} representing when proxy resolution started. Null if there
+         * is no PAC.
+         */
         @Nullable
-        private final Long mTtfbMs;
+        public abstract Date getProxyStart();
+
+        /**
+         * @return {@link java.util.Date} representing when proxy resolution finished. Null if there
+         * is no PAC.

[xunjieli, 2016/09/01 22:17:42]

As far as I know, Cronet doesn't do PAC resolution. Chrome's PAC resolution uses
V8. Cronet doesn't package V8. If there is a PAC URL, Android platform hides
that and gives us the address of a local HTTP server that's created by the
platform for this purpose instead of a PAC url.

"proxy start" and "proxy end" will always be null. I don't think we should
introduce these two since they aren't meaningful at least right now.

[mgersh, 2016/09/02 19:32:08]

Ah, didn't know that, thanks. Done.

+         */
         @Nullable
-        private final Long mTotalTimeMs;
+        public abstract Date getProxyEnd();
+
+        /**
+         * @return {@link java.util.Date} representing when DNS lookup started. Null if a proxy is
+         * used to determine the DNS address.
+         */
         @Nullable
-        private final Long mSentBytesCount;
+        public abstract Date getDnsStart();
+
+        /**
+         * @return {@link java.util.Date} representing when DNS lookup finished. Null if a proxy is
+         * used to determine the DNS address.
+         */
         @Nullable
-        private final Long mReceivedBytesCount;
+        public abstract Date getDnsEnd();
 
-        public Metrics(@Nullable Long ttfbMs, @Nullable Long totalTimeMs,
-                @Nullable Long sentBytesCount, @Nullable Long receivedBytesCount) {
-            mTtfbMs = ttfbMs;
-            mTotalTimeMs = totalTimeMs;
-            mSentBytesCount = sentBytesCount;
-            mReceivedBytesCount = receivedBytesCount;
-        }
+        /**
+         * @return {@link java.util.Date} representing when connection establishment started,
+         * typically when DNS resolution finishes if no proxy is used.
+         */
+        @Nullable
+        public abstract Date getConnectStart();
+
+        /**
+         * @return {@link java.util.Date} representing when connection establishment finished,
+         * after TCP connection is established and, if using HTTPS, SSL handshake is completed.
+         */
+        @Nullable
+        public abstract Date getConnectEnd();
+
+        /**
+         * @return {@link java.util.Date} representing when SSL handshake started. Null if SSL is
+         * not used.
+         */
+        @Nullable
+        public abstract Date getSslStart();
+
+        /**
+         * @return {@link java.util.Date} representing when SSL handshake finished. Null if SSL is
+         * not used.
+         */
+        @Nullable
+        public abstract Date getSslEnd();
+
+        /**
+         * @return {@link java.util.Date} representing when sending HTTP request headers started.
+         */
+        @Nullable
+        public abstract Date getSendingStart();
+
+        /**
+         * @return {@link java.util.Date} representing when sending HTTP request body finished.
+         */
+        @Nullable
+        public abstract Date getSendingEnd();
+
+        /**
+         * @return {@link java.util.Date} representing when the first byte of an HTTP2 server push
+         * was received. Null if server push is not used.
+         */
+        @Nullable
+        public abstract Date getPushStart();
+
+        /**
+         * @return {@link java.util.Date} representing when the last byte of an HTTP2 server push
+         * was received. Null if server push is not used.
+         */
+        @Nullable
+        public abstract Date getPushEnd();
+
+        /**
+         * @return {@link java.util.Date} representing when the first byte of the response was
+         * received.
+         */
+        @Nullable
+        public abstract Date getResponseStart();
+
+        /**
+         * @return {@link java.util.Date} representing when the last byte of the response was
+         * received.
+         */
+        @Nullable
+        public abstract Date getResponseEnd();
+
+        /**
+         * @return whether this request reused a socket from a previous request. When true, DNS,
+         * connection, and SSL times will be null.
+         */
+        @Nullable
+        public abstract boolean getSocketReused();
 
         /**
          * Returns milliseconds between request initiation and first byte of response headers,
          * or null if not collected.
          */
         @Nullable
-        public Long getTtfbMs() {
-            return mTtfbMs;
-        }
+        public abstract Long getTtfbMs();

[xunjieli, 2016/09/01 22:17:42]

I am inclining to suggest to spell out Tfbs since it doesn't seem to be a common
acronym?

[mgersh, 2016/09/02 19:32:08]

This is part of the old API which will go away soon, so no point renaming it
now. (We provide request start and response start, embedders can calculate ttfb
on their own if they care.) Added a TODO to make it more clear.

 
         /**
          * Returns milliseconds between request initiation and finish,
          * including a failure or cancellation, or null if not collected.
          */
         @Nullable
-        public Long getTotalTimeMs() {
-            return mTotalTimeMs;
-        }
+        public abstract Long getTotalTimeMs();
 
         /**
          * Returns total bytes sent over the network transport layer, or null if not collected.
          */
         @Nullable
-        public Long getSentBytesCount() {
-            return mSentBytesCount;
-        }
+        public abstract Long getSentBytesCount();
 
         /**
          * Returns total bytes received over the network transport layer, or null if not collected.
          */
         @Nullable
-        public Long getReceivedBytesCount() {
-            return mReceivedBytesCount;
-        }
+        public abstract Long getReceivedBytesCount();
     }
 
+    public static final int SUCCEEDED = 0;
+    public static final int FAILED = 1;
+    public static final int CANCELED = 2;

[xunjieli, 2016/09/01 22:17:42]

Maybe use intDef and add a documentation on what these mean?

[mgersh, 2016/09/02 19:32:08]

Huh, IntDef is cool. Done.

+
     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;
+    }
 }