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
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. |
|
val isInstalled: Boolean Determines whether debug probes were installed. |
|
var sanitizeStackTraces: Boolean Whether coroutine creation stack traces should be sanitized.
Sanitization removes all frames from |
Functions
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 |
|
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. |
|
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. |
|
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. |
|
fun printJob(job: Job, out: PrintStream = System.out): Unit Prints job hierarchy representation from jobToString to the given out. |
|
fun printScope( Prints all coroutines launched within the given scope. Throws IllegalStateException if the scope has no a job in it. |
|
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. |
|
fun uninstall(): Unit Uninstall debug probes. |
|
Invokes given block of code with installed debug probes and uninstall probes in the end. |