TracingController


@AnyThread
public abstract class TracingController


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());

Summary

Public methods

static @NonNull TracingController
@RequiresFeature(name = WebViewFeature.TRACING_CONTROLLER_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
getInstance()

Returns the default TracingController instance.

abstract boolean

Returns whether the WebView framework is tracing.

abstract void
start(@NonNull TracingConfig tracingConfig)

Starts tracing all WebViews.

abstract boolean
stop(@Nullable OutputStream outputStream, @NonNull Executor executor)

Stops tracing and flushes tracing data to the specified outputStream.

Public methods

getInstance

Added in 1.1.0
@RequiresFeature(name = WebViewFeature.TRACING_CONTROLLER_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public static @NonNull TracingController getInstance()

Returns the default TracingController instance. At present there is only one TracingController instance for all WebView instances.

This method should only be called if isFeatureSupported returns true for TRACING_CONTROLLER_BASIC_USAGE.

isTracing

Added in 1.1.0
public abstract boolean isTracing()

Returns whether the WebView framework is tracing.

Returns
boolean

True if tracing is enabled.

start

Added in 1.1.0
public abstract void start(@NonNull TracingConfig tracingConfig)

Starts tracing all WebViews. Depending on the trace mode in traceConfig specifies how the trace events are recorded.

For tracing modes RECORD_UNTIL_FULL and RECORD_CONTINUOUSLY the events are recorded using an internal buffer and flushed to the outputStream when stop is called.

This method should only be called if isFeatureSupported returns true for TRACING_CONTROLLER_BASIC_USAGE.

Parameters
@NonNull TracingConfig tracingConfig

Configuration options to use for tracing.

Throws
java.lang.IllegalStateException

If the system is already tracing.

java.lang.IllegalArgumentException

If the configuration is invalid (e.g. invalid category pattern or invalid tracing mode).

stop

Added in 1.1.0
public abstract boolean stop(@Nullable OutputStream outputStream, @NonNull Executor executor)

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 write. On completion the close method is called.

This method should only be called if isFeatureSupported returns true for TRACING_CONTROLLER_BASIC_USAGE.

Parameters
@Nullable OutputStream outputStream

The output stream the tracing data will be sent to. If null the tracing data will be discarded.

@NonNull Executor executor

The Executor on which the outputStream write and close methods will be invoked.

Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use getMainExecutor. To dispatch events through a shared thread pool, you can use THREAD_POOL_EXECUTOR.

Returns
boolean

false if the WebView framework was not tracing at the time of the call, true otherwise.