Futures/并行代码堆栈追踪优化：遗留项目非ZIO替代方案问询

Great question—this is such a common pain point when debugging multi-threaded legacy JVM/Scala codebases. Default stack traces only show execution-time call stacks, missing the critical definition/composition phase context that makes debugging bearable. Here are practical, low-invasion approaches to replicate ZIO's rich error context without rewriting every Future or monad:

1. Wrap Futures with Contextual Metadata #

Create a lightweight wrapper around Future that captures and propagates context (like business identifiers, call snapshots, or parameter values) as you compose operations. When an exception occurs, append this context to the error to add missing context.

For example, a simple Scala wrapper:

import scala.concurrent.{ExecutionContext, Future}

case class ContextualFuture[A](underlying: Future[A], context: Map[String, String]) {
  def map[B](f: A => B)(implicit ec: ExecutionContext): ContextualFuture[B] =
    ContextualFuture(
      underlying.map(f).recover { case t: Throwable =>
        throw new RuntimeException(s"Failed with context: ${context.mkString(", ")}", t)
      },
      context
    )

  def flatMap[B](f: A => ContextualFuture[B])(implicit ec: ExecutionContext): ContextualFuture[B] =
    ContextualFuture(
      underlying.flatMap(a => f(a).underlying).recover { case t: Throwable =>
        throw new RuntimeException(s"Failed with context: ${context.mkString(", ")}", t)
      },
      context
    )

  // Add other Future methods as needed (recover, zip, etc.)
}

// Helper to create a ContextualFuture with initial context
object ContextualFuture {
  def apply[A](future: Future[A], contextKey: String, contextValue: String): ContextualFuture[A] =
    ContextualFuture(future, Map(contextKey -> contextValue))
}

You can gradually replace raw Future uses with this wrapper where debugging is critical—no need to overhaul everything at once.

2. Use AOP to Auto-Inject Context #

For larger codebases, use aspect-oriented programming to automatically capture context when Futures are created or composed, without manual wrapper code.

• Scala Macros: Write a macro that captures the call stack or custom annotation metadata at compile time, then attaches it to the Future's error handling chain.
• AspectJ: Define pointcuts for Future.apply, map, and flatMap calls, then inject context capture logic around those methods.

This approach minimizes code changes but requires some setup with your build tool (sbt/maven) to enable AOP or macro processing.

3. Custom ExecutionContext with Thread-Local Context #

Create a custom ExecutionContext that propagates context via ThreadLocal (with safeguards against thread pool contamination). When a task throws an exception, pull the context from ThreadLocal and attach it to the error.

Example:

import scala.concurrent.ExecutionContext

class ContextualEC(delegate: ExecutionContext, getContext: () => Map[String, String]) extends ExecutionContext {
  private val threadLocal = new ThreadLocal[Map[String, String]]()

  override def execute(runnable: Runnable): Unit = delegate.execute {
    val context = getContext()
    new Runnable {
      override def run(): Unit = {
        threadLocal.set(context)
        try {
          runnable.run()
        } catch {
          case t: Throwable =>
            throw new RuntimeException(s"Task failed with context: ${threadLocal.get().mkString(", ")}", t)
        } finally {
          threadLocal.remove() // Critical to avoid leaks/context pollution
        }
      }
    }
  }

  override def reportFailure(cause: Throwable): Unit = delegate.reportFailure(cause)
}

// Usage: Wrap your default EC
implicit val contextualEC: ExecutionContext = new ContextualEC(ExecutionContext.global, () => Map("requestId" -> "123"))

Just replace your existing implicit ExecutionContext with this wrapper, and all Future tasks will carry the context you define.

4. Java 9+ Stack Walking API for Richer Stacks #

Leverage Java's StackWalker API (available since Java 9) to capture cleaner, filtered call stacks at the point of Future creation. You can attach this stack trace to exceptions to see the composition phase flow.

Example stack capture utility:

import java.lang.StackWalker

def captureCompositionStack(): String = {
  StackWalker.getInstance(StackWalker.Option.RETAIN_CLASS_REFERENCE)
    .walk { stream =>
      stream
        .filter(frame => !frame.getClassName.startsWith("scala.concurrent") && !frame.getClassName.startsWith("java.util.concurrent"))
        .map(frame => s"${frame.getClassName}.${frame.getMethodName}:${frame.getLineNumber}")
        .toList
        .mkString("\n")
    }
}

Then use it in your Future error handling:

Future { /* your logic */ }
  .recover { case t: Throwable =>
    val stack = captureCompositionStack()
    throw new RuntimeException(s"Composition stack:\n$stack", t)
  }

5. Gradual ZIO Interop #

You don't have to rewrite everything to ZIO to use its error capabilities. Use ZIO's interop libraries to convert existing Futures to ZIO effects, then leverage ZIO's built-in context and error logging.

For example, with zio-interop-scala-future:

import zio._
import zio.interop.scalaFuture._

// Convert a legacy Future to ZIO
val zioEffect: ZIO[Any, Throwable, String] = 
  Future.successful("legacy data").toZIO

// Add context and error logging
val contextualEffect = zioEffect
  .tapError(error => ZIO.logError(s"Failed with requestId=123: ${error.getMessage}"))
  .provideLayer(ZIOConsole.live)

Run the ZIO effect where you need enhanced error visibility, and keep using Futures elsewhere. This lets you incrementally adopt ZIO's strengths without a full rewrite.

内容的提问来源于stack exchange，提问作者Alex