https://source.android.com/ 
/*
 * 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(TracingConfig.CATEGORIES_WEB_DEVELOPER).build());
...
tracingController.stop(new FileOutputStream("trace.json"),
                       Executors.newSingleThreadExecutor());



/**
 * 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.
 * <p>
 * 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.
 * <p>
 * Example usage:
 * <pre class="prettyprint">
 * TracingController tracingController = TracingController.getInstance();
 * tracingController.start(new TracingConfig.Builder()
 *                  .addCategories(TracingConfig.CATEGORIES_WEB_DEVELOPER).build());
 * ...
 * tracingController.stop(new FileOutputStream("trace.json"),
 *                        Executors.newSingleThreadExecutor());
 * </pre></p>
 */
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.

Returns:The default TracingController instance.
/**
     * 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 TracingConfig.RECORD_UNTIL_FULL and TracingConfig.RECORD_CONTINUOUSLY the events are recorded using an internal buffer and flushed to the outputStream when stop(OutputStream, Executor) is called. 
Params:
  • tracingConfig – Configuration options to use for tracing.
Throws:
/**
     * 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 OutputStream.write(byte[]). On completion the OutputStream.close() method is called. 
Params:
Returns:False if the WebView framework was not tracing at the time of the call,
        true otherwise.
/**
     * 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.

Returns:True if tracing is enabled.
/**
     * Returns whether the WebView framework is tracing.
     *
     * @return True if tracing is enabled.
     */
    public abstract boolean isTracing();

}