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. All introspecting methods throw IllegalStateException if debug probes were not installed.

Installed hooks:

Overhead:

Properties

enableCreationStackTraces

var enableCreationStackTraces: Boolean

Whether coroutine creation stack traces should be captured. When enabled, for each created coroutine a stack trace of the current thread is captured and attached to the coroutine. This option can be useful during local debug sessions, but is recommended to be disabled in production environments to avoid stack trace dumping overhead.

isInstalled

val isInstalled: Boolean

Determines whether debug probes were installed.

sanitizeStackTraces

var sanitizeStackTraces: Boolean

Whether coroutine creation stack traces 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.