[Async v2] Support Environment.StackTrace

[tommcdon]

Draft PR for initial feedback. A separate proposal will be created for the design change review/approval.

Summary

Enhance Environment.StackTrace (and the underlying StackTrace/StackFrame APIs) to reconstruct the logical async call chain when executing inside a runtime async (v2) method that has been resumed via continuation dispatch. Today, the stack trace shows only physical stack frames — thread pool internals and the immediately executing method — losing the caller context that is useful for logging.

Motivation

Current behavior (without this change)

When a runtime async v2 method yields and is later resumed by the thread pool, Environment.StackTrace shows only what is physically on the stack:

at System.Environment.get_StackTrace()
at MyApp.MiddleMethod()
at System.Runtime.CompilerServices.YieldAwaitable+YieldAwaiter.RunAction(Object)
at System.Threading.QueueUserWorkItemCallbackDefaultContext.Execute()
at System.Threading.ThreadPoolWorkQueue.Dispatch()
at System.Threading.PortableThreadPool+WorkerThread.WorkerDoWork(...)
at System.Threading.PortableThreadPool+WorkerThread.WorkerThreadStart()
at System.Threading.Thread.StartCallback()

The logical callers — which async methods are awaiting MiddleMethod — are completely absent. A developer has no way to determine why MiddleMethod is running.

Desired behavior

at System.Environment.get_StackTrace()
at MyApp.MiddleMethod() in MyApp.cs:line 42
at MyApp.OuterMethod() in MyApp.cs:line 30       ← continuation frame
at MyApp.EntryPoint() in MyApp.cs:line 15        ← continuation frame

Internal dispatch machinery (DispatchContinuations, thread pool frames) is hidden, and the logical async caller chain is reconstructed from the runtime's continuation data.

Why this matters

• Debugging: Log files with Environment.StackTrace are a useful diagnostic tool. Without the async caller chain, developers cannot trace the origin of a call.
• Parity with Exception stack traces: Exception stack traces in async v2 already inject continuation frames via STEF_CONTINUATION in excep.cpp. Environment.StackTrace should have equivalent behavior.
• Observability tooling: APM tools, logging frameworks, and profilers that consume StackTrace objects need the logical call chain to build meaningful traces.

Background: Runtime Async v2 Continuation Infrastructure

Continuation chain

When a runtime async method suspends (e.g., at an await that doesn't complete synchronously), the JIT creates a Continuation object that captures:

Field	Type	Purpose
Next	Continuation?	Next continuation in the linked list (the method that is awaiting this method)
ResumeInfo	ResumeInfo*	Pointer to resume function and diagnostic IP

The ResumeInfo struct contains:

Field	Type	Purpose
Resume	delegate*<Continuation, ref byte, Continuation?>	Function pointer to the IL stub that resumes the awaiting method
DiagnosticIP	void*	An instruction pointer within the suspending method, suitable for native-to-IL offset mapping

Dispatch

When an async method completes, RuntimeAsyncTaskCore.DispatchContinuations() iterates the continuation chain. It maintains a thread-local AsyncDispatcherInfo pointer (AsyncDispatcherInfo.t_current) that tracks the current dispatch state, including the NextContinuation to be processed.

IsAsyncMethod()

A MethodDesc is considered an async v2 method if it has AsyncMethodData with the AsyncCall flag set. This is populated during JIT compilation when the method uses runtime async calling conventions.

Existing precedent: Exception stack traces

In excep.cpp, when building exception stack traces, continuation frames are already injected with STEF_CONTINUATION:

// When pCf == NULL, this is an async v2 continuation frame
else
{
    stackTraceElem.flags |= STEF_CONTINUATION;
}

[dotnet-policy-service]

Tagging subscribers to this area: @steveisok, @dotnet/area-system-diagnostics
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

Adds support for reconstructing the logical async v2 continuation chain in Environment.StackTrace / StackTrace so stack traces taken during continuation dispatch include awaiting callers and hide internal dispatch machinery.

Changes:

• CoreCLR: capture async v2 continuation resume points during stack walking and inject them as STEF_CONTINUATION frames while filtering out DispatchContinuations.
• NativeAOT: augment the collected IP array by truncating dispatch frames and appending continuation DiagnosticIPs when AsyncDispatcherInfo.t_current is present.
• Tests: update existing reflection stack-frame expectations and add a new env-stacktrace regression test.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/tests/async/reflection/reflection.cs	Updates StackFrame.GetMethod() expectations to reflect injected logical async caller frames.
src/tests/async/env-stacktrace/env-stacktrace.csproj	Adds a new async test project for Environment.StackTrace async-v2 behavior.
src/tests/async/env-stacktrace/env-stacktrace.cs	New test validating that logical async callers appear and DispatchContinuations is filtered.
src/coreclr/vm/debugdebugger.h	Extends stack-walk data to track presence of async frames and collect continuation resume points.
src/coreclr/vm/debugdebugger.cpp	Extracts continuation chain from AsyncDispatcherInfo.t_current and injects continuation frames during stack trace collection.
src/coreclr/nativeaot/System.Private.CoreLib/src/System/Diagnostics/StackTrace.NativeAot.cs	Adds NativeAOT stack trace augmentation to append async continuation frames and truncate dispatch machinery.

---

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

In ExtractContinuationData, the loop uses local OBJECTREF variables (e.g., continuation and pNext) across calls that can GC (e.g., IL stub resolver access and SArray::Append). Only gc.continuation is protected, so if a GC occurs after reading pNext (or while still using continuation), these unprotected locals can become stale and lead to incorrect traversal or crashes. Consider protecting both the current and next OBJECTREFs (e.g., keep them in the GCPROTECT struct and exclusively use those protected slots when reading Next / advancing the loop).