DebugProbes

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.

Functions

dumpCoroutines
Link copied to clipboard
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
Link copied to clipboard
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
Link copied to clipboard
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
Link copied to clipboard
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
Link copied to clipboard
fun printJob(job: Job, out: PrintStream = System.out)

Prints job hierarchy representation from jobToString to the given out.

printScope
Link copied to clipboard
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
Link copied to clipboard
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
Link copied to clipboard
fun uninstall()

Uninstall debug probes.

withDebugProbes
Link copied to clipboard
inline fun withDebugProbes(block: () -> Unit)

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

Properties

enableCreationStackTraces
Link copied to clipboard
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
Link copied to clipboard
val isInstalled: Boolean

Determines whether debug probes were installed.

sanitizeStackTraces
Link copied to clipboard
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.