Inspect managed stack traces (dotnet-stack)

This article applies to: ✔️ dotnet-stack version 5.0.221401 and later versions

Install

There are two ways to download and install dotnet-stack:

Synopsis

dotnet-stack [-h, --help] [--version] <command>

Description

The dotnet-stack tool:

  • Is a cross-platform .NET Core tool.
  • Captures and prints the managed stacks for all threads in the target .NET process.
  • Utilizes EventPipe tracing provided by the .NET Core runtime.

Options

  • -h|--help

    Shows command-line help.

  • --version

    Displays the version of the dotnet-stack utility.

Commands

Command Description
dotnet-stack report Prints the stack trace for each thread in the target process.
dotnet-stack ps Lists the dotnet processes that stack traces can be collected from.

dotnet-stack report

Prints the stack trace for each thread in the target process.

Synopsis

dotnet-stack report -p|--process-id <pid>
                    -n|--name <process-name>
                    [-h|--help]

Options

  • -n, --name <name>

    The name of the process to collect the trace from.

  • -p|--process-id <PID>

    The process ID to collect the trace from.

dotnet-stack ps

Lists the dotnet processes that stack traces can be collected from. dotnet-stack version 6.0.320703 and later versions also display the command-line arguments that each process was started with, if available.

Synopsis

dotnet-stack ps [-h|--help]

Example

Suppose you start a long-running app using the command dotnet run --configuration Release. In another window, you run the dotnet-stack ps command. The output you'll see is as follows. The command-line arguments, if any, are shown in dotnet-stack version 6.0.320703 and later.

> dotnet-stack ps
  
  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

Report managed stacks with dotnet-stack

To report managed stacks using dotnet-stack:

  • Get the process identifier (PID) of the .NET Core application to report stacks from.

    • On Windows, you can use Task Manager or the tasklist command, for example.
    • On Linux, for example, the ps command.
    • dotnet-stack ps
  • Run the following command:

    dotnet-stack report --process-id <PID>
    

    The preceding command generates output similar to the following:

    Thread (0x48839B):
      [Native Frames]
      System.Console!System.IO.StdInReader.ReadKey(bool&)
      System.Console!System.IO.SyncTextReader.ReadKey(bool&)
      System.Console!System.ConsolePal.ReadKey(bool)
      System.Console!System.Console.ReadKey()
      StackTracee!Tracee.Program.Main(class System.String[])
    

    The output of dotnet-stack follows the following form:

    • Comments in the output are prefixed with #.
    • Each thread has a header that includes the native thread ID: Thread (<thread-id>):.
    • Stack frames follow the form Module!Method.
    • Transitions to unmanaged code are represented as [Native Frames] in the output.
    # comment
    Thread (0x1234):
      module!Method
      module!Method
    
    Thread (0x5678):
      [Native Frames]
      Module!Method
      Module!Method
    

Note

Stopping the process can take a long time (up to several minutes) for very large applications. The runtime needs to send over the type and method information for all managed code that was captured to resolve function names.

Next steps