1 /*
2  * Copyright 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.webkit;
18 
19 import android.annotation.CallbackExecutor;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 
23 import java.io.OutputStream;
24 import java.util.concurrent.Executor;
25 
26 /**
27  * Manages tracing of WebViews. In particular provides functionality for the app
28  * to enable/disable tracing of parts of code and to collect tracing data.
29  * This is useful for profiling performance issues, debugging and memory usage
30  * analysis in production and real life scenarios.
31  * <p>
32  * The resulting trace data is sent back as a byte sequence in json format. This
33  * file can be loaded in "chrome://tracing" for further analysis.
34  * <p>
35  * Example usage:
36  * <pre class="prettyprint">
37  * TracingController tracingController = TracingController.getInstance();
38  * tracingController.start(new TracingConfig.Builder()
39  *                  .addCategories(TracingConfig.CATEGORIES_WEB_DEVELOPER).build());
40  * ...
41  * tracingController.stop(new FileOutputStream("trace.json"),
42  *                        Executors.newSingleThreadExecutor());
43  * </pre></p>
44  */
45 public abstract class TracingController {
46     /**
47      * @deprecated This class should not be constructed by applications, use {@link #getInstance}
48      * instead to fetch the singleton instance.
49      */
50     // TODO(ntfschr): mark this as @SystemApi after a year.
51     @Deprecated
TracingController()52     public TracingController() {}
53 
54     /**
55      * Returns the default TracingController instance. At present there is
56      * only one TracingController instance for all WebView instances,
57      * however this restriction may be relaxed in a future Android release.
58      *
59      * @return The default TracingController instance.
60      */
61     @NonNull
getInstance()62     public static TracingController getInstance() {
63         return WebViewFactory.getProvider().getTracingController();
64     }
65 
66     /**
67      * Starts tracing all webviews. Depending on the trace mode in traceConfig
68      * specifies how the trace events are recorded.
69      *
70      * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL} and
71      * {@link TracingConfig#RECORD_CONTINUOUSLY} the events are recorded
72      * using an internal buffer and flushed to the outputStream when
73      * {@link #stop(OutputStream, Executor)} is called.
74      *
75      * @param tracingConfig Configuration options to use for tracing.
76      * @throws IllegalStateException If the system is already tracing.
77      * @throws IllegalArgumentException If the configuration is invalid (e.g.
78      *         invalid category pattern or invalid tracing mode).
79      */
start(@onNull TracingConfig tracingConfig)80     public abstract void start(@NonNull TracingConfig tracingConfig);
81 
82     /**
83      * Stops tracing and flushes tracing data to the specified outputStream.
84      *
85      * The data is sent to the specified output stream in json format typically
86      * in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion
87      * the {@link java.io.OutputStream#close()} method is called.
88      *
89      * @param outputStream The output stream the tracing data will be sent to. If null
90      *                     the tracing data will be discarded.
91      * @param executor The {@link java.util.concurrent.Executor} on which the
92      *        outputStream {@link java.io.OutputStream#write(byte[])} and
93      *        {@link java.io.OutputStream#close()} methods will be invoked.
94      * @return False if the WebView framework was not tracing at the time of the call,
95      *         true otherwise.
96      */
stop(@ullable OutputStream outputStream, @NonNull @CallbackExecutor Executor executor)97     public abstract boolean stop(@Nullable OutputStream outputStream,
98             @NonNull @CallbackExecutor Executor executor);
99 
100     /**
101      * Returns whether the WebView framework is tracing.
102      *
103      * @return True if tracing is enabled.
104      */
isTracing()105     public abstract boolean isTracing();
106 
107 }
108