Table of contents
Debugging asynchronous programs is challenging, because multiple concurrent coroutines are typically working at the same time. To help with that,
kotlinx.coroutines comes with additional features for debugging: debug mode, stacktrace recovery and debug agent.
The first debugging feature of
kotlinx.coroutines is debug mode. It can be enabled either by setting system property DEBUG_PROPERTY_NAME or by running Java with enabled assertions (
-ea flag). The latter is helpful to have debug mode enabled by default in unit tests.
Debug mode attaches a unique name to every launched coroutine. Coroutine name can be seen in a regular Java debugger, in a string representation of the coroutine or in the thread name executing named coroutine. Overhead of this feature is negligible and it can be safely turned on by default to simplify logging and diagnostic.
Stacktrace recovery is another useful feature of debug mode. It is enabled by default in the debug mode, but can be separately disabled by setting
kotlinx.coroutines.stacktrace.recovery system property to
Stacktrace recovery tries to stitch asynchronous exception stacktrace with a stacktrace of the receiver by copying it, providing not only information where an exception was thrown, but also where it was asynchronously rethrown or caught.
It is easy to demonstrate with actual stacktraces of the same program that awaits asynchronous operation in
main function (runnable code is here):
| Without recovery | With recovery | | - | - | | | |
The only downside of this approach is losing referential transparency of the exception.
This section explains the inner mechanism of stacktrace recovery and can be skipped.
When an exception is rethrown between coroutines (e.g. through
Deferred.await boundary), stacktrace recovery machinery tries to create a copy of the original exception (with the original exception as the cause), then rewrite stacktrace of the copy with coroutine-related stack frames (using Throwable.setStackTrace) and then throws the resulting exception instead of the original one.
Exception copy logic is straightforward:
nullcan be returned from
createCopyto opt-out specific exception from being recovered.
kotlinx-coroutines-debug module provides one of the most powerful debug capabilities in
This is a separate module with a JVM agent that keeps track of all alive coroutines, introspects and dumps them similar to thread dump command, additionally enhancing stacktraces with information where coroutine was created.
The full tutorial of how to use debug agent can be found in the corresponding readme.
Unfortunately, Android runtime does not support Instrument API necessary for
kotlinx-coroutines-debug to function, triggering
java.lang.NoClassDefFoundError: Failed resolution of: Ljava/lang/management/ManagementFactory;.
Nevertheless, it will be possible to support debug agent on Android as soon as GradleAspectJ-Android will support android-gradle 3.3