# TracingController

Artifact: [androidx.webkit:webkit](https://developer.android.com/jetpack/androidx/releases/webkit) [View Source](https://cs.android.com/search?q=file:androidx/webkit/TracingController.java+class:androidx.webkit.TracingController) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/webkit#1.1.0)

*** ** * ** ***

<br />

```
@AnyThread
abstract class TracingController
```

<br />

*** ** * ** ***

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:

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

## Summary

| ### Public functions |
|---|---|
| `java-static https://developer.android.com/reference/kotlin/androidx/webkit/TracingController` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresFeature(name = https://developer.android.com/reference/kotlin/androidx/webkit/WebViewFeature.TRACING_CONTROLLER_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported") https://developer.android.com/reference/kotlin/androidx/webkit/TracingController#getInstance()()` Returns the default `https://developer.android.com/reference/kotlin/androidx/webkit/TracingController` instance. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/webkit/TracingController#isTracing()()` Returns whether the WebView framework is tracing. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/webkit/TracingController#start(androidx.webkit.TracingConfig)(tracingConfig: https://developer.android.com/reference/kotlin/androidx/webkit/TracingConfig)` Starts tracing all WebViews. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/webkit/TracingController#stop(java.io.OutputStream,java.util.concurrent.Executor)(outputStream: https://developer.android.com/reference/java/io/OutputStream.html?, executor: https://developer.android.com/reference/java/util/concurrent/Executor.html)` Stops tracing and flushes tracing data to the specified outputStream. |

## Public functions

### getInstance

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/webkit#1.1.0)

```
@RequiresFeature(name = WebViewFeature.TRACING_CONTROLLER_BASIC_USAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
java-static fun getInstance(): TracingController
```

Returns the default `https://developer.android.com/reference/kotlin/androidx/webkit/TracingController` instance. At present there is only one TracingController instance for all WebView instances.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | if the `https://developer.android.com/reference/kotlin/androidx/webkit/WebViewFeature#TRACING_CONTROLLER_BASIC_USAGE()` feature is not supported. This should be checked before use with `https://developer.android.com/reference/kotlin/androidx/webkit/WebViewFeature#isFeatureSupported(java.lang.String)`. |

### isTracing

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/webkit#1.1.0)

```
abstract fun isTracing(): Boolean
```

Returns whether the WebView framework is tracing.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | True if tracing is enabled. |

### start

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/webkit#1.1.0)

```
abstract fun start(tracingConfig: TracingConfig): Unit
```

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

For tracing modes `https://developer.android.com/reference/android/webkit/TracingConfig.html#RECORD_UNTIL_FULL` and `https://developer.android.com/reference/android/webkit/TracingConfig.html#RECORD_CONTINUOUSLY` the events are recorded using an internal buffer and flushed to the outputStream when `https://developer.android.com/reference/kotlin/androidx/webkit/TracingController#stop(java.io.OutputStream,java.util.concurrent.Executor)` is called.

| Parameters |
|---|---|
| `tracingConfig: https://developer.android.com/reference/kotlin/androidx/webkit/TracingConfig` | Configuration options to use for tracing. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | If the system is already tracing. |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | If the configuration is invalid (e.g. invalid category pattern or invalid tracing mode). |

### stop

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/webkit#1.1.0)

```
abstract fun stop(outputStream: OutputStream?, executor: Executor): Boolean
```

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 `https://developer.android.com/reference/java/io/OutputStream.html#write(byte[])`. On completion the `https://developer.android.com/reference/java/io/OutputStream.html#close()` method is called.

| Parameters |
|---|---|
| `outputStream: https://developer.android.com/reference/java/io/OutputStream.html?` | The output stream the tracing data will be sent to. If `null` the tracing data will be discarded. |
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | The Executor on which the outputStream `https://developer.android.com/reference/java/io/OutputStream.html#write(byte[])` and `https://developer.android.com/reference/java/io/OutputStream.html#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 `https://developer.android.com/reference/android/content/Context.html#getMainExecutor()`. To dispatch events through a shared thread pool, you can use `https://developer.android.com/reference/android/os/AsyncTask.html#THREAD_POOL_EXECUTOR`. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `false` if the WebView framework was not tracing at the time of the call, `true` otherwise. |