[Async v2] Support Environment.StackTrace

[tommcdon]

Implementation for #125417

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]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

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

[jkotas]

Nit: #125417 (comment) proposes 0 as the default value. 0 means enable everything (that you probably do not want) in the current scheme. I think it would be more intuitive for 0 to mean default or to mean disable everything.

[noahfalk]

Mostly minor nits. The only thing that seemed potentially more serious is if the NativeAOT dispatcher IP caching still works when multiple generic instantiations are present.

[noahfalk]

As we mentioned earlier I'd suggest we get rid of option (2) just to lower the number of things we are asking folks for feedback on.

[noahfalk]

Suggested change

	if (!_isStackTraceHidden || _ipAddress == IntPtr.Zero)
	if (_ipAddress == IntPtr.Zero)

I'm not sure why we'd need to check _isStackTraceHidden? I assume the dispatch boundary will be hidden, it just seems superfluous to check unless this is a perf optimization?

[noahfalk]

Nit: Creating a private enum seems clearer than having to annotate magic values everywhere they appear.

[noahfalk]

Suggested change

	// Outer dispatchers represent already-completed async scopes and are not displayed.
	// Outer dispatchers represent logically distinct async stacks and are not displayed.

I suspect in many cases the outer dispatchers aren't complete but it doesn't matter because they aren't (necessarily) part of the same async stack.

[noahfalk]

I'd suggest lets not have this fallback. I don't think stitching the continuations in the wrong place on the stack will necessarily be better than not stitching them at all. Ideally we just ensure that we don't get into this buggy situation in the first place.

[noahfalk]

Not sure why hidden is part of the check?

[noahfalk]

Since the owning type is generic is there anything that guarantees us that only one copy of the code exists and it hasn't been specialized based on the generic type argument?

[noahfalk]

Nit: It would be nice if the tests verified the order of the frames in addition to their presence. We could split the stack trace by line and assert the method names show up on the expected line.

[noahfalk]

Was there any test which verified that synchronous frames at the leaf are always included? I may have missed it.

[jkotas]

It is interesting that we changed exception stacktraces unconditionally without a configuration switch, but we are introducing a configuration switch for current StackTrace and Environment.StackTrace. What's different between the two that we treat them differently?

(If we have discussed it, could you please remind me what's the difference?)

[jkotas]

(Our default stance in .NET Core is to avoid introducing config switch proactively unless we have strong evidence that it is going to be needed.)

[noahfalk]

Our default stance in .NET Core is to avoid introducing config switch

Its for short-term user feedback, not for permanent options. #125417 (comment)

What's different between the two that we treat them differently?

I would say Exception.StackTrace had a pre-existing design invariant that had a natural well-defined extension to async frames we agreed upon. Environment.StackTrace extends more ambiguously and we haven't reached a consensus which design is preferable. Lacking agreement on the dev team we hoped some user feedback would help.

As a minimal example:

async Task Main()
{
    await NonAsyncHelper();
}
Task NonAsyncHelper()
{
    return AsyncHelper();
}
async Task AsyncHelper()
{
    Console.WriteLine("BEFORE\n" + Environment.StackTrace);
    await Task.Yield();
    Console.WriteLine("AFTER\n" + Environment.StackTrace);
}

We expect the AFTER stack trace to be:

AsyncHelper
Main

Opinions differ on whether the 'NonAsyncHelper' frame should appear in the BEFORE stack or if the two stacks should be identical. Including it is truer to the physical stack abstraction and exposes the differences between async calls that complete with/without suspension. Excluding it gives more consistent stack traces that don't change behavior based on whether suspension occurred in child method calls.

[jkotas]

I wanted to see what's the actual experience eventually going to look like. I have done the following:

• Create dotnet new webapi using current .NET 11 P4 build
• Change the request lambda to be async and switch threads:

{
...
    await Task.Delay(1);
    Console.WriteLine(Environment.StackTrace);
    return forecast;
})

• Enable <Features>$(Features);runtime-async=on</Features> in the project
• Publish the project as self-contained and overwrite ASP.NET with runtime-async enabled build from Enable runtime-async for SharedFx-only libraries aspnetcore#66200

I got the following with this setup (this is expected):

   at System.Environment.get_StackTrace()
   at Program.<>c__DisplayClass0_0.<<Main>$>b__0() in C:\repro\Program.cs:line 38
   at System.Threading.Tasks.AwaitTaskContinuation.RunOrScheduleAction(Action action, Boolean allowInlining)
   at System.Threading.Tasks.Task.RunContinuations(Object continuationObject)
   at System.Threading.Tasks.Task.TrySetResult()
   at System.Threading.Tasks.Task.DelayPromise.CompleteTimedOut()
   at System.Threading.TimerQueueTimer.Fire(Boolean isThreadPool)
   at System.Threading.ThreadPoolWorkQueue.Dispatch()
   at System.Threading.PortableThreadPool.WorkerThread.WorkerDoWork(PortableThreadPool threadPoolInstance)
   at System.Threading.PortableThreadPool.WorkerThread.WorkerThreadStart()
   at System.Threading.Thread.StartCallback()

Then, I have replaced the runtime with the runtime from this PR and I got the following:

   at System.Environment.get_StackTrace()
   at Program.<>c__DisplayClass0_0.<<Main>$>b__0() in C:\repro\Program.cs:line 38
   at System.Runtime.CompilerServices.AsyncHelpers.RuntimeAsyncTask`1.DispatchContinuations()

Is it expected behavior? It has the threadpool boilerplate removed, but it does not show where the call actually came from. I would expect the stacktrace to show the path all the way to the kestrel.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

[jakobbotsch]

Is there a reason this is not using DiagnosticIP directly? The code below seems to be an indirect way to get to the method that contains DiagnosticIP anyway. It also would not work for interpreter continuations.

[jakobbotsch]

Does this inject all the async frames at the beginning of the frame list? It seems like odd behavior that is not going to make much sense when there are multiple dispatchers.
It would make more sense to me to do the walking in tandem, walking the native frames and replacing all dispatcher frames by continuation frames from that particular dispatcher frame's dispatcher information.

Pseudocode something like:

AsyncDispatcherInfo* dispatcherInfo = AsyncDispatcherInfo.t_current;
frame = InitiateStackWalk();
while (frame != null)
{
  if (IsInFrame(frame, dispatcherInfo))
  {
    AppendContinuationFrames(dispatcherInfo);
    dispatcherInfo = dispatcherInfo.Next;
  }
  else
  {
    AppendFrame(frame);
  }
  frame = NextFrame(frame);
}