dotnet-dump ——github项目

原文：

https://github.com/dotnet/diagnostics/blob/master/documentation/dotnet-dump-instructions.md

Intro

The dotnet-dump CLI global tool is way to collect and analyze the managed data structures in Windows and Linux dumps all without any native debugger involved. This makes creating a managed dump easier, and on some platforms like Alpine Linux or Linux ARM32/ARM64 (where a fully working lldb isn't available) it makes creating a managed dump possible. The dotnet-dump tool will allow you to run SOS commands to analyze crashes and the GC, but it isn't a native debugger so things like displaying the native stack frames aren't supported.

Here's a table showing how dotnet-dump fits into your dump debugging options:

	Windows native dumps	Windows managed eg from dotnet-dump collect	Linux system dump	Linux from dotnet-dump collect	macOS system dump	macOS from dotnet-dump collect
Visual Studio	yes	yes	yes (1)	yes (1)	no, need lldb	no
Windbg (including SOS)	yes	yes	yes (2)	yes (2)	no, need lldb	no
dotnet-dump analyze	no	yes	no	yes	no	yes

(1) Requires Visual Studio 2019 version 16.8 Preview 3 or later. (2) Requires WinDbg Preview version 1.0.2007.01003 or later.

Installing dotnet-dump

The first step is to install the dotnet-dump CLI global tool. This requires at least the 2.1 or greater .NET Core SDK to be installed. If you see the error message Tool 'dotnet-dump' is already installed, you will need to uninstall the global tool (see below).

$ dotnet tool install -g dotnet-dump
You can invoke the tool using the following command: dotnet-dump
Tool 'dotnet-dump' (version '3.0.47001') was successfully installed.

If this is the first global tool installed or you get message Could not execute because the specified command or file was not found. you need to add $HOME/.dotnet/tools to your path.

export PATH=$PATH:$HOME/.dotnet/tools

Using dotnet-dump

The next step is to collect a dump. This can be skipped if a core dump has already been generated by the operating system or createdump on Linux. The default dump type (--type option) is currently "full".

On Linux, the .NET runtime version must be 3.0 or greater. On Windows, dotnet-dump collect will work with any version of the .NET runtime.

$ dotnet-dump collect --process-id 1902
Writing minidump to file ./core_20190226_135837
Written 98983936 bytes (24166 pages) to core file
Complete

If you are running under docker, dump collection requires SYS_PTRACE docker capabilities (--cap-add=SYS_PTRACE or --privileged).

Now analyze the core dump.

$ dotnet-dump analyze ./core_20190226_135850
Loading core dump: ./core_20190226_135850
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>

This brings up an interactive command processor that accepts commands like:

> clrstack
OS Thread Id: 0x573d (0)
    Child SP               IP Call Site
00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
00007FFD28B43210 00007fb22aa9cedf [GCFrame: 00007ffd28b43210]
00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610]

To see the unhandled exception if your app was terminated:

