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(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     /**
48      * Returns the default TracingController instance. At present there is
49      * only one TracingController instance for all WebView instances,
50      * however this restriction may be relaxed in a future Android release.
51      *
52      * @return The default TracingController instance.
53      */
54     @NonNull
getInstance()55     public static TracingController getInstance() {
56         return WebViewFactory.getProvider().getTracingController();
57     }
58 
59     /**
60      * Starts tracing all webviews. Depending on the trace mode in traceConfig
61      * specifies how the trace events are recorded.
62      *
63      * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL} and
64      * {@link TracingConfig#RECORD_CONTINUOUSLY} the events are recorded
65      * using an internal buffer and flushed to the outputStream when
66      * {@link #stop(OutputStream, Executor)} is called.
67      *
68      * @param tracingConfig Configuration options to use for tracing.
69      * @throws IllegalStateException If the system is already tracing.
70      * @throws IllegalArgumentException If the configuration is invalid (e.g.
71      *         invalid category pattern or invalid tracing mode).
72      */
start(@onNull TracingConfig tracingConfig)73     public abstract void start(@NonNull TracingConfig tracingConfig);
74 
75     /**
76      * Stops tracing and flushes tracing data to the specified outputStream.
77      *
78      * The data is sent to the specified output stream in json format typically
79      * in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion
80      * the {@link java.io.OutputStream#close()} method is called.
81      *
82      * @param outputStream The output stream the tracing data will be sent to. If null
83      *                     the tracing data will be discarded.
84      * @param executor The {@link java.util.concurrent.Executor} on which the
85      *        outputStream {@link java.io.OutputStream#write(byte[])} and
86      *        {@link java.io.OutputStream#close()} methods will be invoked.
87      * @return False if the WebView framework was not tracing at the time of the call,
88      *         true otherwise.
89      */
stop(@ullable OutputStream outputStream, @NonNull @CallbackExecutor Executor executor)90     public abstract boolean stop(@Nullable OutputStream outputStream,
91             @NonNull @CallbackExecutor Executor executor);
92 
93     /**
94      * Returns whether the WebView framework is tracing.
95      *
96      * @return True if tracing is enabled.
97      */
isTracing()98     public abstract boolean isTracing();
99 
100 }
101