From ec74368a1570c176e0506f9f1a480414dbb0a62d Mon Sep 17 00:00:00 2001 From: Mike McLaughlin Date: Wed, 20 Mar 2019 09:31:36 -0700 Subject: [PATCH] Add dotnet-dump documentation for the preview. (#141) Upgrade to clrmd 1.0.5 containing the ELF dump fix. Add official build instructions. --- README.md | 7 +- .../building/official-build-instructions.md | 8 ++ documentation/dotnet-dump-instructions.md | 106 ++++++++++++++++++ eng/Versions.props | 2 +- src/Tools/dotnet-dump/Analyzer.cs | 3 +- 5 files changed, 123 insertions(+), 3 deletions(-) create mode 100644 documentation/building/official-build-instructions.md create mode 100644 documentation/dotnet-dump-instructions.md diff --git a/README.md b/README.md index b58c2737d..7212d8654 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ To test the resulting SOS and plugin: ```sh ./test.sh ``` - + ## Getting lldb Getting a version of lldb that works for your platform can be a problem sometimes. The version has to be at least 3.9 or greater because of a bug running SOS on a core dump that was fixed. Some Linux distros like Ubuntu it is easy as `sudo apt-get install lldb-3.9 python-lldb-3.9`. On other distros, you will need to build lldb. The directions below should give you some guidance. @@ -88,6 +88,10 @@ Getting a version of lldb that works for your platform can be a problem sometime * [SOS debugging for Windows](documentation/sos-debugging-extension-windows.md) * [Debugging a core dump](documentation/debugging-coredump.md) +## Tools + +* [dotnet-dump](documentation/dotnet-dump-instructions.md) - Dump collection and analysis utility. + ## New Features Symbol server support - The `setsymbolserver` command enables downloading the symbol files (portable PDBs) for managed assemblies during commands like `clrstack`, etc. See `soshelp setsymbolserver` for more details. @@ -104,6 +108,7 @@ Before executing the "bt" command to dump native frames to load the native symbo * [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) - More information about SOS. * [Debugging CoreCLR](https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md) - Instructions for debugging .NET Core and the CoreCLR runtime. * [dotnet/coreclr](https://github.com/dotnet/coreclr) - Source for the .NET Core runtime. +* [Official Build Instructions](documentation/building/official-build-instructions.md) - Internal official build instructions. [//]: # (Begin current test results) diff --git a/documentation/building/official-build-instructions.md b/documentation/building/official-build-instructions.md new file mode 100644 index 000000000..6a246ada0 --- /dev/null +++ b/documentation/building/official-build-instructions.md @@ -0,0 +1,8 @@ +Official Build Instructions +=========================== + +WARNING: These instructions will only work internally at Microsoft. + +To kick off an official build, go to this build definition: https://devdiv.visualstudio.com/DevDiv/_build?definitionId=9462 and queue build leaving all the build variables as their defaults. + +This signs and publishes dotnet-dump, dotnet-sos, dotnet-trace, dotnet-counters and Microsoft.Diagnostic.TestHepers packages to https://dotnetfeed.blob.core.windows.net/dotnet-core feed. diff --git a/documentation/dotnet-dump-instructions.md b/documentation/dotnet-dump-instructions.md new file mode 100644 index 000000000..37dc73b79 --- /dev/null +++ b/documentation/dotnet-dump-instructions.md @@ -0,0 +1,106 @@ +Dump collection and analysis utility (dotnet-dump) +================================================== + +The dotnet-dump CLI global tool is way to collect and analyze Windows and Linux dumps all without any native debugger involved like lldb on Linux. This is important on platforms like Alpine Linux where a fully working lldb isn't available. 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 isn't supported. + +## Installing dotnet-dump + +The first step is to install the dotnet-dump CLI global tool. This requires the 2.1 .NET Core SDK to be installed. + + $ dotnet tool install -g dotnet-dump --version 1.0.2-preview3.19151.2 --add-source https://dotnetfeed.blob.core.windows.net/dotnet-core/index.json + You can invoke the tool using the following command: dotnet-dump + Tool 'dotnet-dump' (version '1.0.2-preview3.19151.2') was successfully installed. + +## 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](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) on Linux. + +On Linux, it needs to be run as superuser: + + $ sudo -E dotnet dump collect --process-id 1902 + Writing minidump to file ./core_20190226_135837 + Written 98983936 bytes (24166 pages) to core file + Complete + +Now analyze the core dump. Only works on Linux for this preview. + + $ 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: +HResult: 80131604 + +To display the help: + + > help + Usage: + dotnet-dump [command] + + Commands: + exit, quit Exit interactive mode. + help Display help for a command. + lm, modules Displays the native modules in the process. + threads, setthread Sets or displays the current thread id for the SOS commands. + clrstack Provides a stack trace of managed code only. + clrthreads List the managed threads running. + dumpasync Displays info about async state machines on the garbage-collected heap. + dumpassembly Displays details about an assembly. + dumpclass Displays information about a EE class structure at the specified address. + dumpdelegate Displays information about a delegate. + dumpdomain Displays information all the AppDomains and all assemblies within the domains. + dumpheap Displays info about the garbage-collected heap and collection statistics about objects. + dumpil Displays the Microsoft intermediate language (MSIL) that is associated with a managed method. + dumplog Writes the contents of an in-memory stress log to the specified file. + dumpmd Displays information about a MethodDesc structure at the specified address. + dumpmodule Displays information about a EE module structure at the specified address. + dumpmt Displays information about a method table at the specified address. + dumpobj Displays info about an object at the specified address. + dso, dumpstackobjects Displays all managed objects found within the bounds of the current stack. + eeheap Displays info about process memory consumed by internal runtime data structures. + finalizequeue Displays all objects registered for finalization. + gcroot Displays info about references (or roots) to an object at the specified address. + gcwhere Displays the location in the GC heap of the argument passed in. + ip2md Displays the MethodDesc structure at the specified address in code that has been JIT-compiled. + name2ee Displays the MethodTable structure and EEClass structure for the specified type or method in the specified module. + pe, printexception Displays and formats fields of any object derived from the Exception class at the specified address. + syncblk Displays the SyncBlock holder info. + histclear Releases any resources used by the family of Hist commands. + histinit Initializes the SOS structures from the stress log saved in the debuggee. + histobj 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 Displays all the log entries that reference an object at the specified address. + histroot Displays information related to both promotions and relocations of the specified root. + setsymbolserver Enables the symbol server support + soshelp Displays all available commands when no parameter is specified, or displays detailed help information about the specified command. soshelp diff --git a/eng/Versions.props b/eng/Versions.props index a17e8bc06..bdeb7c9f2 100644 --- a/eng/Versions.props +++ b/eng/Versions.props @@ -20,7 +20,7 @@ 1.0.0-dev-63716-01 - 1.0.3 + 1.0.5 diff --git a/src/Tools/dotnet-dump/Analyzer.cs b/src/Tools/dotnet-dump/Analyzer.cs index 69939f3b7..d011926d7 100644 --- a/src/Tools/dotnet-dump/Analyzer.cs +++ b/src/Tools/dotnet-dump/Analyzer.cs @@ -33,7 +33,8 @@ namespace Microsoft.Diagnostic.Tools.Dump target = DataTarget.LoadCoreDump(dump_path.FullName); } else if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) { - target = DataTarget.LoadCrashDump(dump_path.FullName, CrashDumpReader.ClrMD); + //target = DataTarget.LoadCrashDump(dump_path.FullName, CrashDumpReader.ClrMD); + throw new PlatformNotSupportedException("Preview build: This is not yet implemented on Windows"); } else { throw new PlatformNotSupportedException($"Unsupported operating system: {RuntimeInformation.OSDescription}"); -- 2.34.1