DebugProbes

@ExperimentalCoroutinesApi object DebugProbes

Debug probes support.

Debug probes is a dynamic attach mechanism which installs multiple hooks into coroutines machinery. It slows down all coroutine-related code, but in return provides a lot of diagnostic information, including asynchronous stack-traces and coroutine dumps (similar to ThreadMXBean.dumpAllThreads and jstack via DebugProbes.dumpCoroutines.

Installed hooks:

Overhead:

Properties

sanitizeStackTraces

var sanitizeStackTraces: Boolean

Whether coroutine creation stacktraces should be sanitized. Sanitization removes all frames from kotlinx.coroutines package except the first one and the last one to simplify diagnostic.

Functions

dumpCoroutines

fun dumpCoroutines(out: PrintStream = System.out): Unit

Dumps all active coroutines into the given output stream, providing a consistent snapshot of all existing coroutines at the moment of invocation. The output of this method is similar to jstack or a full thread dump. It can be used as the replacement to “Dump threads” action.

dumpCoroutinesInfo

fun dumpCoroutinesInfo(): List<CoroutineInfo>

Returns all existing coroutines info. The resulting collection represents a consistent snapshot of all existing coroutines at the moment of invocation.

install

fun install(): Unit

Installs a DebugProbes instead of no-op stdlib probes by redefining debug probes class using the same class loader as one loaded DebugProbes class.

jobToString

fun jobToString(job: Job): String

Returns string representation of the coroutines job hierarchy with additional debug information. Hierarchy is printed from the job as a root transitively to all children.

printJob

fun printJob(job: Job, out: PrintStream = System.out): Unit

Prints job hierarchy representation from jobToString to the given out.

printScope

fun printScope(
    scope: CoroutineScope,
    out: PrintStream = System.out
): Unit

Prints all coroutines launched within the given scope. Throws IllegalStateException if the scope has no a job in it.

scopeToString

fun scopeToString(scope: CoroutineScope): String

Returns string representation of all coroutines launched within the given scope. Throws IllegalStateException if the scope has no a job in it.

uninstall

fun uninstall(): Unit

Uninstall debug probes.

withDebugProbes

fun withDebugProbes(block: () -> Unit): Unit

Invokes given block of code with installed debug probes and uninstall probes in the end.