From: Mike McLaughlin Date: Tue, 18 Jun 2019 01:34:55 +0000 (-0700) Subject: Update documentation (#345) X-Git-Tag: submit/tizen/20190813.035844~4^2^2~31 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f84b70d976b9a111e515013eec36f94cd49c5b89;p=platform%2Fcore%2Fdotnet%2Fdiagnostics.git Update documentation (#345) Update documentation --- diff --git a/README.md b/README.md index 3aa6de88e..5b58cd745 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ .NET Core Diagnostics Repo ========================== -**Currently under construction** - -This repository contains the source code for various .NET Core runtime diagnostic tools. It currently contains SOS, the managed portion of SOS and the lldb SOS plugin. The goals of this repo is to build SOS and the lldb SOS plugin for the portable (glibc based) Linux platform (Centos 7) and the platforms not supported by the portable (musl based) build (Centos 6, Alpine, and macOS) and to test across various indexes in a very large matrix: OSs/distros (Centos 6/7, Ubuntu, Alpine, Fedora, Debian, RHEL 7.2), architectures (x64, x86, arm, arm64), lldb versions (3.9, 4.0, 5.0, 6.0) and .NET Core versions (1.1, 2.0.x, 2.1). +This repository contains the source code for various .NET Core runtime diagnostic tools. It currently contains SOS, the managed portion of SOS, the lldb SOS plugin and various global diagnostic tools. The goals of this repo is to build SOS and the lldb SOS plugin for the portable (glibc based) Linux platform (Centos 7) and the platforms not supported by the portable (musl based) build (Centos 6, Alpine, and macOS) and to test across various indexes in a very large matrix: OSs/distros (Centos 6/7, Ubuntu, Alpine, Fedora, Debian, RHEL 7.2), architectures (x64, x86, arm, arm64), lldb versions (3.9, 4.0, 5.0, 6.0) and .NET Core versions (1.1, 2.0.x, 2.1). Another goal to make it easier to obtain a version of lldb (currently 3.9) with scripts and documentation for platforms/distros like Centos, Alpine, Fedora, etc. that by default provide really old versions. This repo will also allow out of band development of new SOS and lldb plugin features like symbol server support for the .NET Core runtime and solve the source build problem having SOS.NETCore (managed portion of SOS) in the coreclr repo. +See the github release tab for notes on SOS and diagnostic tools releases. + -------------------------- ## Building the Repository diff --git a/documentation/building/linux-instructions.md b/documentation/building/linux-instructions.md index 74c963328..998a49762 100644 --- a/documentation/building/linux-instructions.md +++ b/documentation/building/linux-instructions.md @@ -8,7 +8,7 @@ Toolchain Setup The following instructions will install the required packages. This only needs to be done once per machine. These instructions assume that you already have "sudo" installed. It is also recommended to create a github fork of the diagnostics repo and cloning that instead of https://github.com/dotnet/diagnostics.git directly. -To build or cross build for ARM on Windows or Linux see the instructions [here](https://github.com/mikem8361/coreclr/blob/master/Documentation/building/cross-building.md) in the coreclr repo. +To build or cross build for ARM on Windows or Linux see the instructions [here](https://github.com/dotnet/coreclr/blob/master/Documentation/building/cross-building.md#generating-the-rootfs) in the coreclr repo. You will need to clone the coreclr [repo](https://github.com/dotnet/coreclr.git) and build the appropriate "rootfs" for arm or arm64 using these instructions. You only need to do this once. #### Ubuntu 14.04 #### diff --git a/documentation/debugging-coredump.md b/documentation/debugging-coredump.md index 4cc420d06..3f07d00f6 100644 --- a/documentation/debugging-coredump.md +++ b/documentation/debugging-coredump.md @@ -18,7 +18,7 @@ Copy the core dump to a tmp directory. Download the modules and symbols for the core dump: - ~$ dotnet symbol /tmp/dump/coredump.32232 + ~$ dotnet-symbol /tmp/dump/coredump.32232 ### Install lldb ### @@ -38,6 +38,39 @@ Even if the core dump was not generated on this machine, the native and managed ### Launch lldb under MacOS ### ~$ lldb - (lldb) target create --core /tmp/dump/coredump.32232 - -The MacOS lldb has a bug that prevents SOS clrstack from properly working. Because of this bug SOS can't properly match the lldb native with with the managed thread OSID displayed by `clrthreads`. The `setsostid` command is a work around for this lldb bug. + (lldb) target create --core /cores/core.32232 + +The MacOS lldb has a bug that prevents SOS clrstack from properly working. Because of this bug SOS can't properly match the lldb native with with the managed thread OSID displayed by `clrthreads`. The `setsostid` command is a work around for this lldb bug. This command maps the OSID from this command: + +``` +(lldb) clrthreads +ThreadCount: 2 +UnstartedThread: 0 +BackgroundThread: 1 +PendingThread: 0 +DeadThread: 0 +Hosted Runtime: no + Lock + DBG ID OSID ThreadOBJ State GC Mode GC Alloc Context Domain Count Apt Exception +XXXX 1 1fbf31 00007FBEC9007200 20020 Preemptive 0000000190191710:0000000190191FD0 00007FBEC981F200 0 Ukn System.IO.DirectoryNotFoundException 0000000190172b88 +XXXX 2 1fbf39 00007FBEC9008000 21220 Preemptive 0000000000000000:0000000000000000 00007FBEC981F200 0 Ukn (Finalizer) +``` +To one of the native thread indexes from this command: + +``` +(lldb) thread list +Process 0 stopped +* thread #1: tid = 0x0000, 0x00007fffb5595d42 libsystem_kernel.dylib`__pthread_kill + 10, stop reason = signal SIGSTOP + thread #2: tid = 0x0001, 0x00007fffb558e34a libsystem_kernel.dylib`mach_msg_trap + 10, stop reason = signal SIGSTOP + thread #3: tid = 0x0002, 0x00007fffb559719e libsystem_kernel.dylib`poll + 10, stop reason = signal SIGSTOP + thread #4: tid = 0x0003, 0x00007fffb5595a3e libsystem_kernel.dylib`__open + 10, stop reason = signal SIGSTOP + thread #5: tid = 0x0004, 0x00007fffb5595bf2 libsystem_kernel.dylib`__psynch_cvwait + 10, stop reason = signal SIGSTOP + thread #6: tid = 0x0005, 0x00007fffb5595bf2 libsystem_kernel.dylib`__psynch_cvwait + 10, stop reason = signal SIGSTOP + thread #7: tid = 0x0006, 0x00007fffb558e34a libsystem_kernel.dylib`mach_msg_trap + 10, stop reason = signal SIGSTOP +``` + +Map the main managed thread `1fbf31` to native thread index `1`: + +``` +(lldb) setsostid 1fbf31 1 +``` diff --git a/documentation/dotnet-dump-instructions.md b/documentation/dotnet-dump-instructions.md index eb7fd9c50..5115a9468 100644 --- a/documentation/dotnet-dump-instructions.md +++ b/documentation/dotnet-dump-instructions.md @@ -23,7 +23,7 @@ The next step is to collect a dump. This can be skipped if a core dump has alrea On Linux, the runtime version must be 3.0 or greater. - $ dotnet dump collect --process-id 1902 + $ dotnet-dump collect --process-id 1902 Writing minidump to file ./core_20190226_135837 Written 98983936 bytes (24166 pages) to core file Complete diff --git a/documentation/dotnet-trace-instructions.md b/documentation/dotnet-trace-instructions.md index 6b4eade5c..52983c0d4 100644 --- a/documentation/dotnet-trace-instructions.md +++ b/documentation/dotnet-trace-instructions.md @@ -4,7 +4,7 @@ The dotnet-trace tool is a cross-platform CLI global tool that enables the colle ## Installing dotnet-trace -The first step is to install the dotnet-trace CLI global tool. This requires at least version 2.1 of the SDK to be installed. +The first step is to install the dotnet-trace CLI global tool. ```cmd $ dotnet tool install --global dotnet-trace --version 1.0.4-preview6.19311.1 diff --git a/documentation/installing-sos-instructions.md b/documentation/installing-sos-instructions.md index 62c0fb41d..9a92a5a47 100644 --- a/documentation/installing-sos-instructions.md +++ b/documentation/installing-sos-instructions.md @@ -7,11 +7,9 @@ The first step is to install the dotnet-sos CLI global tool. This requires at le You can invoke the tool using the following command: dotnet-sos Tool 'dotnet-sos' (version '1.0.4-preview6.19311.1') was successfully installed. - - The next step is use this global tool to install SOS. - $ dotnet sos install + $ dotnet-sos install Installing SOS to /home/mikem/.dotnet/sos from /home/mikem/.dotnet/tools/.store/dotnet-sos/1.0.4-preview6.19311.1/dotnet-sos/1.0.4-preview6.19311.1/tools/netcoreapp2.1/any/linux-x64 Creating installation directory... Copying files... @@ -73,7 +71,7 @@ Now any time you run lldb, SOS will automatically be loaded and the symbol downl The installer needs to be run again: - $ dotnet sos install + $ dotnet-sos install Installing SOS to /home/mikem/.dotnet/sos from /home/mikem/.dotnet/tools/.store/dotnet-sos/1.0.4-preview6.19311.1/dotnet-sos/1.0.4-preview6.19311.1/tools/netcoreapp2.1/any/linux-x64 Installing over existing installation... Creating installation directory... @@ -86,7 +84,7 @@ The installer needs to be run again: To uninstall and remove the lldb configuration run this command: - $ dotnet sos uninstall + $ dotnet-sos uninstall Uninstalling SOS from /home/mikem/.dotnet/sos Reverting /home/mikem/.lldbinit file - LLDB will no longer load SOS at startup SOS uninstall succeeded diff --git a/documentation/installing-sos-windows-instructions.md b/documentation/installing-sos-windows-instructions.md index 600ae5957..7f6452834 100644 --- a/documentation/installing-sos-windows-instructions.md +++ b/documentation/installing-sos-windows-instructions.md @@ -53,7 +53,7 @@ It is recommended that you update to the newer versions of the Windows debugger, Run the installer: - C:\Users\mikem>dotnet sos install + C:\Users\mikem>dotnet-sos install Installing SOS to C:\Users\mikem\.dotnet\sos from C:\Users\mikem\.dotnet\tools\.store\dotnet-sos\1.0.4-preview6.19311.1\dotnet-sos\1.0.4-preview6.19311.1\tools\netcoreapp2.1\any\win-x64 Creating installation directory... Copying files... diff --git a/documentation/tutorial/installing_the_diagnostics_tools.md b/documentation/tutorial/installing_the_diagnostics_tools.md index df315f2b6..b6c5f7234 100644 --- a/documentation/tutorial/installing_the_diagnostics_tools.md +++ b/documentation/tutorial/installing_the_diagnostics_tools.md @@ -17,8 +17,6 @@ In the .NET full/Windows world, we have a myriad of performance counters that ca > dotnet tool install --global dotnet-trace --version 1.0.4-preview6.19311.1 > ``` -Please note, the dotnet-trace tool is version independent but as of right now (preview 5) it requires the 2.1 runtime to be installed to work. This will be fixed moving forward. - ### dotnet-dump In order to generate core dumps for .net core apps, you can use the dotnet-dump tool. To install the tool, run the following command: @@ -27,8 +25,6 @@ In order to generate core dumps for .net core apps, you can use the dotnet-dump > dotnet tool install --global dotnet-dump --version 1.0.4-preview6.19311.1 > ``` -Please note, the dotnet-trace tool is version independent but as of right now (preview 5) it requires the 2.1 runtime to be installed to work. This will be fixed moving forward. - ### dotnet-symbol In order to debug core dumps, the correct symbols need to be available. The dotnet-symbol tool allows you to point to a core dump and it will automatically download the symbols for you. To install the tool, run: