/* * Copyright 2017 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.webkit; import android.annotation.CallbackExecutor; import android.annotation.NonNull; import android.annotation.Nullable; import java.io.OutputStream; import java.util.concurrent.Executor; /** * Manages tracing of WebViews. In particular provides functionality for the app * to enable/disable tracing of parts of code and to collect tracing data. * This is useful for profiling performance issues, debugging and memory usage * analysis in production and real life scenarios. *

* The resulting trace data is sent back as a byte sequence in json format. This * file can be loaded in "chrome://tracing" for further analysis. *

* Example usage: *

 * TracingController tracingController = TracingController.getInstance();
 * tracingController.start(new TracingConfig.Builder()
 *                  .addCategories(CATEGORIES_WEB_DEVELOPER).build());
 * ...
 * tracingController.stop(new FileOutputStream("trace.json"),
 *                        Executors.newSingleThreadExecutor());
 * 

*/ public abstract class TracingController { /** * Returns the default TracingController instance. At present there is * only one TracingController instance for all WebView instances, * however this restriction may be relaxed in a future Android release. * * @return The default TracingController instance. */ @NonNull public static TracingController getInstance() { return WebViewFactory.getProvider().getTracingController(); } /** * Starts tracing all webviews. Depending on the trace mode in traceConfig * specifies how the trace events are recorded. * * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL} and * {@link TracingConfig#RECORD_CONTINUOUSLY} the events are recorded * using an internal buffer and flushed to the outputStream when * {@link #stop(OutputStream, Executor)} is called. * * @param tracingConfig Configuration options to use for tracing. * @throws IllegalStateException If the system is already tracing. * @throws IllegalArgumentException If the configuration is invalid (e.g. * invalid category pattern or invalid tracing mode). */ public abstract void start(@NonNull TracingConfig tracingConfig); /** * Stops tracing and flushes tracing data to the specified outputStream. * * The data is sent to the specified output stream in json format typically * in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion * the {@link java.io.OutputStream#close()} method is called. * * @param outputStream The output stream the tracing data will be sent to. If null * the tracing data will be discarded. * @param executor The {@link java.util.concurrent.Executor} on which the * outputStream {@link java.io.OutputStream#write(byte[])} and * {@link java.io.OutputStream#close()} methods will be invoked. * @return False if the WebView framework was not tracing at the time of the call, * true otherwise. */ public abstract boolean stop(@Nullable OutputStream outputStream, @NonNull @CallbackExecutor Executor executor); /** * Returns whether the WebView framework is tracing. * * @return True if tracing is enabled. */ public abstract boolean isTracing(); }