See the section below on how to clone, build and test the repo.
-#### Alpine 3.6 ####
+#### Alpine 3.8/3.9 ####
-Currently there is no lldb that works on Alpine.
+Install the required packages:
-Issue https://github.com/dotnet/diagnostics/issues/73
+ sudo apk add autoconf bash clang clang-dev cmake coreutils curl gcc gettext-dev git icu-dev krb5-dev libunwind-dev llvm make openssl openssl-dev python which
#### CentOS 6 ####
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.
+To kick off an official build, go to this build definition: https://dev.azure.com/dnceng/internal/_build?definitionId=528.
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.
+
+To release the latest tools:
+
+1) Merge all the commits for this release from the master branch to the release/3.0 branch.
+2) Kick off an official build from the release/3.0 branch.
+3) Change all the package version references in the documentation folder to this official build's package version. Commit/merge to master and release/3.0.
+4) Download the above packages from the successful official build under "Artifacts" -> "packages".
+5) Upload these packages to nuget.org.
+6) Create a new "release" in the [releases](https://github.com/dotnet/diagnostics/releases) diagnostics repo release tab with the package version (not the official build id) as the "tag". Add any release notes about known issues, issues fixed and new features.
### Getting symbols ###
+Because SOS now has symbol download support, this step can be skipped if the matching version of the "host" program is available on the machine loading the dump. Usually the host program is "dotnet" but each .NET Core SDK has a different version.
+
First install the dotnet CLI symbol tool. This only needs to be down once. See this [link](https://github.com/dotnet/symstore/tree/master/src/dotnet-symbol#install) for more details.
~$ dotnet tool install -g dotnet-symbol
### Launch lldb under Linux ###
- ~$ lldb
- (lldb) target create --core /tmp/dump/coredump.32232
+ ~$ lldb --core /tmp/dump/coredump.32232 <host-program>
+ Core file '/tmp/dump/coredump.32232' (x86_64) was loaded.
+ (lldb)
+
+The `<host-program>` is the native program that started the .NET Core application. It is usually `dotnet` unless the application is self contained and then it is the name of application without the .dll.
+
+Add the directory with the core dump and symbols to the symbol search path:
+
+ (lldb) setsymbolserver -directory /tmp/dump
+ Added symbol directory path: /tmp/dump
+ (lldb)
Even if the core dump was not generated on this machine, the native and managed .NET Core symbols should be available along with all the SOS commands.
### Launch lldb under MacOS ###
- ~$ lldb
- (lldb) target create --core /cores/core.32232
+ ~$ lldb --core /cores/core.32232 <host-program>
+ (lldb)
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:
|**PrintException** [**-nested**] [**-lines**] [\<*Exception object address*>]<br /><br /> -or-<br /><br /> **PE** [**-nested**] [\<*Exception object address*>]|Displays and formats fields of any object derived from the <xref:System.Exception> class at the specified address. If you do not specify an address, the **PrintException** command displays the last exception thrown on the current thread.<br /><br /> The **-nested** option displays details about nested exception objects.<br /><br /> The **-lines** option displays source information, if available.<br /><br /> You can use this command to format and view the `_stackTrace` field, which is a binary array.|
|**SyncBlk** [**-all** | \<*syncblk number*>]|Displays the specified `SyncBlock` structure or all `SyncBlock` structures. If you do not pass any arguments, the **SyncBlk** command displays the `SyncBlock` structure corresponding to objects that are owned by a thread.<br /><br /> A `SyncBlock` structure is a container for extra information that does not need to be created for every object. It can hold COM interop data, hash codes, and locking information for thread-safe operations.|
|**SOSFlush**|Flushes an internal SOS cache.|
-|**SetSymbolServer** [**-ms**] [**-disable**] [**-log**] [**-cache** \<cache-path>] [**-loadsymbols**] [\<symbol-server-URL>]|Enables the symbol server downloading support.<br/><br/>The **-ms** option enables downloading from the public Microsoft symbol server.<br/><br/>The **-disable** option turns on the symbol download support.<br/><br/>The **-cache** \<cache-path> option specifies a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.<br/><br/>The **-log** option enables symbol download logging.<br/><br/>The **-loadsymbols** option attempts to download the native .NET Core symbols for the runtime.|
+|**SetSymbolServer** [**-ms**] [**-disable**] [**-log**] [**-loadsymbols**] [**-cache** \<cache-path>] [**-directory** \<search-directory>] [**-sympath** \<windows-symbol-path>] [\<symbol-server-URL>]|Enables the symbol server downloading support.<br/><br/>The **-ms** option enables downloading from the public Microsoft symbol server.<br/><br/>The **-disable** option turns on the symbol download support.<br/><br/>The **-cache** \<cache-path> option specifies a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.<br/><br/>The **-directory** option add a path to search for symbols. Can be more than one.<br/><br/>The **-sympath** option adds server, cache and directory paths in the Windows symbol path format.<br/><br/>The **-log** option enables symbol download logging.<br/><br/>The **-loadsymbols** option attempts to download the native .NET Core symbols for the runtime.|
|**Token2EE** \<*module name*> \<*token*>|Turns the specified metadata token in the specified module into a `MethodTable` structure or `MethodDesc` structure.<br /><br /> You can pass `*` for the module name parameter to find what that token maps to in every loaded managed module. You can also pass the debugger's name for a module, such as `mscorlib` or `image00400000`.|
|**Threads** (**clrthreads**) [**-live**] [**-special**]|Displays all managed threads in the process.<br /><br /> The **Threads** command displays the debugger shorthand ID, the CLR thread ID, and the operating system thread ID. Additionally, the **Threads** command displays a Domain column that indicates the application domain in which a thread is executing, an APT column that displays the COM apartment mode, and an Exception column that displays the last exception thrown in the thread.<br /><br /> The **-live** option displays threads associated with a live thread.<br /><br /> The **-special** option displays all special threads created by the CLR. Special threads include garbage collection threads (in concurrent and server garbage collection), debugger helper threads, finalizer threads, <xref:System.AppDomain> unload threads, and thread pool timer threads.|
|**ThreadState \<** *State value field* **>**|Displays the state of the thread. The `value` parameter is the value of the `State` field in the **Threads** report output.|
...
"Free" objects are simply regions of space the garbage collector can use later.
-If 30% or more of the heap contains "Free" objects, the process may suffer from
+If 30%% or more of the heap contains "Free" objects, the process may suffer from
heap fragmentation. This is usually caused by pinning objects for a long time
combined with a high rate of allocation. Here is example output where !DumpHeap
provides a warning about fragmentation:
output. Example of special threads include: GC threads (in
concurrent GC and server GC), Debugger helper threads, Finalizer
threads, AppDomain Unload threads, and Threadpool timer threads.
+-managedexception: optional. Sets the current thread to first thread with
+ an managed exception for the "printexception" command.
Each thread has many attributes, many of which can be ignored. The important
ones are discussed below:
\\
COMMAND: clrstack.
-!CLRStack [-a] [-l] [-p] [-n] [-f]
+!CLRStack [-a] [-l] [-p] [-n] [-f] [-r] [-all]
!CLRStack [-a] [-l] [-p] [-i] [variable name] [frame]
CLRStack attempts to provide a true stack trace for managed code only. It is
the managed frames and the assembly name and function offset for the managed
frames.
+The -r option dumps the registers for each stack frame.
+
+The -all option dumps all the managed threads' stacks.
+
If the debugger has the option SYMOPT_LOAD_LINES specified (either by the
.lines or .symopt commands), SOS will look up the symbols for every managed
frame and if successful will display the corresponding source file name and
Total 337556 24 306968 8800
Free space: Percentage
- Heap0 28 12 12 64 SOH: 0% LOH: 0%
- Heap1 104 12 12 16 SOH: 0% LOH:100%
+ Heap0 28 12 12 64 SOH: 0%% LOH: 0%%
+ Heap1 104 12 12 16 SOH: 0%% LOH:100%%
Total 132 24 24 80
0:002> !heapstat -inclUnrooted
Total 337556 24 306968 8800
Free space: Percentage
- Heap0 28 12 12 64 SOH: 0% LOH: 0%
- Heap1 104 12 12 16 SOH: 0% LOH:100%
+ Heap0 28 12 12 64 SOH: 0%% LOH: 0%%
+ Heap1 104 12 12 16 SOH: 0%% LOH:100%%
Total 132 24 24 80
Unrooted objects: Percentage
- Heap0 152212 0 306196 0 SOH: 94% LOH: 0%
- Heap1 155704 0 0 0 SOH: 97% LOH: 0%
+ Heap0 152212 0 306196 0 SOH: 94%% LOH: 0%%
+ Heap1 155704 0 0 0 SOH: 97%% LOH: 0%%
Total 307916 0 306196 0
The percentage column contains a breakout of free or unrooted bytes to total bytes.
GC can not commit memory it needs. You can look at these scenarios by using performance
counters or debugger commands. For example for the former scenario the "!address
-summary" debugger command will show you the largest free region in the VM. For
-the latter scenario you can look at the "Memory\% Committed Bytes In Use" see
+the latter scenario you can look at the "Memory%% Committed Bytes In Use" see
if you are running low on commit space. One important thing to keep in mind is
when you do this kind of memory analysis it could an aftereffect and doesn't
completely agree with what this command tells you, in which case the command should
\\
COMMAND: setsymbolserver.
-SetSymbolServer [-ms] [-mi] [-disable] [-log] [-cache <cache-path>] [<symbol-server-URL>]
+SetSymbolServer [-ms] [-mi] [-disable] [-log] [-cache <cache-path>] [-directory <search-directory>] [<symbol-server-URL>]
-ms - Use the public Microsoft symbol server.
-mi - Use the internal symweb symbol server.
-disable - Disable symbol download support.
--cache - Specific a symbol cache directory. The default is %TEMP%\SymbolCache if not specified.
+-directory - Directory to search for symbols. Can be more than one.
+-cache - Specific a symbol cache directory. The default is %%TEMP%%\SymbolCache if not specified.
-log - Enable symbol download logging.
<symbol-server-URL> - Symbol server URL.
This commands enables symbol server support for portable PDBs in SOS. If the .sympath is set, this
-symbol server support is automatically enabled.
\ No newline at end of file
+symbol server support is automatically enabled.
+
+To disable downloading or clear the current SOS symbol settings allowing new symbol paths to be set:
+
+ 0:000> !setsymbolserver -disable
output. Example of special threads include: GC threads (in
concurrent GC and server GC), Debugger helper threads, Finalizer
threads, AppDomain Unload threads, and Threadpool timer threads.
+-managedexception: optional. Sets the current thread to first thread with
+ an managed exception for the "printexception" command.
Each thread has many attributes, many of which can be ignored. The important
ones are discussed below:
the managed frames and the assembly name and function offset for the managed
frames.
+The -r option dumps the registers for each stack frame.
+
+The -all option dumps all the managed threads' stacks.
+
If the debugger has the option SYMOPT_LOAD_LINES specified (either by the
.lines or .symopt commands), SOS will look up the symbols for every managed
frame and if successful will display the corresponding source file name and
COMMAND: setsymbolserver.
COMMAND: loadsymbols.
-SetSymbolServer [-ms] [-disable] [-log] [-cache <cache-path>] [-loadsymbols] [<symbol-server-URL>]
+COMMAND: sympath.
+SetSymbolServer [-ms] [-disable] [-log] [-loadsymbols] [-cache <cache-path>] [-directory <search-directory>] [-sympath <windows-symbol-path>] [<symbol-server-URL>]
-ms - Use the public Microsoft symbol server.
-disable - Disable symbol download support.
+-directory - Directory to search for symbols. Can be more than one.
-cache - Specific a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.
+-sympath - Add server, cache and directory paths in the Windows symbol path format.
-log - Enable symbol download logging.
-loadsymbols - Attempts to download the native .NET Core symbols for the runtime
<symbol-server-URL> - Symbol server URL.
This command may take some time without any output while it attempts to download the symbol files.
-To disable download:
+To disable downloading or clear the current SOS symbol settings allowing new symbol paths to be set:
(lldb) setsymbolserver -disable
+To add a directory to search for symbols:
+
+ (lldb) setsymbolserver -directory /home/mikem/symbols
+
+This command can be used so the module/symbol file structure does not have to match the machine
+file structure that the core dump was generated.
+
+The "sympath" option/command alias allows Windows symbol paths to be parsed:
+
+ (lldb) sympath "/home/mikem/localsymbols;srv*/home/mikem/symbolcache*https://msdl.microsoft.com/download/symbols".
+
To clear the default cache run "rm -r $HOME/.dotnet/symbolcache" in a command shell.
If you receive an error like the one below on a core dump, you need to set the .NET Core
projects / platform / core / dotnet / diagnostics.git / commitdiff