[API Proposal]: Include runtime async frames in Environment.StackTrace and System.Diagnostics.StackFrame

[tommcdon]

Background

Customers often use logging to diagnose issues in production code. Environment.StackTrace is one of the possible ways to log current callstack and method location. Async v1 code often times be undiagnosable due to thread switches, for example calling Environment.StackTrace immediately after await Task.Delay would be resumed on a new thread, and so there would be no indication on how execution led to the current method.

Runtime Async (also known as Async V2) gives us a new opportunity to improve the scenario. Previously in Async V1, async execution state was tracked in Roslyn compiler-generated code, requiring decoding of async state machines to track caller/callee chains. Now with Async V2, the runtime tracks async execution and so we can now extract the resume locations and output this information as part of a synchronous callstack.

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
• Observability tooling: APM tools, logging frameworks, and profilers that consume StackTrace objects need the logical call chain to build meaningful traces.

API Proposal

No API changes are suggested - this is changing behavior of an existing API to provide more information. API's affected are:

• System.Diagnostics.StackFrame
• System.Diagnostics.StackTrace.ctor
• System.Environment.StackTrace

Draft PR with proposed changes is here: #125396

API Usage

 static void PrintStackTrace()
 {
 // Get the current stack trace as a string
 string stackTrace = Environment.StackTrace;

 Console.WriteLine("Current Stack Trace:");
 Console.WriteLine(stackTrace);
 }

Alternative Designs

We could consider adding overloads that make the behavior opt-in or opt-out

Risks

Including runtime async frames might unexpectedly slow down performance for those that log callstacks in production scenarios, or bloat the log files themselves causing an extra expense on log storage.
Risk is mitigated by:

1. Runtime async is currently opt-in at the application level (at the time of writing in .NET 11)
2. Diagnostic benefits should outweigh performance or log size concerns. To mitigate this risk, the feature should include an opt-out app config switch to revert to fully non-async callstacks. We can also consider API overloads as well depending on feedback.

[dotnet-policy-service]

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

[MihuBot]

I'm a bot. Here is a possible related and/or duplicate issue (I may be wrong):

• new StackTrace() inside async methods -> Useless, Lack of frames with sync caller method (initiator) #60764

[noahfalk]

I like that we are doing this :D A variety of questions trying to dig more into the details of the design...

1. The APIs affected didn't mention System.Diagnostics.StackTrace.ctor, is that included?
2. If a runtime async method has a continuation that is an AsyncV1 Task does the stack chain through?
3. If a V1 async task is at the leaf of the stack does that get included in the stack trace?
4. If there are multiple continuations pending on the same frame, what do we show in the stack? Does it depend on the kind of continuation objects that are registered?
5. Does the stack capture anything about synchronous calls that created the async Task or that might be waiting on it? (Task.Start(), Task.Wait(), Task.Run())

[tommcdon]

The APIs affected didn't mention System.Diagnostics.StackTrace.ctor, is that included?

Added to the list

If a runtime async method has a continuation that is an AsyncV1 Task does the stack chain through?

Only runtime async v2 continuation chains are shown in the stack - no async v1 state machines are decoded. For example:

// ===== Mixed v2 → v1 → v2 chain =====

async Task<string> V2_Outer()
{
 return await V1_Middle();
}

[RuntimeAsyncMethodGeneration(false)] // Force v1 (state machine) generation
async Task<string> V1_Middle()
{
 return await V2_Inner();
}

async Task<string> V2_Inner()
{
 await Task.Yield(); // Force suspension
 return Environment.StackTrace;
}

V2_Outer().GetAwaiter().GetResult();

Would output the following stack:

at System.Environment.get_StackTrace()
at Program.V2_InnerMethod() in Program.cs:line XYZ
at System.Runtime.CompilerServices.YieldAwaitable.YieldAwaiter.RunAction(Object state)
at System.Threading.QueueUserWorkItemCallbackDefaultContext.Execute()
at System.Threading.ThreadPoolWorkQueue.Dispatch()
at System.Threading.PortableThreadPool.WorkerThread.WorkerDoWork(PortableThreadPool threadPoolInstance)
at System.Threading.PortableThreadPool.WorkerThread.WorkerThreadStart()
at System.Threading.Thread.StartCallback()

If a V1 async task is at the leaf of the stack does that get included in the stack trace?

Same as the above - if the left (current) frame is an async v1 state machine, we do not decode it and will simply show the synchronous stack on the thread. For example:

// ===== V1 Leaf - v2 → v2 → v1 chain =====

async Task<string> V2_Outer()
{
 return await V2_Middle();
}

async Task<string> V2_Middle()
{
 return await V1_Leaf();
}

[RuntimeAsyncMethodGeneration(false)] // Force v1 (state machine) generation
async Task<string> V1_Leaf()
{
 await Task.Yield();
 return Environment.StackTrace;
}

V2_Outer().GetAwaiter().GetResult();

Would output the following stack:

