TracingController.java revision c809542c3081ee2fd31313f29626cc0b765147cf
1c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine/* 2c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Copyright 2017 The Android Open Source Project 3c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 4c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Licensed under the Apache License, Version 2.0 (the "License"); 5c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * you may not use this file except in compliance with the License. 6c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * You may obtain a copy of the License at 7c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 8c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * http://www.apache.org/licenses/LICENSE-2.0 9c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 10c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Unless required by applicable law or agreed to in writing, software 11c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * distributed under the License is distributed on an "AS IS" BASIS, 12c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * See the License for the specific language governing permissions and 14c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * limitations under the License. 15c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 16c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 17c809542c3081ee2fd31313f29626cc0b765147cfTim Volodinepackage android.webkit; 18c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 19c809542c3081ee2fd31313f29626cc0b765147cfTim Volodineimport android.annotation.NonNull; 20c809542c3081ee2fd31313f29626cc0b765147cfTim Volodineimport android.annotation.Nullable; 21c809542c3081ee2fd31313f29626cc0b765147cfTim Volodineimport android.os.Handler; 22c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 23c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine/** 24c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Manages tracing of WebViews. In particular provides functionality for the app 25c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * to enable/disable tracing of parts of code and to collect tracing data. 26c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * This is useful for profiling performance issues, debugging and memory usage 27c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * analysis in production and real life scenarios. 28c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <p> 29c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * The resulting trace data is sent back as a byte sequence in json format. This 30c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * file can be loaded in "chrome://tracing" for further analysis. 31c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <p> 32c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Note: All methods in this class must be called on the UI thread. All callbacks 33c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * are also called on the UI thread. 34c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <p> 35c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Example usage: 36c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <pre class="prettyprint"> 37c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * TracingController tracingController = TracingController.getInstance(); 38c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * tracingController.start(new TraceConfig(CATEGORIES_WEB_DEVELOPER)); 39c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * [..] 40c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * tracingController.stopAndFlush(new TraceFileOutput("trace.json"), null); 41c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * </pre></p> 42c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 43c809542c3081ee2fd31313f29626cc0b765147cfTim Volodinepublic abstract class TracingController { 44c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 45c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 46c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Interface for capturing tracing data. 47c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 48c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public interface TracingOutputStream { 49c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 50c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Will be called to return tracing data in chunks. 51c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Tracing data is returned in json format an array of bytes. 52c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 53c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine void write(byte[] chunk); 54c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 55c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 56c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Called when tracing is finished and the data collection is over. 57c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * There will be no calls to #write after #complete is called. 58c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 59c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine void complete(); 60c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine } 61c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 62c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 63c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Returns the default TracingController instance. At present there is 64c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * only one TracingController instance for all WebView instances, 65c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * however this restriction may be relaxed in the future. 66c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 67c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @return the default TracingController instance 68c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 69c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine @NonNull 70c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public static TracingController getInstance() { 71c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine return WebViewFactory.getProvider().getTracingController(); 72c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine } 73c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 74c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 75c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Starts tracing all webviews. Depeding on the trace mode in traceConfig 76c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * specifies how the trace events are recorded. 77c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 78c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL}, 79c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * {@link TracingConfig#RECORD_CONTINUOUSLY} and 80c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * {@link TracingConfig#RECORD_UNTIL_FULL_LARGE_BUFFER} the events are recorded 81c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * using an internal buffer and flushed to the outputStream when 82c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * {@link #stopAndFlush(TracingOutputStream, Handler)} is called. 83c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 84c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @param tracingConfig configuration options to use for tracing 85c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @return false if the system is already tracing, true otherwise. 86c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 87c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public abstract boolean start(TracingConfig tracingConfig); 88c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 89c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 90c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Stops tracing and discards all tracing data. 91c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 92c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * This method is particularly useful in conjunction with the 93c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * {@link TracingConfig#RECORD_TO_CONSOLE} tracing mode because tracing data is logged to 94c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * console and not sent to an outputStream as with 95c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * {@link #stopAndFlush(TracingOutputStream, Handler)}. 96c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 97c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @return false if the system was not tracing at the time of the call, true 98c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * otherwise. 99c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 100c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public abstract boolean stop(); 101c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 102c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 103c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Stops tracing and flushes tracing data to the specifid outputStream. 104c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 105c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Note that if the {@link TracingConfig#RECORD_TO_CONSOLE} tracing mode is used 106c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * nothing will be sent to the outputStream and no TracingOuputStream methods will be 107c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * called. In that case it is more convenient to just use {@link #stop()} instead. 108c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 109c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @param outputStream the output steam the tracing data will be sent to. 110c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @param handler the {@link android.os.Handler} on which the outputStream callbacks 111c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * will be invoked. If the handler is null the current thread's Looper 112c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * will be used. 113c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * @return false if the system was not tracing at the time of the call, true 114c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * otherwise. 115c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 116c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public abstract boolean stopAndFlush(TracingOutputStream outputStream, 117c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine @Nullable Handler handler); 118c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 119c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** True if the system is tracing */ 120c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public abstract boolean isTracing(); 121c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 122c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine // TODO: consider adding getTraceBufferUsage, percentage and approx event count. 123c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine // TODO: consider adding String getCategories(), for obtaining the actual list 124c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine // of categories used (given that presets are ints). 125c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 126c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine} 127