kotlinx-coroutines-debug/kotlinx.coroutines.debug/DebugProbes

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:

probeCoroutineResumed is invoked on every Continuation.resume.
probeCoroutineSuspended is invoked on every continuation suspension.
probeCoroutineCreated is invoked on every coroutine creation using stdlib intrinsics.

Overhead:

Every created coroutine is stored in a concurrent hash map and hash map is looked up and updated on each suspension and resumption.
If DebugProbes.enableCreationStackTraces is enabled, stack trace of the current thread is captured on each created coroutine that is a rough equivalent of throwing an exception per each created coroutine.

Functions

dumpCoroutines

fun dumpCoroutines(out: PrintStream = System.out)

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

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)

Prints job hierarchy representation from jobToString to the given out.

printScope

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

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

Uninstall debug probes.

withDebugProbes

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

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

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.