> pe -lines
Exception object: 00007fb18c038590
Exception type:   System.Reflection.TargetInvocationException
Message:          Exception has been thrown by the target of an invocation.
InnerException:   System.Exception, Use !PrintException 00007FB18C038368 to see more.
StackTrace (generated):
SP               IP               Function
00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.dll!SymbolTestApp.Program.Foo2(Int32, System.String)+0x34 [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.dll!SymbolTestApp.Program.Foo1(Int32, System.String)+0x3a [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.dll!SymbolTestApp.Program.Main(System.String[])+0x6e [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]

StackTraceString: <none>
HResult: 80131604

To display the help:

> help
Usage:
  dotnet-dump [command]

Commands:
  exit, quit                           Exit interactive mode.
  help, soshelp <command>              Display help for a command.
  lm, modules                          Displays the native modules in the process.
  threads, setthread <threadid>        Sets or displays the current thread id for the SOS commands.
  clrstack <arguments>                 Provides a stack trace of managed code only.
  clrthreads <arguments>               List the managed threads running.
  dumpasync <arguments>                Displays info about async state machines on the garbage-collected heap.
  dumpassembly <arguments>             Displays details about an assembly.
  dumpclass <arguments>                Displays information about a EE class structure at the specified address.
  dumpdelegate <arguments>             Displays information about a delegate.
  dumpdomain <arguments>               Displays information all the AppDomains and all assemblies within the domains.
  dumpheap <arguments>                 Displays info about the garbage-collected heap and collection statistics about objects.
  dumpil <arguments>                   Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.
  dumplog <arguments>                  Writes the contents of an in-memory stress log to the specified file.
  dumpmd <arguments>                   Displays information about a MethodDesc structure at the specified address.
  dumpmodule <arguments>               Displays information about a EE module structure at the specified address.
  dumpmt <arguments>                   Displays information about a method table at the specified address.
  dumpobj <arguments>                  Displays info about an object at the specified address.
  dso, dumpstackobjects <arguments>    Displays all managed objects found within the bounds of the current stack.
  eeheap <arguments>                   Displays info about process memory consumed by internal runtime data structures.
  finalizequeue <arguments>            Displays all objects registered for finalization.
  gcroot <arguments>                   Displays info about references (or roots) to an object at the specified address.
  gcwhere <arguments>                  Displays the location in the GC heap of the argument passed in.
  ip2md <arguments>                    Displays the MethodDesc structure at the specified address in code that has been JIT-compiled.
  name2ee <arguments>                  Displays the MethodTable structure and EEClass structure for the specified type or method in the specified module.
  pe, printexception <arguments>       Displays and formats fields of any object derived from the Exception class at the specified address.
  syncblk <arguments>                  Displays the SyncBlock holder info.
  histclear <arguments>                Releases any resources used by the family of Hist commands.
  histinit <arguments>                 Initializes the SOS structures from the stress log saved in the debuggee.
  histobj <arguments>                  Examines all stress log relocation records and displays the chain of garbage collection relocations that may have led to the address passed in as an argument.
  histobjfind <arguments>              Displays all the log entries that reference an object at the specified address.
  histroot <arguments>                 Displays information related to both promotions and relocations of the specified root.
  setsymbolserver <arguments>          Enables the symbol server support
  soshelp <arguments>                  Displays all available commands when no parameter is specified, or displays detailed help information about the specified command. soshelp <command>

This command on Microsoft .NET Core SDK Linux docker images can throw Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies exception. To work around this problem install the "libc6-dev" package.

Uninstalling dotnet-dump

$ dotnet tool uninstall -g dotnet-dump
Tool 'dotnet-dump' (version '3.0.47001') was successfully uninstalled.

https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/linux-performance-tracing.md

Performance Tracing on Linux

When a performance problem is encountered on Linux, these instructions can be used to gather detailed information about what was happening on the machine at the time of the performance problem.

CoreCLR supports two different mechanisms for tracing .NET applications on Linux: EventPipe and LTTng. They both have tools built by the .NET team, namely dotnet-trace (which uses EventPipe) and PerfCollect (which uses LTTng). Here are some notable differences between the two tools to help you decide which to use:

1. PerfCollect leverages LTTng, which is a tracing framework built for the Linux kernel, so it can only be used on Linux. dotnet-trace is OS agnostic, so you can use it the same way across Windows/macOS and Linux.

2. PerfCollect uses perf, which gives you native callstacks. dotnet-trace can only give you managed callstack.

3. PerfCollect has a machine-wide scope, so it can be used to capture events from multiple processes running on the same machine. dotnet-trace is specific to a single runtime instance.

4. PerfCollect can be started prior to the process start, whereas dotnet-trace can only be attached after the process has started and runtime has set up the necessary internal data structures to allow attach.

5. PerfCollect supports .NET Core 2.1 or later. dotnet-trace supports .NET Core 3.0 or later.

LTTng and PerfCollect (.NET Core 2.1 or later)

Required Tools

• perfcollect: Bash script that automates data collection.
  • Available at http://aka.ms/perfcollect.
• PerfView: Windows-based performance tool that can also analyze trace files collected with Perfcollect.
  • Available at http://aka.ms/perfview.

Preparing Your Machine

Follow these steps to prepare your machine to collect a performance trace.

1. Download Perfcollect.

   curl -OL http://aka.ms/perfcollect

2. Make the script executable.

   chmod +x perfcollect

3. Install tracing prerequisites - these are the actual tracing libraries. For details on prerequisites, see below.

   sudo ./perfcollect install

Collecting a Trace

1. Have two shell windows available - one for controlling tracing, referred to as [Trace], and one for running the application, referred to as [App].

2. [App] Setup the application shell - this enables tracing configuration inside of CoreCLR.

   export COMPlus_PerfMapEnabled=1
   export COMPlus_EnableEventLog=1

3. [Trace] Start collection.

   sudo ./perfcollect collect sampleTrace

   Expected Output:

   Collection started.  Press CTRL+C to stop.

4. [App] Run the app - let it run as long as you need to in order to capture the performance problem. Generally, you don't need very long. As an example, for a CPU investigation, 5-10 seconds of the high CPU situation is usually enough.

   dotnet run

5. [Trace] Stop collection - hit CTRL+C.

   ^C
   ...STOPPED.
   
   Starting post-processing. This may take some time.
   
   Generating native image symbol files
   ...SKIPPED
   Saving native symbols
   ...FINISHED
   Exporting perf.data file
   ...FINISHED
   Compressing trace files
   ...FINISHED
   Cleaning up artifacts
   ...FINISHED
   
   Trace saved to sampleTrace.trace.zip

   The compressed trace file is now stored in the current working directory.