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

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:

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 weak hash map, thus adding additional GC pressure.
On every created coroutine, stacktrace of the current thread is dumped.
On every resume and suspend, WeakHashMap is updated under a global lock.

Properties

isInstalled	`val isInstalled: Boolean` Determines whether debug probes were installed.
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.