{"id":19898384,"url":"https://github.com/anamorphosee/stacktrace-decoroutinator","last_synced_at":"2025-04-07T18:14:43.826Z","repository":{"id":39863469,"uuid":"429510239","full_name":"Anamorphosee/stacktrace-decoroutinator","owner":"Anamorphosee","description":"Small lib for recovering stack trace in exceptions thrown in Kotlin coroutines","archived":false,"fork":false,"pushed_at":"2024-08-16T02:51:47.000Z","size":395,"stargazers_count":186,"open_issues_count":5,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-21T09:12:21.391Z","etag":null,"topics":["android","coroutines","debug","jvm","kotlin","kotlin-coroutines"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Anamorphosee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-18T16:55:45.000Z","updated_at":"2024-08-25T05:23:27.779Z","dependencies_parsed_at":"2024-08-25T05:23:23.200Z","dependency_job_id":"0a1f9991-7647-42bd-83fb-080d68b0a4f4","html_url":"https://github.com/Anamorphosee/stacktrace-decoroutinator","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Anamorphosee%2Fstacktrace-decoroutinator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Anamorphosee%2Fstacktrace-decoroutinator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Anamorphosee%2Fstacktrace-decoroutinator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Anamorphosee%2Fstacktrace-decoroutinator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Anamorphosee","download_url":"https://codeload.github.com/Anamorphosee/stacktrace-decoroutinator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247704571,"owners_count":20982298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","coroutines","debug","jvm","kotlin","kotlin-coroutines"],"created_at":"2024-11-12T19:04:12.367Z","updated_at":"2025-04-07T18:14:43.792Z","avatar_url":"https://github.com/Anamorphosee.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Maven Central](https://img.shields.io/maven-central/v/dev.reformator.stacktracedecoroutinator/stacktrace-decoroutinator-common 'JVM artifact')](https://central.sonatype.com/artifact/dev.reformator.stacktracedecoroutinator/stacktrace-decoroutinator-jvm)\n[![Gradle Plugin Portal Version](https://img.shields.io/gradle-plugin-portal/v/dev.reformator.stacktracedecoroutinator 'Gradle plugin')](https://plugins.gradle.org/plugin/dev.reformator.stacktracedecoroutinator)\n# Stacktrace-decoroutinator\nLibrary for recovering stack trace in exceptions thrown in Kotlin coroutines.\n\nSupports JVM 1.8 or higher and Android API 26 or higher.\n\n### Motivation\nCoroutines is a significant Kotlin feature which allows you to write asynchronous code in synchronous style.\n\nIt's absolutely perfect until you need to investigate problems in your code.\n\nOne of the common problems is the shortened stack trace in exceptions thrown in coroutines. For example, this code prints out the stack trace below:\n```kotlin\nimport kotlinx.coroutines.delay\nimport kotlinx.coroutines.runBlocking\n\nsuspend fun fun1() {\n    delay(10)\n    throw Exception(\"exception at ${System.currentTimeMillis()}\")\n}\n\nsuspend fun fun2() {\n    fun1()\n    delay(10)\n}\n\nsuspend fun fun3() {\n    fun2()\n    delay(10)\n}\n\nfun main() {\n    try {\n        runBlocking {\n            fun3()\n        }\n    } catch (e: Exception) {\n        e.printStackTrace()\n    }\n}\n```\n```\njava.lang.Exception: exception at 1641842199891\n  at MainKt.fun1(main.kt:6)\n  at MainKt$fun1$1.invokeSuspend(main.kt)\n  at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)\n  at kotlinx.coroutines.DispatchedTaskKt.resume(DispatchedTask.kt:234)\n  at kotlinx.coroutines.DispatchedTaskKt.dispatch(DispatchedTask.kt:166)\n  at kotlinx.coroutines.CancellableContinuationImpl.dispatchResume(CancellableContinuationImpl.kt:397)\n  at kotlinx.coroutines.CancellableContinuationImpl.resumeImpl(CancellableContinuationImpl.kt:431)\n  at kotlinx.coroutines.CancellableContinuationImpl.resumeImpl$default(CancellableContinuationImpl.kt:420)\n  at kotlinx.coroutines.CancellableContinuationImpl.resumeUndispatched(CancellableContinuationImpl.kt:518)\n  at kotlinx.coroutines.EventLoopImplBase$DelayedResumeTask.run(EventLoop.common.kt:494)\n  at kotlinx.coroutines.EventLoopImplBase.processNextEvent(EventLoop.common.kt:279)\n  at kotlinx.coroutines.BlockingCoroutine.joinBlocking(Builders.kt:85)\n  at kotlinx.coroutines.BuildersKt__BuildersKt.runBlocking(Builders.kt:59)\n  at kotlinx.coroutines.BuildersKt.runBlocking(Unknown Source)\n  at kotlinx.coroutines.BuildersKt__BuildersKt.runBlocking$default(Builders.kt:38)\n  at kotlinx.coroutines.BuildersKt.runBlocking$default(Unknown Source)\n  at MainKt.main(main.kt:21)\n  at MainKt.main(main.kt)\n```\nThe stack trace doesn't represent the true coroutine call stack: calls of functions `fun3` and `fun2` are absent.\n\nIn complex systems, even more calls may be missing. This can make debugging much more difficult.\n\nSome examples of suffering from this problem:\n- https://github.com/arrow-kt/arrow/issues/2647\n- https://stackoverflow.com/questions/54349418/how-to-recover-the-coroutines-true-call-trace\n- https://stackoverflow.com/questions/69226016/how-to-get-full-exception-stacktrace-when-using-await-on-completablefuture\n\nThe Kotlin team are known about the problem and has come up with a [solution](https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/topics/debugging.md#stacktrace-recovery), but it solves just a part of the cases.\nFor example, the exception from the example above still lacks some calls.\n\n### Solution\nStacktrace-decoroutinator replaces the coroutine awakening implementation.\n\nIt generates methods at runtime with names that match the entire coroutine call stack.\n\nThese methods don't do anything except call each other in the coroutine call stack order.\n\nThus, if the coroutine throws an exception, they mimic the real call stack of the coroutine during the creation of the exception stacktrace.\n\n### JVM\nThere are three ways to enable Stacktrace-decoroutinator for JVM.\n1. (recommended) If you build your project with Gradle, just apply Gradle plugin with id `dev.reformator.stacktracedecoroutinator`.\n2. Add dependency `dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm:2.4.8` and call method `DecoroutinatorJvmApi.install()`.\n3. Add `-javaagent:stacktrace-decoroutinator-jvm-agent-2.4.8.jar` to your JVM start arguments. Corresponding dependency is `dev.reformator.stacktracedecoroutinator:stacktrace-decoroutinator-jvm-agent:2.4.8`.\n\nThe first option generates auxiliary methods at build time and the other two use the Java instrumentation API at runtime.\n\nUsage example:\n```kotlin\npackage dev.reformator.stacktracedecoroutinator.jvmtests\n\nimport dev.reformator.stacktracedecoroutinator.jvm.DecoroutinatorJvmApi\nimport kotlinx.coroutines.runBlocking\nimport kotlinx.coroutines.yield\n\nobject Test {\n    suspend fun rec(depth: Int) {\n        if (depth == 0) {\n            yield()\n            throw Exception(\"exception at ${System.currentTimeMillis()}\")\n        }\n        rec(depth - 1)\n    }\n}\n\nfun main() {\n    DecoroutinatorJvmApi.install() // enable stacktrace-decoroutinator runtime\n    try {\n        runBlocking {\n            Test.rec(10)\n        }\n    } catch (e: Exception) {\n        e.printStackTrace() // print full stack trace with 10 recursive calls\n    }\n}\n```\nprints out:\n```\njava.lang.Exception: exception at 1725331728978\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:11)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test$rec$1.invokeSuspend(example.kt)\n\tat dev.reformator.stacktracedecoroutinator.common/dev.reformator.stacktracedecoroutinator.common.internal.DecoroutinatorSpecImpl.resumeNext(utils-common.kt:126)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.Test.rec(example.kt:13)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.ExampleKt$main$1.invokeSuspend(example.kt:21)\n\tat dev.reformator.stacktracedecoroutinator.common/dev.reformator.stacktracedecoroutinator.common.internal.AwakenerKt.callSpecMethods(awakener.kt:80)\n\tat dev.reformator.stacktracedecoroutinator.common/dev.reformator.stacktracedecoroutinator.common.internal.AwakenerKt.awake(awakener.kt:32)\n\tat dev.reformator.stacktracedecoroutinator.common/dev.reformator.stacktracedecoroutinator.common.internal.Provider.awakeBaseContinuation(provider-impl.kt:38)\n\tat dev.reformator.stacktracedecoroutinator.provider/dev.reformator.stacktracedecoroutinator.provider.DecoroutinatorProviderApiKt.awakeBaseContinuation(provider-api.kt:48)\n\tat kotlin.stdlib/kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:104)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.EventLoopImplBase.processNextEvent(EventLoop.common.kt:277)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.BlockingCoroutine.joinBlocking(Builders.kt:95)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.BuildersKt__BuildersKt.runBlocking(Builders.kt:69)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.BuildersKt.runBlocking(Unknown Source)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.BuildersKt__BuildersKt.runBlocking$default(Builders.kt:48)\n\tat kotlinx.coroutines.core/kotlinx.coroutines.BuildersKt.runBlocking$default(Unknown Source)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.ExampleKt.main(example.kt:20)\n\tat dev.reformator.stacktracedecoroutinator.jvm.tests/dev.reformator.stacktracedecoroutinator.jvmtests.ExampleKt.main(example.kt)\n```\n\n### Android\nFor Android there is only one option to enable Stacktrace-decoroutinator - apply the Gradle plugin `dev.reformator.stacketracedecoroutinator` to your application's project.\n```kotlin\nplugins {\n    id(\"dev.reformator.stacktracedecoroutinator\") version \"2.4.8\"\n}\n```\n\n### Using Decoroutinator Gradle plugin only for tests\nIf you want to use Decoroutinator for test only, it's recommended to separate your tests in a different Gradle subproject and apply Decoroutinator Gradle plugin to it.\nBut if you don't want to separate your tests, it's still possible by adding a configuration below to your `build.gradle.kts`:\n```kotlin\nstacktraceDecoroutinator {\n    androidTestsOnly = true\n}\n```\n\n### Using ProGuard\nIf you use ProGuard (usually for Android) please add the following exclusion rules:\n```\n-keep @kotlin.coroutines.jvm.internal.DebugMetadata class * { *; }\n-keep @dev.reformator.stacktracedecoroutinator.provider.DecoroutinatorTransformed class * { *; }\n```\n\n### Problem with Shadow Gradle plugin\nThere is [a bug](https://github.com/GradleUp/shadow/issues/882) in Shadow Gradle plugin which may lead to some build issues when both Decoroutinator as a Gradle plugin and Shadow are applied. But there are some [workarounds](https://github.com/GradleUp/shadow/issues/882#issuecomment-1715703146) for it. See more at https://github.com/Anamorphosee/stacktrace-decoroutinator/issues/46. \n\n### Problem with Jacoco\nUsing Jacoco and Decoroutinator as a Java agent may lead to the loss of code coverage. It's [a common Jacoco Problem](https://www.eclemma.org/jacoco/trunk/doc/classids.html). In order not to lose coverage, make sure that the Jacoco agent comes before the Decoroutinator agent. See more at https://github.com/Anamorphosee/stacktrace-decoroutinator/issues/24.\n\n### Troubleshooting\nYou can call function `DecoroutinatorCommonApi.getStatus { it() }` at runtime to check if Decoroutinator has been successfully installed.\n\n### Communication\nFeel free to ask any question at [Discussions](https://github.com/Anamorphosee/stacktrace-decoroutinator/discussions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanamorphosee%2Fstacktrace-decoroutinator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanamorphosee%2Fstacktrace-decoroutinator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanamorphosee%2Fstacktrace-decoroutinator/lists"}