at System.Environment.get_StackTrace()
at Program.V1_Leaf() in Program.cs:line XYZ
at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1.AsyncStateMachineBox`1.ExecutionContextCallback(Object s)
at System.Threading.ExecutionContext.RunFromThreadPoolDispatchLoop(Thread threadPoolThread, ExecutionContext executionContext, ContextCallback callback, Object state)
at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1.AsyncStateMachineBox`1.MoveNext(Thread threadPoolThread)
at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1.AsyncStateMachineBox`1.ExecuteFromThreadPool(Thread threadPoolThread)
at System.Threading.ThreadPoolWorkQueue.Dispatch()
at System.Threading.PortableThreadPool.WorkerThread.WorkerDoWork(PortableThreadPool threadPoolInstance)
at System.Threading.PortableThreadPool.WorkerThread.WorkerThreadStart()
at System.Threading.Thread.StartCallback()

If there are multiple continuations pending on the same frame, what do we show in the stack? Does it depend on the kind of continuation objects that are registered?

Continuation chains should be single linked lists. It is possible that there are "nested" wait chains on the same thread. For that case, we only show the first one in the list. I experimented it trying to show "nested" continuations but felt it ended up being more confusing than helpful.

For example:

async Task Run()
{
 TaskCompletionSource tcs = new TaskCompletionSource();
 Task t = BarCaller(tcs.Task);
 Task t2 = FooCaller(tcs);
 await Task.WhenAll(t, t2);
}

async Task FooCaller(TaskCompletionSource tcs)
{
 await Task.Yield();
 Console.WriteLine("FooCaller calling Foo...");
 await Foo(tcs);
}

async Task Foo(TaskCompletionSource tcs)
{
 //await Task.Yield();
 Console.WriteLine("Foo delay...");
 await Task.Delay(1);
 Console.WriteLine("Foo setting tcs...");
 tcs.SetResult();
}

async Task BarCaller(Task task)
{
 Console.WriteLine("BarCaller yielding...");
 await Task.Yield();
 Console.WriteLine("BarCaller calling Bar...");
 await Bar(task);
}

async Task Bar(Task task)
{
 Console.WriteLine("Bar yielding...");
 await Task.Yield();
 Console.WriteLine("Bar awaiting the tsc task...");
 await task;
 Console.WriteLine("Bar dumping the stack...");
 Console.WriteLine(Environment.StackTrace);
}

Run().GetAwaiter().GetResult();

Would output:

...
Bar dumping the stack...
 at System.Environment.get_StackTrace()
 at AsyncTest_tcs.Bar(Task task) in Program.cs:line XYZ1
 at AsyncTest_tcs.BarCaller(Task task) in Program.cs:line XYZ2
 at AsyncTest_tcs.FooCaller(TaskCompletionSource tcs) in Program.cs:line XYZ3

Does the stack capture anything about synchronous calls that created the async Task or that might be waiting on it? (Task.Start(), Task.Wait(), Task.Run())

The feature as it is proposed today treats existing async V1 task and state machine decoding as out of scope, so we only display what is included in the runtime async continuation data which does not include calls to Task.Start/Wait/Run.

[noahfalk]

Thanks Tom!

Async V1 handling

The feature as it is proposed today treats existing async V1 task and state machine decoding as out of scope

I'd be curious to dig into this a bit more - its not obvious to me that it should be out of scope. Certainly there would be more work involved so I don't want to expand the scope cavalierly, but a few considerations that push me in that direction:

• Changing Environment.StackTrace is a breaking change that will probably require some .NET developers to make adjustments to their application code if they were parsing it or had certain UX expectations around it. If we think devs will want Async V1 support ideally we do it all at once rather than spreading breaking changes over multiple releases.
• In the short term many libraries might continue to use Async V1 because the code hasn't been recompiled to target V2.
• Longer term I'm not aware we have any plan to completely phase out Async V1 so it would continue to be a rough edge in the feature indefinitely. The first example that came to mind is code that uses Task.WhenAny/WhenAll. I know there are plenty of other custom task types out there though I'm not sure how many of them are likely to run app developer code while they are on the async stack.

I think there are varying degrees of support we could have for V1. For example we could probably trace a continuation chain through V1 tasks without rendering anything into the stacktrace, or we could render some basic information like a method name, or we could really dig into it and disassemble the Async V1 state machine to infer an IL offset -> file info. IMO its worth looking into. (@jkotas, @stephentoub, @davidfowl - I'd be glad to get your perspectives on this)

When does synchronous dispatch logic appear

Another question that would be good to dig into... what synchronous frames get shown on the stack? The initial example in the issue showed only synchronous frames that were closer to the leaf than the most recent async frame:

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

Would output the following stack:

However in this V2_InnerMethod example from above, V2_InnerMethod is implemented with async V2 but it is showing all of the synchronous dispatch logic in the stack. If I nievely imagine the pattern shown in the first example and apply it here then I wouldn't expect the YieldAwaitable frame or anything below it to show up:

at System.Environment.get_StackTrace()
at Program.V2_InnerMethod() in Program.cs:line XYZ
at System.Runtime.CompilerServices.YieldAwaitable.YieldAwaiter.RunAction(Object state)
at System.Threading.QueueUserWorkItemCallbackDefaultContext.Execute()
at System.Threading.ThreadPoolWorkQueue.Dispatch()
at System.Threading.PortableThreadPool.WorkerThread.WorkerDoWork(PortableThreadPool threadPoolInstance)
at System.Threading.PortableThreadPool.WorkerThread.WorkerThreadStart()
at System.Threading.Thread.StartCallback()

I'm guessing that we are rendering the stacks differently depending on whether control entered at the start of the function or what dispatcher was responsible for resuming after an await. That feels like unnecessary implementation detail we'd be better off not leaking into the user experience if we can help it.

Nested waits

It is possible that there are "nested" wait chains on the same thread. For that case, we only show the first one in the list. I experimented it trying to show "nested" continuations but felt it ended up being more confusing than helpful.

I agree. I think it is a cleaner representation of the async abstraction to follow a single async continuation chain to its root, disregarding the dispatch logic or outer dispatchers that might be present on the same OS thread stack.

opt-in/out

We could consider adding overloads that make the behavior opt-in or opt-out

One place that might fit well is new overloads or options on the StackTrace constructor. Additionally a config switch that lets folks preserve the current Environment.StackTrace behavior seems like a cheap and helpful mitigation for folks who don't want the async-aware behavior.