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 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.

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.