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 1988604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodineimport android.annotation.CallbackExecutor; 20c809542c3081ee2fd31313f29626cc0b765147cfTim Volodineimport android.annotation.NonNull; 21c809542c3081ee2fd31313f29626cc0b765147cfTim Volodineimport android.annotation.Nullable; 2288604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine 2388604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodineimport java.io.OutputStream; 2488604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodineimport java.util.concurrent.Executor; 25c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 26c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine/** 27c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Manages tracing of WebViews. In particular provides functionality for the app 28c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * to enable/disable tracing of parts of code and to collect tracing data. 29c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * This is useful for profiling performance issues, debugging and memory usage 30c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * analysis in production and real life scenarios. 31c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <p> 32c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * The resulting trace data is sent back as a byte sequence in json format. This 33c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * file can be loaded in "chrome://tracing" for further analysis. 34c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <p> 35c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Example usage: 36c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * <pre class="prettyprint"> 37c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * TracingController tracingController = TracingController.getInstance(); 3890980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * tracingController.start(new TracingConfig.Builder() 3988604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * .addCategories(CATEGORIES_WEB_DEVELOPER).build()); 4090980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * ... 4188604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * tracingController.stop(new FileOutputStream("trace.json"), 4288604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * Executors.newSingleThreadExecutor()); 43c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * </pre></p> 44c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 45c809542c3081ee2fd31313f29626cc0b765147cfTim Volodinepublic abstract class TracingController { 46c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 47c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 48c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * Returns the default TracingController instance. At present there is 49c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * only one TracingController instance for all WebView instances, 5088604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * however this restriction may be relaxed in a future Android release. 51c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 5290980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @return The default TracingController instance. 53c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 54c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine @NonNull 55c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public static TracingController getInstance() { 56c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine return WebViewFactory.getProvider().getTracingController(); 57c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine } 58c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 59c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 6088604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * Starts tracing all webviews. Depending on the trace mode in traceConfig 61c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * specifies how the trace events are recorded. 62c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 631a07ccc07e9cc5b0ba8e8922979a486bd83f333dTim Volodine * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL} and 641a07ccc07e9cc5b0ba8e8922979a486bd83f333dTim Volodine * {@link TracingConfig#RECORD_CONTINUOUSLY} the events are recorded 65c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * using an internal buffer and flushed to the outputStream when 6688604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * {@link #stop(OutputStream, Executor)} is called. 67c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 6890980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @param tracingConfig Configuration options to use for tracing. 6990980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @throws IllegalStateException If the system is already tracing. 7090980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @throws IllegalArgumentException If the configuration is invalid (e.g. 7190980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * invalid category pattern or invalid tracing mode). 72c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 7388604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine public abstract void start(@NonNull TracingConfig tracingConfig); 74c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 75c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine /** 7688604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * Stops tracing and flushes tracing data to the specified outputStream. 77c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 7888604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * The data is sent to the specified output stream in json format typically 7988604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion 8088604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * the {@link java.io.OutputStream#close()} method is called. 81c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine * 8290980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @param outputStream The output stream the tracing data will be sent to. If null 8388604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine * the tracing data will be discarded. 8490980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @param executor The {@link java.util.concurrent.Executor} on which the 8590980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * outputStream {@link java.io.OutputStream#write(byte[])} and 8690980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * {@link java.io.OutputStream#close()} methods will be invoked. 8790980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @return False if the WebView framework was not tracing at the time of the call, 8890980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * true otherwise. 89c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine */ 9088604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine public abstract boolean stop(@Nullable OutputStream outputStream, 9188604f2f8ac07283fa70ec2feb3aaeadcedaf0ceTim Volodine @NonNull @CallbackExecutor Executor executor); 92c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 9390980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine /** 9490980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * Returns whether the WebView framework is tracing. 9590980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * 9690980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine * @return True if tracing is enabled. 9790980b42080c88b0b31ccbbbe1760037b26de8f7Tim Volodine */ 98c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine public abstract boolean isTracing(); 99c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine 100c809542c3081ee2fd31313f29626cc0b765147cfTim Volodine} 101