From d560dc2d223adc4b369c4745570f54a996f1e828 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 13:11:19 -0400 Subject: [PATCH 01/45] Draft TOC --- docs/toc.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/toc.yml b/docs/toc.yml index 6307f3fb23110..322e9fd7315d0 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -271,6 +271,18 @@ href: core/diagnostics/managed-debuggers.md - name: Logging and tracing href: core/diagnostics/logging-tracing.md + - name: .NET Core CLI global tools + items: + - name: Overview + href: core/diagnostics/cli-tools/overview.md + - name: dotnet-counters + href: core/diagnostics/cli-tools/dotnet-counters.md + - name: dotnet-dump + href: core/diagnostics/cli-tools/dotnet-dump.md + - name: dotnet-trace + href: core/diagnostics/cli-tools/dotnet-trace.md + - name: dotnet-symbol + href: core/diagnostics/cli-tools/dotnet-symbol.md - name: Unit Testing href: core/testing/index.md items: @@ -329,6 +341,8 @@ href: core/tools/global-tools-how-to-create.md - name: Troubleshoot tool usage issues href: core/tools/troubleshoot-usage-issues.md + - name: Diagnostics global tools + href: core/diagnostics/cli-tools/overview.md - name: Elevated access href: core/tools/elevated-access.md - name: Extensibility Model From 96ba51244b781b920b3a796549ddb96236c5eb06 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 13:41:30 -0400 Subject: [PATCH 02/45] Create basic file structure Copy rough documentation from dotnet/diagnostics --- .../diagnostics/cli-tools/dotnet-counters.md | 117 +++++++++++ .../core/diagnostics/cli-tools/dotnet-dump.md | 121 ++++++++++++ .../diagnostics/cli-tools/dotnet-trace.md | 183 ++++++++++++++++++ docs/core/diagnostics/cli-tools/installing.md | 44 +++++ docs/core/diagnostics/cli-tools/overview.md | 0 docs/toc.yml | 4 +- 6 files changed, 467 insertions(+), 2 deletions(-) create mode 100644 docs/core/diagnostics/cli-tools/dotnet-counters.md create mode 100644 docs/core/diagnostics/cli-tools/dotnet-dump.md create mode 100644 docs/core/diagnostics/cli-tools/dotnet-trace.md create mode 100644 docs/core/diagnostics/cli-tools/installing.md create mode 100644 docs/core/diagnostics/cli-tools/overview.md diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md new file mode 100644 index 0000000000000..792f94178d876 --- /dev/null +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -0,0 +1,117 @@ +# dotnet-counters + + +## Intro + +dotnet-counters is a performance monitoring tool for ad-hoc health monitoring or 1st level performance investigation. It can observe performance counter values that are published via `EventCounter` API (https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there is anything suspiscious before diving into more serious performance investigation using PerfView or dotnet-trace. + + +## Install dotnet-counters + +``` +dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 +``` + + +## Using dotnet-counters + +*SYNOPSIS* + + dotnet-counters [--version] + [-h, --help] + [] + +*OPTIONS* + + --version + Display the version of the dotnet-counters utility. + + -h, --help + Show command line help + +*COMMANDS* + + list Display a list of counter names and descriptions + monitor Display periodically refreshing values of selected counters + +*LIST* + + dotnet-counters list [-h|--help] + + Display a list of counter names and descriptions, grouped by provider. + + -h, --help + Show command line help + + Examples: + > dotnet-counters list + + Showing well-known counters only. Specific processes may support additional counters. + System.Runtime + cpu-usage Amount of time the process has utilized the CPU (ms) + working-set Amount of working set used by the process (MB) + gc-heap-size Total heap size reported by the GC (MB) + gen-0-gc-count Number of Gen 0 GCs / sec + gen-1-gc-count Number of Gen 1 GCs / sec + gen-2-gc-count Number of Gen 2 GCs / sec + exception-count Number of Exceptions / sec + +*MONITOR* + + ### Examples: + + 1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: + + > dotnet-counters monitor --process-id 1902 System.Runtime + + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + Working Set (MB) 1982 + GC Heap Size (MB) 811 + Gen 0 GC / second 20 + Gen 1 GC / second 4 + Gen 1 GC / Second 1 + Number of Exceptions / sec 4 + + 2. Monitoring just CPU usage and GC heap size from `System.Runtime` at a refresh interval of 5 seconds: + + > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size,exception-count] + + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + GC Heap Size (MB) 811 + Number of Exceptions / sec 4 + + 3. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.0) + + > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal + + Press p to pause, r to resume, q to quit. + request 100 + + + ### Syntax: + + dotnet-counters monitor [-h||--help] + [-p|--process-id ] + [--refreshInterval ] + counter_list + + Display periodically refreshing values of selected counters + + -h, --help + Show command line help + + -p,--process-id + The ID of the process that will be monitored + + --refresh-interval + The number of seconds to delay between updating the displayed counters + + counter_list + A space separated list of counters. Counters can be specified provider_name[:counter_name]. If the + provider_name is used without a qualifying counter_name then all counters will be shown. To discover + provider and counter names, use the list command. + diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md new file mode 100644 index 0000000000000..5abd8068f2fa6 --- /dev/null +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -0,0 +1,121 @@ +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. + +Currently not supported on macOS. + +## 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 --version 3.0.0-preview8.19412.1 + You can invoke the tool using the following command: dotnet-dump + Tool 'dotnet-dump' (version '3.0.0-preview8.19412.1') 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](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) on Linux. + +On Linux, the runtime version must be 3.0 or greater. + + $ 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. 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 + +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.0-preview8.19412.1') was successfully uninstalled. diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md new file mode 100644 index 0000000000000..f43beacd5151d --- /dev/null +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -0,0 +1,183 @@ +# Trace for performance analysis utility (dotnet-trace) + +The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. It is built around the EventPipe technology of the .NET Core runtime as a cross-platform alternative to ETW on Windows and LTTng on Linux, which only work on a single platform. With EventPipe/dotnet-trace, we are trying to deliver the same experience on Windows, Linux, or macOS. dotnet-trace can be used on any .NET Core applications using versions .NET Core 3.0 Preview 5 or later. + +## Installing dotnet-trace + +The first step is to install the dotnet-trace CLI global tool. + +```cmd +$ dotnet tool install --global dotnet-trace --version 3.0.0-preview8.19412.1 +You can invoke the tool using the following command: dotnet-trace +Tool 'dotnet-trace' (version '3.0.0-preview8.19412.1') was successfully installed. +``` + +## Using dotnet-trace + +In order to collect traces using dotnet-trace, you will need to: + +- First, find out the process identifier (pid) of the .NET Core 3.0 application (using builds Preview 5 or after) to collect traces from. + + - On Windows, there are options such as using the task manager or the `tasklist` command on the cmd window. + - On Linux, the trivial option could be using `pidof` on the terminal window. + +You may also use the command `dotnet-trace list-processes` command to find out what .NET Core processes are running, along with their process IDs. + +- Then, run the following command: + +```cmd +dotnet-trace collect --process-id --providers Microsoft-Windows-DotNETRuntime + +Press to exit... +Connecting to process: /dotnet.exe +Collecting to file: /trace.nettrace + Session Id: + Recording trace 721.025 (KB) +``` + +- Finally, stop collection by pressing the \ key, and *dotnet-trace* will finish logging events to *trace.nettrace* file. + +### Using dotnet-trace to collect counter values over time + +If you are trying to use EventCounter for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real-time, you can do that with `dotnet-trace` as well. + +For example, if you want to enable and collect runtime performance counter values, you can use the following command: +```cmd +dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 +``` + +This will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. + +If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. +```cmd +dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 +``` + + +## Viewing the trace captured from dotnet-trace + +On Windows, `.nettrace` files can be viewed on PerfView (https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. + +If you would rather view the trace on a Linux machine, you can do this by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a speedscope file. You can currently choose between `nettrace` (the default option) and `speedscope`. Speedscope files can be opened at https://www.speedscope.app. + +Note: The .NET Core runtime generates traces in the `nettrace` format, and are converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. + +## Known Caveats + +- Perfview/VS aren't showing any callstacks + +There was a regression in Preview6 (https://github.com/dotnet/coreclr/issues/25046) that dropped these callstacks. It has since been fixed in daily builds. If you want to demo callstacks you can use either Preview5, Preview7 which will be out soon, or daily builds. + + +- "dotnet-trace used to work but now it's giving me `Unable to create a session`" + +Between .NET Core Preview 5 and Preview 6, there were breaking changes in the runtime. To use the Preview 6 version of dotnet-trace, you need to be using it on an application with Preview 6 of the runtime, and the same holds for the other way around - To trace an application using .NET Core Preview 6 or later, you need to use the latest version of dotnet-trace. + + + +## Commonly used keywords for the *Microsoft-Windows-DotNETRuntime* provider + + Runtime keyword name | Keyword Value | Description + ------------------------------ | ----------------: | ------------ +None | 0 | +All | FFFFFFFFFFFFFFBF | All does not include start-enumeration. It just is not that useful. +GC | 1 | Logging when garbage collections and finalization happen. +GCHandle | 2 | Events when GC handles are set or destroyed. +Binder | 4 | +Loader | 8 | Logging when modules actually get loaded and unloaded. +Jit | 10 | Logging when Just in time (JIT) compilation occurs. +NGen | 20 | Logging when precompiled native (NGEN) images are loaded. +StartEnumeration | 40 | Indicates that on attach or module load, a rundown of all existing methods should be done. +StopEnumeration | 80 | Indicates that on detach or process shutdown, a rundown of all existing methods should be done. +Security | 400 | Events associated with validating security restrictions. +AppDomainResourceManagement | 800 | Events for logging resource consumption on an app-domain level granularity. +JitTracing | 1000 | Logging of the internal workings of the Just In Time compiler. This is fairly verbose. It details decisions about interesting optimization (like inlining and tail call). +Interop | 2000 | Log information about code thunks that transition between managed and unmanaged code. +Contention | 4000 | Log when lock contention occurs. (Monitor.Enters actually blocks). +Exception | 8000 | Log exception processing. +Threading | 10000 | Log events associated with the threadpool, and other threading events. +JittedMethodILToNativeMap | 20000 | Dump the native to IL mapping of any method that is JIT compiled. (V4.5 runtimes and above). +OverrideAndSuppressNGenEvents | 40000 | If enabled will suppress the rundown of NGEN events on V4.0 runtime (has no effect on Pre-V4.0 runtimes). +SupressNGen | 40000 | This suppresses NGEN events on V4.0 (where you have NGEN PDBs), but not on V2.0 (which does not know about this bit and also does not have NGEN PDBS). +JITSymbols | 60098 | What is needed to get symbols for JIT compiled code.
This is equivalent to `Jit+JittedMethodILToNativeMap+Loader+OverrideAndSuppressNGenEvents+StopEnumeration` +Type | 80000 | Enables the 'BulkType' event. +GCHeapDump | 100000 | Enables the events associated with dumping the GC heap. +GCSampledObjectAllocationHigh | 200000 | Enables allocation sampling with the 'fast'. Sample to limit to 100 allocations per second per type. This is good for most detailed performance investigations.
Note that this DOES update the allocation path to be slower and only works if the process start with this on. +GCHeapSurvivalAndMovement | 400000 | Enables events associate with object movement or survival with each GC. +GCHeapCollect | 800000 | Triggers a GC. Can pass a 64 bit value that will be logged with the GC Start event so you know which GC you actually triggered. +GCHeapAndTypeNames | 1000000 | Indicates that you want type names looked up and put into the events (not just meta-data tokens). +GCHeapSnapshot | 1980001 | This provides the flags commonly needed to take a heap .NET Heap snapshot with EventPipe.
This is equivalent to `GC+Type+GCHeapDump+GCHeapCollect+GCHeapAndTypeNames` +GCSampledObjectAllocationLow | 2000000 | Enables allocation sampling with the 'slow' rate, Sample to limit to 5 allocations per second per type. This is reasonable for monitoring. Note that this DOES update the allocation path to be slower and only works if the process start with this on. +GCAllObjectAllocation | 2200000 | Turns on capturing the stack and type of object allocation made by the .NET Runtime. This is only supported after V4.5.3 (Late 2014) This can be very verbose and you should seriously using GCSampledObjectAllocationHigh instead (and GCSampledObjectAllocationLow for production scenarios). +Stack | 40000000 | Also log the stack trace of events for which this is valuable. +ThreadTransfer | 80000000 | This allows tracing work item transfer events (thread pool enqueue/dequeue/ioenqueue/iodequeue/a.o.). +Debugger | 100000000 | .NET Debugger events +Monitoring | 200000000 | Events intended for monitoring on an ongoing basis. +Codesymbols | 400000000 | Events that will dump PDBs of dynamically generated assemblies to the EventPipe stream. +Default | 4C14FCCBD | Recommend default flags (good compromise on verbosity). + +[source](https://github.com/Microsoft/perfview/blob/master/src/TraceEvent/Parsers/ClrTraceEventParser.cs#L41) + +## More information on .NET Providers + + Provider Name | Information + -------------------------------------: | ------------ +Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) +Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) +Microsoft-DotNETCore-SampleProfiler | Enable the sample profiler + +## *dotnet-trace* help + +```cmd +dotnet.exe run -c Release --no-restore --no-build -- collect --help + +collect: + Collects a diagnostic trace from a currently running process + +Usage: + dotnet-trace collect [options] + +Options: + -h, --help + Shows this help message and exit. + + -p, --process-id + The process to collect the trace from + + -o, --output + The output path for the collected trace data. If not specified it defaults to 'trace.nettrace' + + --profile + A named pre-defined set of provider configurations that allows common tracing scenarios to be specified + succinctly. The options are: + runtime-basic Useful for tracking CPU usage and general runtime information. This the default option + if no profile is specified. + gc Tracks allocation and collection performance + gc-collect Tracks GC collection only at very low overhead + none Tracks nothing. Only providers specified by the --providers option will be available. + + --providers + A list of comma separated EventPipe providers to be enabled. + This option adds to the configuration already provided via the --profile argument. If the same provider is configured in both places, this option takes precedence. + A provider consists of the name and optionally the keywords, verbosity level, and custom key/value pairs. + + The string is written 'Provider[,Provider]' + Provider format: KnownProviderName[:Keywords[:Level][:KeyValueArgs]] + KnownProviderName - The provider's name + Keywords - 8 character hex number bit mask + Level - A number in the range [0, 5] + 0 - Always + 1 - Critical + 2 - Error + 3 - Warning + 4 - Informational + 5 - Verbose + KeyValueArgs - A semicolon separated list of key=value + KeyValueArgs format: '[key1=value1][;key2=value2]' + note: values that contain ';' or '=' characters should be surrounded by double quotes ("), e.g., 'key="value;with=symbols";key2=value2' + + --buffersize + Sets the size of the in-memory circular buffer in megabytes. Default 256 MB. + + -f, --format + The format of the output trace file. This defaults to "nettrace" on Windows and "speedscope" on other OSes. diff --git a/docs/core/diagnostics/cli-tools/installing.md b/docs/core/diagnostics/cli-tools/installing.md new file mode 100644 index 0000000000000..8f9562c85ff44 --- /dev/null +++ b/docs/core/diagnostics/cli-tools/installing.md @@ -0,0 +1,44 @@ +# Installing the diagnostics tools + +Depending on the diagnostics scenario you will use one or more of the tools below to get to root cause. By default, these tools are installed to ~/.dotnet/tools. + +### dotnet-counters +In the .NET full/Windows world, we have a myriad of performance counters that can be used to triage and diagnose production issues. For .Net core we have a similar and cross platform story centered around a tool called dotnet-counters. To install the tool, run the following command: + +> ```bash +> dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 +> ``` + + +### dotnet-trace +.NET core includes what is called the 'EventPipe' through which diagnostics data is exposed. The dotnet-trace tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. To install the tool, run the following command: + +> ```bash +> dotnet tool install --global dotnet-trace --version 3.0.0-preview8.19412.1 +> ``` + + +### 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: + +> ```bash +> dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 +> ``` + + +### 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: + +> ```bash +> dotnet tool install -g dotnet-symbol +> ``` + +### perfcollect +Thet .NET core runtime is instrumented for both perf and LTTng. To facilitate easier collection of both tracing technologies there is a tool called perfcollect. Perfcollect will output the joint trace data into a nettrace file that can be analyzed using PerfView on Windows. To install the tool run the following commands: + +> ``` +> curl -OL http://aka.ms/perfcollect +> chmod +x perfcollect +> sudo ./perfcollect install +> ``` + diff --git a/docs/core/diagnostics/cli-tools/overview.md b/docs/core/diagnostics/cli-tools/overview.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/docs/toc.yml b/docs/toc.yml index 322e9fd7315d0..a8ea090ca1ba8 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -275,14 +275,14 @@ items: - name: Overview href: core/diagnostics/cli-tools/overview.md + - name: Install + href: core/diagnostics/cli-tools/install.md - name: dotnet-counters href: core/diagnostics/cli-tools/dotnet-counters.md - name: dotnet-dump href: core/diagnostics/cli-tools/dotnet-dump.md - name: dotnet-trace href: core/diagnostics/cli-tools/dotnet-trace.md - - name: dotnet-symbol - href: core/diagnostics/cli-tools/dotnet-symbol.md - name: Unit Testing href: core/testing/index.md items: From 982343522ff209e72f2e619aa633918ef5926f1a Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 15:36:20 -0400 Subject: [PATCH 03/45] Add headers --- docs/core/diagnostics/cli-tools/dotnet-counters.md | 10 +++++++--- docs/core/diagnostics/cli-tools/dotnet-dump.md | 7 +++++++ docs/core/diagnostics/cli-tools/dotnet-trace.md | 7 +++++++ docs/core/diagnostics/cli-tools/overview.md | 10 ++++++++++ 4 files changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index 792f94178d876..be09a8f95cc56 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -1,18 +1,22 @@ +--- +title: dotnet-counters - .NET Core +description: Installing and using the dotnet-counter command line tool. +author: sdmaclea +ms.author: stmaclea +ms.date: 08/05/2019 +--- # dotnet-counters - ## Intro dotnet-counters is a performance monitoring tool for ad-hoc health monitoring or 1st level performance investigation. It can observe performance counter values that are published via `EventCounter` API (https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there is anything suspiscious before diving into more serious performance investigation using PerfView or dotnet-trace. - ## Install dotnet-counters ``` dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 ``` - ## Using dotnet-counters *SYNOPSIS* diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md index 5abd8068f2fa6..a5cef9d129129 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-dump.md +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -1,3 +1,10 @@ +--- +title: dotnet-dump - .NET Core +description: Installing and using the dotnet-dump command line tool. +author: sdmaclea +ms.author: stmaclea +ms.date: 08/05/2019 +--- Dump collection and analysis utility (dotnet-dump) ================================================== diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index f43beacd5151d..227082474b6c1 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -1,3 +1,10 @@ +--- +title: dotnet-trace - .NET Core +description: Installing and using the dotnet-trace command line tool. +author: sdmaclea +ms.author: stmaclea +ms.date: 08/05/2019 +--- # Trace for performance analysis utility (dotnet-trace) The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. It is built around the EventPipe technology of the .NET Core runtime as a cross-platform alternative to ETW on Windows and LTTng on Linux, which only work on a single platform. With EventPipe/dotnet-trace, we are trying to deliver the same experience on Windows, Linux, or macOS. dotnet-trace can be used on any .NET Core applications using versions .NET Core 3.0 Preview 5 or later. diff --git a/docs/core/diagnostics/cli-tools/overview.md b/docs/core/diagnostics/cli-tools/overview.md index e69de29bb2d1d..02e51b0d7b988 100644 --- a/docs/core/diagnostics/cli-tools/overview.md +++ b/docs/core/diagnostics/cli-tools/overview.md @@ -0,0 +1,10 @@ +--- +title: Diagnostic dotnet tools overview - .NET Core +description: An overview of the dotnet global command line tools available to diagnose .NET Core applications. +author: sdmaclea +ms.author: stmaclea +ms.date: 08/21/2019 +ms.topic: overview +#Customer intent: As a .NET Core developer I want to diagnose problems so that I can be productive. +--- +# .NET Core dotnet diagnostic global tools From 2248df335a4d0c3f47b6342454d77fc6e7ed8f4a Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 15:45:07 -0400 Subject: [PATCH 04/45] Remove /en-us/ from links --- docs/core/diagnostics/cli-tools/dotnet-counters.md | 2 +- docs/core/diagnostics/cli-tools/dotnet-trace.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index be09a8f95cc56..ab6d1f0a28317 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -9,7 +9,7 @@ ms.date: 08/05/2019 ## Intro -dotnet-counters is a performance monitoring tool for ad-hoc health monitoring or 1st level performance investigation. It can observe performance counter values that are published via `EventCounter` API (https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there is anything suspiscious before diving into more serious performance investigation using PerfView or dotnet-trace. +dotnet-counters is a performance monitoring tool for ad-hoc health monitoring or 1st level performance investigation. It can observe performance counter values that are published via `EventCounter` API (https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there is anything suspiscious before diving into more serious performance investigation using PerfView or dotnet-trace. ## Install dotnet-counters diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index 227082474b6c1..6135d52b71224 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -129,8 +129,8 @@ Default | 4C14FCCBD | Recommend default flags (g Provider Name | Information -------------------------------------: | ------------ -Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) -Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/en-us/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) +Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) +Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) Microsoft-DotNETCore-SampleProfiler | Enable the sample profiler ## *dotnet-trace* help From 8e33d7303d342e22a622bc397e0b1b40e4844812 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 15:52:31 -0400 Subject: [PATCH 05/45] Edit dotnet-counters Correct spelling, hyphenation and grammar. Update install instructions to use latest release version. --- docs/core/diagnostics/cli-tools/dotnet-counters.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index ab6d1f0a28317..1f7a9a5777055 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -1,6 +1,6 @@ --- title: dotnet-counters - .NET Core -description: Installing and using the dotnet-counter command line tool. +description: Installing and using the dotnet-counter command-line tool. author: sdmaclea ms.author: stmaclea ms.date: 08/05/2019 @@ -9,14 +9,18 @@ ms.date: 08/05/2019 ## Intro -dotnet-counters is a performance monitoring tool for ad-hoc health monitoring or 1st level performance investigation. It can observe performance counter values that are published via `EventCounter` API (https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there is anything suspiscious before diving into more serious performance investigation using PerfView or dotnet-trace. +`dotnet-counters` is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there's anything suspicious before diving into more serious performance investigation using `PerfView` or `dotnet-trace`. ## Install dotnet-counters +To install the latest release version of the `dotnet-counters` [NuGet package](https://www.nuget.org/packages/dotnet-counters): + ``` -dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 +dotnet tool install --global dotnet-counters ``` +For details and other options, see [Installing the diagnostics tools](installing.md). + ## Using dotnet-counters *SYNOPSIS* From 30e9914ae8bb0c5e82b21f7fd3b77dd1e6d83aa9 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 18:32:47 -0400 Subject: [PATCH 06/45] Clean up dotnet-dump --- .../core/diagnostics/cli-tools/dotnet-dump.md | 219 +++++++++--------- 1 file changed, 113 insertions(+), 106 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md index a5cef9d129129..38f2a4d0c1d31 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-dump.md +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -1,128 +1,135 @@ --- title: dotnet-dump - .NET Core -description: Installing and using the dotnet-dump command line tool. +description: Installing and using the dotnet-dump command-line tool. author: sdmaclea ms.author: stmaclea ms.date: 08/05/2019 --- -Dump collection and analysis utility (dotnet-dump) -================================================== +# 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. +The `dotnet-dump` CLI global tool is a way to collect and analyze Windows and Linux dumps all without any native debugger involved like `lldb` on Linux. This tool 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 native stack frames aren't supported. -Currently not supported on macOS. +> [!NOTE] +> `dotnet-dump` is not supported on macOS. -## Installing dotnet-dump +## 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). +To install the latest release version of the `dotnet-dump` [NuGet package](https://www.nuget.org/packages/dotnet-dump): - $ dotnet tool install -g dotnet-dump --version 3.0.0-preview8.19412.1 - You can invoke the tool using the following command: dotnet-dump - Tool 'dotnet-dump' (version '3.0.0-preview8.19412.1') was successfully installed. +```bash +$ dotnet tool install -g dotnet-dump +You can invoke the tool using the following command: dotnet-dump +Tool 'dotnet-dump' (version '3.0.0') 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. +For details and other options, see [Installing the diagnostics tools](installing.md). - export PATH=$PATH:$HOME/.dotnet/tools +## Using `dotnet-dump` -## 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. +The next step is to collect a dump. This step 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, the runtime version must be 3.0 or greater. - - $ 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. 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] + +```bash +$ 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. + +```bash +$ 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 action brings up an interactive session that accepts commands like: + +```bash +> 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 an unhandled exception that terminated your app: + +```bash +> 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 - -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.0-preview8.19412.1') was successfully uninstalled. + ```bash +> 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 +``` + +## Docker special instructions + +If you're running under docker, dump collection requires `SYS_PTRACE` docker capabilities (`--cap-add=SYS_PTRACE or --privileged`). + +On Microsoft .NET Core SDK Linux docker images, some `dotnet-dump` commands 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. From a3562fca7d41f670091c4e083120be19a47f10b5 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 21 Aug 2019 18:33:13 -0400 Subject: [PATCH 07/45] Clean up dotnet-trace --- .../diagnostics/cli-tools/dotnet-trace.md | 148 ++++++++---------- 1 file changed, 69 insertions(+), 79 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index 6135d52b71224..962fae3c068f1 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -1,29 +1,32 @@ --- title: dotnet-trace - .NET Core -description: Installing and using the dotnet-trace command line tool. +description: Installing and using the dotnet-trace command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 08/05/2019 +ms.date: 08/21/2019 --- -# Trace for performance analysis utility (dotnet-trace) +# Trace for performance analysis utility (`dotnet-trace`) -The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. It is built around the EventPipe technology of the .NET Core runtime as a cross-platform alternative to ETW on Windows and LTTng on Linux, which only work on a single platform. With EventPipe/dotnet-trace, we are trying to deliver the same experience on Windows, Linux, or macOS. dotnet-trace can be used on any .NET Core applications using versions .NET Core 3.0 Preview 5 or later. +The `dotnet-trace` tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. It's built around the `EventPipe` technology of the .NET Core runtime as a cross-platform alternative to ETW on Windows and LTTng on Linux, which only work on a single platform. With `EventPipe`/`dotnet-trace`, we're trying to deliver the same experience on Windows, Linux, or macOS. -## Installing dotnet-trace +> [!NOTE] +> `dotnet-trace` can be used on any .NET Core applications using versions .NET Core 3.0 Preview 7 or later. -The first step is to install the dotnet-trace CLI global tool. +## Installing `dotnet-trace` -```cmd -$ dotnet tool install --global dotnet-trace --version 3.0.0-preview8.19412.1 -You can invoke the tool using the following command: dotnet-trace -Tool 'dotnet-trace' (version '3.0.0-preview8.19412.1') was successfully installed. +To install the latest release version of the `dotnet-trace` [NuGet package](https://www.nuget.org/packages/dotnet-trace): + +``` +dotnet tool install --global dotnet-trace ``` -## Using dotnet-trace +For details and other options, see [Installing the diagnostics tools](installing.md). + +## Using `dotnet-trace` -In order to collect traces using dotnet-trace, you will need to: +To collect traces, using `dotnet-trace`, you'll need to: -- First, find out the process identifier (pid) of the .NET Core 3.0 application (using builds Preview 5 or after) to collect traces from. +- First, find out the process identifier (pid) of the .NET Core application to collect traces from. - On Windows, there are options such as using the task manager or the `tasklist` command on the cmd window. - On Linux, the trivial option could be using `pidof` on the terminal window. @@ -32,7 +35,7 @@ You may also use the command `dotnet-trace list-processes` command to find out w - Then, run the following command: -```cmd +```bash dotnet-trace collect --process-id --providers Microsoft-Windows-DotNETRuntime Press to exit... @@ -42,100 +45,86 @@ Collecting to file: /trace.nettrace Recording trace 721.025 (KB) ``` -- Finally, stop collection by pressing the \ key, and *dotnet-trace* will finish logging events to *trace.nettrace* file. +- Finally, stop collection by pressing the \ key, and `dotnet-trace` will finish logging events to *trace.nettrace* file. -### Using dotnet-trace to collect counter values over time +### Using `dotnet-trace` to collect counter values over time -If you are trying to use EventCounter for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real-time, you can do that with `dotnet-trace` as well. +If you're trying to use `EventCounter` for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real time, you can do that with `dotnet-trace` as well. -For example, if you want to enable and collect runtime performance counter values, you can use the following command: -```cmd +For example, if you want to collect runtime performance counter values, you can use the following command: +```bash dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 ``` -This will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. +This command will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. -```cmd +```bash dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 ``` - - -## Viewing the trace captured from dotnet-trace - -On Windows, `.nettrace` files can be viewed on PerfView (https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. - -If you would rather view the trace on a Linux machine, you can do this by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a speedscope file. You can currently choose between `nettrace` (the default option) and `speedscope`. Speedscope files can be opened at https://www.speedscope.app. -Note: The .NET Core runtime generates traces in the `nettrace` format, and are converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. +## Viewing the trace captured from `dotnet-trace` -## Known Caveats - -- Perfview/VS aren't showing any callstacks - -There was a regression in Preview6 (https://github.com/dotnet/coreclr/issues/25046) that dropped these callstacks. It has since been fixed in daily builds. If you want to demo callstacks you can use either Preview5, Preview7 which will be out soon, or daily builds. - - -- "dotnet-trace used to work but now it's giving me `Unable to create a session`" - -Between .NET Core Preview 5 and Preview 6, there were breaking changes in the runtime. To use the Preview 6 version of dotnet-trace, you need to be using it on an application with Preview 6 of the runtime, and the same holds for the other way around - To trace an application using .NET Core Preview 6 or later, you need to use the latest version of dotnet-trace. +On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. +You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at https://www.speedscope.app. +Note: The .NET Core runtime generates traces in the `nettrace` format, and they're converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. ## Commonly used keywords for the *Microsoft-Windows-DotNETRuntime* provider Runtime keyword name | Keyword Value | Description ------------------------------ | ----------------: | ------------ -None | 0 | -All | FFFFFFFFFFFFFFBF | All does not include start-enumeration. It just is not that useful. -GC | 1 | Logging when garbage collections and finalization happen. -GCHandle | 2 | Events when GC handles are set or destroyed. -Binder | 4 | -Loader | 8 | Logging when modules actually get loaded and unloaded. -Jit | 10 | Logging when Just in time (JIT) compilation occurs. -NGen | 20 | Logging when precompiled native (NGEN) images are loaded. -StartEnumeration | 40 | Indicates that on attach or module load, a rundown of all existing methods should be done. -StopEnumeration | 80 | Indicates that on detach or process shutdown, a rundown of all existing methods should be done. -Security | 400 | Events associated with validating security restrictions. -AppDomainResourceManagement | 800 | Events for logging resource consumption on an app-domain level granularity. -JitTracing | 1000 | Logging of the internal workings of the Just In Time compiler. This is fairly verbose. It details decisions about interesting optimization (like inlining and tail call). -Interop | 2000 | Log information about code thunks that transition between managed and unmanaged code. -Contention | 4000 | Log when lock contention occurs. (Monitor.Enters actually blocks). -Exception | 8000 | Log exception processing. -Threading | 10000 | Log events associated with the threadpool, and other threading events. -JittedMethodILToNativeMap | 20000 | Dump the native to IL mapping of any method that is JIT compiled. (V4.5 runtimes and above). -OverrideAndSuppressNGenEvents | 40000 | If enabled will suppress the rundown of NGEN events on V4.0 runtime (has no effect on Pre-V4.0 runtimes). -SupressNGen | 40000 | This suppresses NGEN events on V4.0 (where you have NGEN PDBs), but not on V2.0 (which does not know about this bit and also does not have NGEN PDBS). -JITSymbols | 60098 | What is needed to get symbols for JIT compiled code.
This is equivalent to `Jit+JittedMethodILToNativeMap+Loader+OverrideAndSuppressNGenEvents+StopEnumeration` -Type | 80000 | Enables the 'BulkType' event. -GCHeapDump | 100000 | Enables the events associated with dumping the GC heap. -GCSampledObjectAllocationHigh | 200000 | Enables allocation sampling with the 'fast'. Sample to limit to 100 allocations per second per type. This is good for most detailed performance investigations.
Note that this DOES update the allocation path to be slower and only works if the process start with this on. -GCHeapSurvivalAndMovement | 400000 | Enables events associate with object movement or survival with each GC. -GCHeapCollect | 800000 | Triggers a GC. Can pass a 64 bit value that will be logged with the GC Start event so you know which GC you actually triggered. -GCHeapAndTypeNames | 1000000 | Indicates that you want type names looked up and put into the events (not just meta-data tokens). -GCHeapSnapshot | 1980001 | This provides the flags commonly needed to take a heap .NET Heap snapshot with EventPipe.
This is equivalent to `GC+Type+GCHeapDump+GCHeapCollect+GCHeapAndTypeNames` -GCSampledObjectAllocationLow | 2000000 | Enables allocation sampling with the 'slow' rate, Sample to limit to 5 allocations per second per type. This is reasonable for monitoring. Note that this DOES update the allocation path to be slower and only works if the process start with this on. -GCAllObjectAllocation | 2200000 | Turns on capturing the stack and type of object allocation made by the .NET Runtime. This is only supported after V4.5.3 (Late 2014) This can be very verbose and you should seriously using GCSampledObjectAllocationHigh instead (and GCSampledObjectAllocationLow for production scenarios). -Stack | 40000000 | Also log the stack trace of events for which this is valuable. -ThreadTransfer | 80000000 | This allows tracing work item transfer events (thread pool enqueue/dequeue/ioenqueue/iodequeue/a.o.). -Debugger | 100000000 | .NET Debugger events -Monitoring | 200000000 | Events intended for monitoring on an ongoing basis. -Codesymbols | 400000000 | Events that will dump PDBs of dynamically generated assemblies to the EventPipe stream. -Default | 4C14FCCBD | Recommend default flags (good compromise on verbosity). +`None` | 0 | +`All` | FFFFFFFFFFFFFFBF | All doesn't include `start-enumeration`. It just isn't that useful. +`GC` | 1 | Logging when garbage collections and finalization happen. +`GCHandle` | 2 | Events when GC handles are set or destroyed. +`Binder` | 4 | +`Loader` | 8 | Logging when modules actually get loaded and unloaded. +`Jit` | 10 | Logging when Just in time (JIT) compilation occurs. +`NGen` | 20 | Logging when precompiled native (NGEN) images are loaded. +`StartEnumeration` | 40 | Indicates that on attach or module load, a rundown of all existing methods should be done. +`StopEnumeration` | 80 | Indicates that on detach or process shutdown, a rundown of all existing methods should be done. +`Security` | 400 | Events associated with validating security restrictions. +`AppDomainResourceManagement` | 800 | Events for logging resource consumption on an app-domain level granularity. +`JitTracing` | 1000 | Logging of the internal workings of the Just In Time compiler. This log is fairly verbose. It details decisions about interesting optimization (like inlining and tail call). +`Interop` | 2000 | Log information about code thunks that transition between managed and unmanaged code. +`Contention` | 4000 | Log when lock contention occurs. ( actually blocks). +`Exception` | 8000 | Log exception processing. +`Threading` | 10000 | Log events associated with the thread pool, and other threading events. +`JittedMethodILToNativeMap` | 20000 | Dump the native to IL mapping of any method that is JIT compiled. +`OverrideAndSuppressNGenEvents` | 40000 | If enabled, will suppress the rundown of NGEN events. +`SupressNGen` | 40000 | This flag suppresses NGEN events. +`JITSymbols` | 60098 | What is needed to get symbols for JIT compiled code.
This keyword is equivalent to `Jit`+`JittedMethodILToNativeMap`+`Loader`+`OverrideAndSuppressNGenEvents`+`StopEnumeration` +`Type` | 80000 | Enables the 'BulkType' event. +`GCHeapDump` | 100000 | Enables the events associated with dumping the GC heap. +`GCSampledObjectAllocationHigh` | 200000 | Enables allocation sampling with the 'fast'. Sample to limit to 100 allocations per second per type. This keyword is good for most detailed performance investigations.
Note this DOES update the allocation path to be slower and only works if the process is started with this option. +`GCHeapSurvivalAndMovement` | 400000 | Enables events associate with object movement or survival with each GC. +`GCHeapCollect` | 800000 | Triggers a GC. Can pass a 64-bit value that will be logged with the GC Start event. This value is so you know which GC you actually triggered. +`GCHeapAndTypeNames` | 1000000 | Indicates that you want type names looked up and put into the events (not just meta-data tokens). +`GCHeapSnapshot` | 1980001 | This keyword provides the flags commonly needed to take a heap .NET Heap snapshot with EventPipe.
This keyword is equivalent to `GC`+`Type`+`GCHeapDump`+`GCHeapCollect`+`GCHeapAndTypeNames` +`GCSampledObjectAllocationLow` | 2000000 | Enables allocation sampling with the 'slow' rate, Sample to limit to 5 allocations per second per type. This keyword is reasonable for monitoring. Note this DOES update the allocation path to be slower and only works if the process is started with this option. +`GCAllObjectAllocation` | 2200000 | Turns on capturing the stack and type of object allocation made by the .NET Runtime. This keyword can be excessively verbose. Consider using `GCSampledObjectAllocationHigh` instead (and `GCSampledObjectAllocationLow` for production scenarios). +`Stack` | 40000000 | Also log the stack trace of events. +`ThreadTransfer` | 80000000 | This keyword allows tracing work item transfer events (thread pool enqueue/dequeue/ioenqueue/iodequeue/a.o.). +`Debugger` | 100000000 | .NET Debugger events +`Monitoring` | 200000000 | Events intended for monitoring on an ongoing basis. +`Codesymbols` | 400000000 | Events that will dump PDBs of dynamically generated assemblies to the EventPipe stream. +`Default` | 4C14FCCBD | Recommend default flags (good compromise on verbosity). [source](https://github.com/Microsoft/perfview/blob/master/src/TraceEvent/Parsers/ClrTraceEventParser.cs#L41) ## More information on .NET Providers Provider Name | Information - -------------------------------------: | ------------ + ------------------------------------- | ------------ Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) Microsoft-DotNETCore-SampleProfiler | Enable the sample profiler -## *dotnet-trace* help +## `dotnet-trace` help -```cmd +```bash dotnet.exe run -c Release --no-restore --no-build -- collect --help collect: @@ -180,7 +169,7 @@ Options: 4 - Informational 5 - Verbose KeyValueArgs - A semicolon separated list of key=value - KeyValueArgs format: '[key1=value1][;key2=value2]' + KeyValueArgs format: '[key1=value1][;key2=value2]' note: values that contain ';' or '=' characters should be surrounded by double quotes ("), e.g., 'key="value;with=symbols";key2=value2' --buffersize @@ -188,3 +177,4 @@ Options: -f, --format The format of the output trace file. This defaults to "nettrace" on Windows and "speedscope" on other OSes. +``` From 5bbd961da5917d4461a33b36384233ee14eb79f3 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Thu, 22 Aug 2019 15:55:31 -0400 Subject: [PATCH 08/45] Fix dates --- docs/core/diagnostics/cli-tools/dotnet-counters.md | 2 +- docs/core/diagnostics/cli-tools/dotnet-dump.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index 1f7a9a5777055..304e434a346bb 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -3,7 +3,7 @@ title: dotnet-counters - .NET Core description: Installing and using the dotnet-counter command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 08/05/2019 +ms.date: 08/21/2019 --- # dotnet-counters diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md index 38f2a4d0c1d31..b36528301fb58 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-dump.md +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -3,7 +3,7 @@ title: dotnet-dump - .NET Core description: Installing and using the dotnet-dump command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 08/05/2019 +ms.date: 08/21/2019 --- # Dump collection and analysis utility (`dotnet-dump`) From 05fc5b9033e2b9095e2bb2b6f0b99e9d6782232b Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Thu, 22 Aug 2019 15:58:53 -0400 Subject: [PATCH 09/45] Fix markuplint issues --- docs/core/diagnostics/cli-tools/dotnet-trace.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index 962fae3c068f1..9c309b7e9c04f 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -52,6 +52,7 @@ Collecting to file: /trace.nettrace If you're trying to use `EventCounter` for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real time, you can do that with `dotnet-trace` as well. For example, if you want to collect runtime performance counter values, you can use the following command: + ```bash dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 ``` @@ -59,6 +60,7 @@ dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCoun This command will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. + ```bash dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 ``` From 0679ca38bdb5e51a1fc12168ff9bf4e4c922ba28 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Thu, 22 Aug 2019 16:02:35 -0400 Subject: [PATCH 10/45] Fix markuplint issues --- .../diagnostics/cli-tools/dotnet-counters.md | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index 304e434a346bb..e9c3af9172fc0 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -25,25 +25,31 @@ For details and other options, see [Installing the diagnostics tools](installing *SYNOPSIS* - dotnet-counters [--version] - [-h, --help] - [] +``` +dotnet-counters [--version] + [-h, --help] + [] +``` *OPTIONS* +``` --version Display the version of the dotnet-counters utility. - -h, --help Show command line help +``` *COMMANDS* +``` list Display a list of counter names and descriptions monitor Display periodically refreshing values of selected counters +``` *LIST* +``` dotnet-counters list [-h|--help] Display a list of counter names and descriptions, grouped by provider. @@ -63,9 +69,11 @@ For details and other options, see [Installing the diagnostics tools](installing gen-1-gc-count Number of Gen 1 GCs / sec gen-2-gc-count Number of Gen 2 GCs / sec exception-count Number of Exceptions / sec +``` *MONITOR* +``` ### Examples: 1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: @@ -82,7 +90,7 @@ For details and other options, see [Installing the diagnostics tools](installing Gen 1 GC / Second 1 Number of Exceptions / sec 4 - 2. Monitoring just CPU usage and GC heap size from `System.Runtime` at a refresh interval of 5 seconds: + 1. Monitoring just CPU usage and GC heap size from `System.Runtime` at a refresh interval of 5 seconds: > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size,exception-count] @@ -92,34 +100,35 @@ For details and other options, see [Installing the diagnostics tools](installing GC Heap Size (MB) 811 Number of Exceptions / sec 4 - 3. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.0) + 1. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.0) > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal Press p to pause, r to resume, q to quit. request 100 +``` +### Syntax: - ### Syntax: - +``` dotnet-counters monitor [-h||--help] [-p|--process-id ] [--refreshInterval ] counter_list - + Display periodically refreshing values of selected counters - + -h, --help Show command line help - + -p,--process-id The ID of the process that will be monitored --refresh-interval The number of seconds to delay between updating the displayed counters - + counter_list A space separated list of counters. Counters can be specified provider_name[:counter_name]. If the provider_name is used without a qualifying counter_name then all counters will be shown. To discover provider and counter names, use the list command. - +``` From 19a95425f4ffcf8a7b481a015afb072adb7c1c4c Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Thu, 22 Aug 2019 21:03:20 -0400 Subject: [PATCH 11/45] Update install instructions --- docs/core/diagnostics/cli-tools/installing.md | 74 +++++++++++-------- 1 file changed, 45 insertions(+), 29 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/installing.md b/docs/core/diagnostics/cli-tools/installing.md index 8f9562c85ff44..40a96e0b56090 100644 --- a/docs/core/diagnostics/cli-tools/installing.md +++ b/docs/core/diagnostics/cli-tools/installing.md @@ -1,44 +1,60 @@ -# Installing the diagnostics tools +--- +title: Installing dotnet diagnostic tools - .NET Core +description: Installing dotnet diagnostic command-line tools. +author: sdmaclea +ms.author: stmaclea +ms.date: 08/21/2019 +--- +# Installing the `dotnet` diagnostic command-line tools -Depending on the diagnostics scenario you will use one or more of the tools below to get to root cause. By default, these tools are installed to ~/.dotnet/tools. +Depending on the diagnostics scenario, you can use one or more tools to get to root cause. -### dotnet-counters -In the .NET full/Windows world, we have a myriad of performance counters that can be used to triage and diagnose production issues. For .Net core we have a similar and cross platform story centered around a tool called dotnet-counters. To install the tool, run the following command: +These tools are implemented as [.NET Core Global Tools](../../tools/global-tools.md). They're installed, upgraded, and uninstalled using the `dotnet tool` commands: +- [dotnet tool install](../../tools/dotnet-tool-install.md). +- [dotnet tool update](../../tools/dotnet-tool-update.md). +- [dotnet tool uninstall](../../tools/dotnet-tool-uninstall.md). -> ```bash -> dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 -> ``` +## Using prerelease versions +As tools are developed, we initially release them with a pre-release version. -### dotnet-trace -.NET core includes what is called the 'EventPipe' through which diagnostics data is exposed. The dotnet-trace tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. To install the tool, run the following command: +### Finding available pre-release versions -> ```bash -> dotnet tool install --global dotnet-trace --version 3.0.0-preview8.19412.1 -> ``` +The pre-release packages are published on [NuGet package](https://www.nuget.org/). You can search for each package by name. Releases are listed on each packages page. For instance: +- [dotnet-counters](https://www.nuget.org/packages/dotnet-counters) +- [dotnet-dump](https://www.nuget.org/packages/dotnet-dump) +- [dotnet-trace](https://www.nuget.org/packages/dotnet-trace) +### Install -### 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: +These prerelease versions can't be installed without an explicit `--version` option to the [dotnet tool install](../../tools/dotnet-tool-install.md) command. For instance: -> ```bash -> dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 -> ``` +```bash +dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 +``` +### Upgrade -### 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: +To upgrade from or to a prerelease version, [dotnet tool uninstall](../../tools/dotnet-tool-uninstall.md) the previous version of the tool before upgrade. Preview versions can't be automatically updated. For instance: -> ```bash -> dotnet tool install -g dotnet-symbol -> ``` +```bash +dotnet tool uninstall --global dotnet-dump +dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 +``` -### perfcollect -Thet .NET core runtime is instrumented for both perf and LTTng. To facilitate easier collection of both tracing technologies there is a tool called perfcollect. Perfcollect will output the joint trace data into a nettrace file that can be analyzed using PerfView on Windows. To install the tool run the following commands: +## Handling common install problems -> ``` -> curl -OL http://aka.ms/perfcollect -> chmod +x perfcollect -> sudo ./perfcollect install -> ``` +### "Tool already installed" +If you see the error message `Tool 'dotnet-...' is already installed`, you can either: +- [Uninstall](../../tools/dotnet-tool-uninstall.md) the global tool before reinstalling the tool. +- Install to a different path. + +### "Specified command or file was not found" + +If this install is the first global tool or you get message `Could not execute because the specified command or file was not found.`, you need to add the global tools directory to your path. + +| OS | Default global tool path | +|-------------|-------------------------------| +| Linux/macOS | `$HOME/.dotnet/tools` | +| Windows | `%USERPROFILE%\.dotnet\tools` | From 052404d98c54fd76ae5f7909a04780532a218857 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Fri, 23 Aug 2019 15:17:08 -0400 Subject: [PATCH 12/45] More dotnet-counters clean up Revise per Noah Falk's feedback Reorder to make internally consistent. --- .../diagnostics/cli-tools/dotnet-counters.md | 59 +++++++++---------- 1 file changed, 27 insertions(+), 32 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index e9c3af9172fc0..13e52b9d3cece 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -74,11 +74,32 @@ dotnet-counters [--version] *MONITOR* ``` - ### Examples: + dotnet-counters monitor [-h||--help] + [-p|--process-id ] + [--refreshInterval ] + counter_list + + Display periodically refreshing values of selected counters + + -h, --help + Show command line help + + -p,--process-id + The ID of the process that will be monitored + + --refresh-interval + The number of seconds to delay between updating the displayed counters + + counter_list + A space separated list of counters. Counters can be specified provider_name[:counter_name]. If the + provider_name is used without a qualifying counter_name then all counters will be shown. To discover + provider and counter names, use the list command. + + Examples: 1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: - > dotnet-counters monitor --process-id 1902 System.Runtime + > dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime Press p to pause, r to resume, q to quit. System.Runtime: @@ -87,48 +108,22 @@ dotnet-counters [--version] GC Heap Size (MB) 811 Gen 0 GC / second 20 Gen 1 GC / second 4 - Gen 1 GC / Second 1 + Gen 2 GC / second 1 Number of Exceptions / sec 4 - 1. Monitoring just CPU usage and GC heap size from `System.Runtime` at a refresh interval of 5 seconds: + 2. Monitoring just CPU usage and GC heap size from `System.Runtime`: - > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size,exception-count] + > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size] Press p to pause, r to resume, q to quit. System.Runtime: CPU Usage (%) 24 GC Heap Size (MB) 811 - Number of Exceptions / sec 4 - 1. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.0) + 2. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.) > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal Press p to pause, r to resume, q to quit. request 100 ``` - -### Syntax: - -``` - dotnet-counters monitor [-h||--help] - [-p|--process-id ] - [--refreshInterval ] - counter_list - - Display periodically refreshing values of selected counters - - -h, --help - Show command line help - - -p,--process-id - The ID of the process that will be monitored - - --refresh-interval - The number of seconds to delay between updating the displayed counters - - counter_list - A space separated list of counters. Counters can be specified provider_name[:counter_name]. If the - provider_name is used without a qualifying counter_name then all counters will be shown. To discover - provider and counter names, use the list command. -``` From c2bb0812c219e5de6b2ec0b6ed32a9610267a5ea Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Fri, 23 Aug 2019 15:32:01 -0400 Subject: [PATCH 13/45] dotnet-dump feedback --- docs/core/diagnostics/cli-tools/dotnet-dump.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md index b36528301fb58..8a5c858174fba 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-dump.md +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -26,7 +26,7 @@ For details and other options, see [Installing the diagnostics tools](installing ## Using `dotnet-dump` -The next step is to collect a dump. This step 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. +The next step is to collect a dump. This step can be skipped if a core dump has already been generated by the operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy). On Linux, the runtime version must be 3.0 or greater. @@ -37,7 +37,7 @@ Written 98983936 bytes (24166 pages) to core file Complete ``` -Now `analyze` the core dump. Only works on Linux for this preview. +Now `analyze` the core dump. ```bash $ dotnet-dump analyze ./core_20190226_135850 From a988f133a50bf36f45357f266404f828b127b2ec Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Fri, 23 Aug 2019 15:51:53 -0400 Subject: [PATCH 14/45] Cleanup dotnet-trace documentation Apply Noah's suggestions Reorder document for more logical flow Remove ETW keyword table --- .../diagnostics/cli-tools/dotnet-trace.md | 164 +++++++----------- 1 file changed, 62 insertions(+), 102 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index 9c309b7e9c04f..bd278b5660166 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -22,108 +22,6 @@ dotnet tool install --global dotnet-trace For details and other options, see [Installing the diagnostics tools](installing.md). -## Using `dotnet-trace` - -To collect traces, using `dotnet-trace`, you'll need to: - -- First, find out the process identifier (pid) of the .NET Core application to collect traces from. - - - On Windows, there are options such as using the task manager or the `tasklist` command on the cmd window. - - On Linux, the trivial option could be using `pidof` on the terminal window. - -You may also use the command `dotnet-trace list-processes` command to find out what .NET Core processes are running, along with their process IDs. - -- Then, run the following command: - -```bash -dotnet-trace collect --process-id --providers Microsoft-Windows-DotNETRuntime - -Press to exit... -Connecting to process: /dotnet.exe -Collecting to file: /trace.nettrace - Session Id: - Recording trace 721.025 (KB) -``` - -- Finally, stop collection by pressing the \ key, and `dotnet-trace` will finish logging events to *trace.nettrace* file. - -### Using `dotnet-trace` to collect counter values over time - -If you're trying to use `EventCounter` for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real time, you can do that with `dotnet-trace` as well. - -For example, if you want to collect runtime performance counter values, you can use the following command: - -```bash -dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 -``` - -This command will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. - -If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. - -```bash -dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 -``` - -## Viewing the trace captured from `dotnet-trace` - -On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. - -You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at https://www.speedscope.app. - -Note: The .NET Core runtime generates traces in the `nettrace` format, and they're converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. - -## Commonly used keywords for the *Microsoft-Windows-DotNETRuntime* provider - - Runtime keyword name | Keyword Value | Description - ------------------------------ | ----------------: | ------------ -`None` | 0 | -`All` | FFFFFFFFFFFFFFBF | All doesn't include `start-enumeration`. It just isn't that useful. -`GC` | 1 | Logging when garbage collections and finalization happen. -`GCHandle` | 2 | Events when GC handles are set or destroyed. -`Binder` | 4 | -`Loader` | 8 | Logging when modules actually get loaded and unloaded. -`Jit` | 10 | Logging when Just in time (JIT) compilation occurs. -`NGen` | 20 | Logging when precompiled native (NGEN) images are loaded. -`StartEnumeration` | 40 | Indicates that on attach or module load, a rundown of all existing methods should be done. -`StopEnumeration` | 80 | Indicates that on detach or process shutdown, a rundown of all existing methods should be done. -`Security` | 400 | Events associated with validating security restrictions. -`AppDomainResourceManagement` | 800 | Events for logging resource consumption on an app-domain level granularity. -`JitTracing` | 1000 | Logging of the internal workings of the Just In Time compiler. This log is fairly verbose. It details decisions about interesting optimization (like inlining and tail call). -`Interop` | 2000 | Log information about code thunks that transition between managed and unmanaged code. -`Contention` | 4000 | Log when lock contention occurs. ( actually blocks). -`Exception` | 8000 | Log exception processing. -`Threading` | 10000 | Log events associated with the thread pool, and other threading events. -`JittedMethodILToNativeMap` | 20000 | Dump the native to IL mapping of any method that is JIT compiled. -`OverrideAndSuppressNGenEvents` | 40000 | If enabled, will suppress the rundown of NGEN events. -`SupressNGen` | 40000 | This flag suppresses NGEN events. -`JITSymbols` | 60098 | What is needed to get symbols for JIT compiled code.
This keyword is equivalent to `Jit`+`JittedMethodILToNativeMap`+`Loader`+`OverrideAndSuppressNGenEvents`+`StopEnumeration` -`Type` | 80000 | Enables the 'BulkType' event. -`GCHeapDump` | 100000 | Enables the events associated with dumping the GC heap. -`GCSampledObjectAllocationHigh` | 200000 | Enables allocation sampling with the 'fast'. Sample to limit to 100 allocations per second per type. This keyword is good for most detailed performance investigations.
Note this DOES update the allocation path to be slower and only works if the process is started with this option. -`GCHeapSurvivalAndMovement` | 400000 | Enables events associate with object movement or survival with each GC. -`GCHeapCollect` | 800000 | Triggers a GC. Can pass a 64-bit value that will be logged with the GC Start event. This value is so you know which GC you actually triggered. -`GCHeapAndTypeNames` | 1000000 | Indicates that you want type names looked up and put into the events (not just meta-data tokens). -`GCHeapSnapshot` | 1980001 | This keyword provides the flags commonly needed to take a heap .NET Heap snapshot with EventPipe.
This keyword is equivalent to `GC`+`Type`+`GCHeapDump`+`GCHeapCollect`+`GCHeapAndTypeNames` -`GCSampledObjectAllocationLow` | 2000000 | Enables allocation sampling with the 'slow' rate, Sample to limit to 5 allocations per second per type. This keyword is reasonable for monitoring. Note this DOES update the allocation path to be slower and only works if the process is started with this option. -`GCAllObjectAllocation` | 2200000 | Turns on capturing the stack and type of object allocation made by the .NET Runtime. This keyword can be excessively verbose. Consider using `GCSampledObjectAllocationHigh` instead (and `GCSampledObjectAllocationLow` for production scenarios). -`Stack` | 40000000 | Also log the stack trace of events. -`ThreadTransfer` | 80000000 | This keyword allows tracing work item transfer events (thread pool enqueue/dequeue/ioenqueue/iodequeue/a.o.). -`Debugger` | 100000000 | .NET Debugger events -`Monitoring` | 200000000 | Events intended for monitoring on an ongoing basis. -`Codesymbols` | 400000000 | Events that will dump PDBs of dynamically generated assemblies to the EventPipe stream. -`Default` | 4C14FCCBD | Recommend default flags (good compromise on verbosity). - -[source](https://github.com/Microsoft/perfview/blob/master/src/TraceEvent/Parsers/ClrTraceEventParser.cs#L41) - -## More information on .NET Providers - - Provider Name | Information - ------------------------------------- | ------------ -Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) -Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) -Microsoft-DotNETCore-SampleProfiler | Enable the sample profiler - ## `dotnet-trace` help ```bash @@ -180,3 +78,65 @@ Options: -f, --format The format of the output trace file. This defaults to "nettrace" on Windows and "speedscope" on other OSes. ``` + +## Collect a trace with `dotnet-trace` + +To collect traces, using `dotnet-trace`, you'll need to: + +- First, find out the process identifier (pid) of the .NET Core application to collect traces from. + + - On Windows, there are options such as using the task manager or the `tasklist` command on the cmd window. + - On Linux, the trivial option could be using `pidof` on the terminal window. + +You may also use the command `dotnet-trace list-processes` command to find out what .NET Core processes are running, along with their process IDs. + +- Then, run the following command: + +```bash +dotnet-trace collect --process-id + +Press to exit... +Connecting to process: /dotnet.exe +Collecting to file: /trace.nettrace + Session Id: + Recording trace 721.025 (KB) +``` + +## Viewing the trace captured from `dotnet-trace` + +On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. + +You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at https://www.speedscope.app. + +Note: The .NET Core runtime generates traces in the `nettrace` format, and they're converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. +- Finally, stop collection by pressing the \ key, and `dotnet-trace` will finish logging events to *trace.nettrace* file. + +## Using `dotnet-trace` to collect counter values over time + +If you're trying to use `EventCounter` for basic health monitoring in performance-sensitive settings like production environments and you want to collect traces instead of watching them in real time, you can do that with `dotnet-trace` as well. + +For example, if you want to collect runtime performance counter values, you can use the following command: + +```bash +dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 +``` + +This command will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. + +If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. + +```bash +dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 +``` + +## More information on .NET Providers + +The .NET Core runtime supports the following .NET providers. .NET Core uses the same keywords to enable both +`Event Tracing for Windows (ETW)` and `EventPipe` traces. + + Provider Name | Information + ------------------------------------- | ------------ +Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) + +Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) +Microsoft-DotNETCore-SampleProfiler | Enable the sample profiler From f8ced8dc600e832fad82975745f7fd28d7afa2c2 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Fri, 23 Aug 2019 17:57:15 -0400 Subject: [PATCH 15/45] Fix dotnet-trace instructions --- docs/core/diagnostics/cli-tools/dotnet-trace.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index bd278b5660166..3cc1120f3a0cd 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -102,6 +102,8 @@ Collecting to file: /trace.nettrace Recording trace 721.025 (KB) ``` +- Finally, stop collection by pressing the `` key, and `dotnet-trace` will finish logging events to *trace.nettrace* file. + ## Viewing the trace captured from `dotnet-trace` On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. @@ -109,7 +111,6 @@ On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/mic You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at https://www.speedscope.app. Note: The .NET Core runtime generates traces in the `nettrace` format, and they're converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. -- Finally, stop collection by pressing the \ key, and `dotnet-trace` will finish logging events to *trace.nettrace* file. ## Using `dotnet-trace` to collect counter values over time From 54eb3373746d549e8b7232d021c54539d8f074b7 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Fri, 23 Aug 2019 18:56:19 -0400 Subject: [PATCH 16/45] Add overview --- docs/core/diagnostics/cli-tools/overview.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/overview.md b/docs/core/diagnostics/cli-tools/overview.md index 02e51b0d7b988..f70cb0d53e9b2 100644 --- a/docs/core/diagnostics/cli-tools/overview.md +++ b/docs/core/diagnostics/cli-tools/overview.md @@ -1,10 +1,22 @@ --- title: Diagnostic dotnet tools overview - .NET Core -description: An overview of the dotnet global command line tools available to diagnose .NET Core applications. +description: An overview of the dotnet global command-line tools available to diagnose .NET Core applications. author: sdmaclea ms.author: stmaclea ms.date: 08/21/2019 ms.topic: overview #Customer intent: As a .NET Core developer I want to diagnose problems so that I can be productive. --- -# .NET Core dotnet diagnostic global tools +# .NET Core dotnet diagnostic global command-line tools + +## dotnet-counters + +[dotnet-counters](dotnet-counters.md) is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. + +### dotnet-dump + +The [dotnet-dump](dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps all without any native debugger. + +### dotnet-trace + +.NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. From 9f2eff3a432a9d6b9a3f0bb97ceab6cb80195700 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Fri, 23 Aug 2019 18:57:35 -0400 Subject: [PATCH 17/45] Simplify dotnet-dump sentence --- docs/core/diagnostics/cli-tools/dotnet-dump.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md index 8a5c858174fba..3650cc76c5a02 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-dump.md +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -26,7 +26,7 @@ For details and other options, see [Installing the diagnostics tools](installing ## Using `dotnet-dump` -The next step is to collect a dump. This step can be skipped if a core dump has already been generated by the operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy). +The next step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) can each create core dumps. On Linux, the runtime version must be 3.0 or greater. From 6fb48237be88d5eb4761e2322280e3b05a628f23 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 26 Aug 2019 12:50:42 -0400 Subject: [PATCH 18/45] Remove cli-tools/overview Move the content of core/diagnostics/cli-tools/overview.md to core/diagnostics/index.md Adjust TOC. --- docs/core/diagnostics/cli-tools/overview.md | 22 --------------------- docs/core/diagnostics/index.md | 14 +++++++++++++ docs/toc.yml | 4 +--- 3 files changed, 15 insertions(+), 25 deletions(-) delete mode 100644 docs/core/diagnostics/cli-tools/overview.md diff --git a/docs/core/diagnostics/cli-tools/overview.md b/docs/core/diagnostics/cli-tools/overview.md deleted file mode 100644 index f70cb0d53e9b2..0000000000000 --- a/docs/core/diagnostics/cli-tools/overview.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Diagnostic dotnet tools overview - .NET Core -description: An overview of the dotnet global command-line tools available to diagnose .NET Core applications. -author: sdmaclea -ms.author: stmaclea -ms.date: 08/21/2019 -ms.topic: overview -#Customer intent: As a .NET Core developer I want to diagnose problems so that I can be productive. ---- -# .NET Core dotnet diagnostic global command-line tools - -## dotnet-counters - -[dotnet-counters](dotnet-counters.md) is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. - -### dotnet-dump - -The [dotnet-dump](dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps all without any native debugger. - -### dotnet-trace - -.NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. diff --git a/docs/core/diagnostics/index.md b/docs/core/diagnostics/index.md index 188b3f27742cf..763d8c94bb48e 100644 --- a/docs/core/diagnostics/index.md +++ b/docs/core/diagnostics/index.md @@ -21,3 +21,17 @@ Logging and tracing are related techniques. They refer to instrumenting code to ## [Unit testing](../testing/index.md) Unit testing is a key component of continuous integration and deployment of high-quality software. Unit tests are designed to give you an early warning when you break something. + +## .NET Core dotnet diagnostic global command-line tools + +### dotnet-counters + +[dotnet-counters](cli-tools/dotnet-counters.md)is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. + +### dotnet-dump + +The [dotnet-dump](cli-tools/dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps all without any native debugger. + +### dotnet-trace + +.NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](cli-tools/dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. diff --git a/docs/toc.yml b/docs/toc.yml index a8ea090ca1ba8..886a7b164280e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -273,8 +273,6 @@ href: core/diagnostics/logging-tracing.md - name: .NET Core CLI global tools items: - - name: Overview - href: core/diagnostics/cli-tools/overview.md - name: Install href: core/diagnostics/cli-tools/install.md - name: dotnet-counters @@ -342,7 +340,7 @@ - name: Troubleshoot tool usage issues href: core/tools/troubleshoot-usage-issues.md - name: Diagnostics global tools - href: core/diagnostics/cli-tools/overview.md + href: core/diagnostics/index.md#net-core-dotnet-diagnostic-global-command-line-tools - name: Elevated access href: core/tools/elevated-access.md - name: Extensibility Model From 61e44b32dc5165de40e004efceaa051eeeb68d45 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 26 Aug 2019 13:03:16 -0400 Subject: [PATCH 19/45] Add release not avaialble notes --- docs/core/diagnostics/cli-tools/dotnet-counters.md | 8 ++++++++ docs/core/diagnostics/cli-tools/dotnet-dump.md | 12 +++++++++--- docs/core/diagnostics/cli-tools/dotnet-trace.md | 8 ++++++++ 3 files changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index 13e52b9d3cece..a3a926b8504e2 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -21,6 +21,14 @@ dotnet tool install --global dotnet-counters For details and other options, see [Installing the diagnostics tools](installing.md). +> [!NOTE] +> At the time of this writing, the `dotnet-counters` tool has not been released. The prerelease version can be installed using: +> +> ``` +> dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 +> ``` +> + ## Using dotnet-counters *SYNOPSIS* diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/cli-tools/dotnet-dump.md index 3650cc76c5a02..7361ad942ddb2 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-dump.md +++ b/docs/core/diagnostics/cli-tools/dotnet-dump.md @@ -17,13 +17,19 @@ The `dotnet-dump` CLI global tool is a way to collect and analyze Windows and Li To install the latest release version of the `dotnet-dump` [NuGet package](https://www.nuget.org/packages/dotnet-dump): ```bash -$ dotnet tool install -g dotnet-dump -You can invoke the tool using the following command: dotnet-dump -Tool 'dotnet-dump' (version '3.0.0') was successfully installed. +dotnet tool install -g dotnet-dump ``` For details and other options, see [Installing the diagnostics tools](installing.md). +> [!NOTE] +> At the time of this writing, the `dotnet-dump` tool has not been released. The prerelease version can be installed using: +> +> ``` +> dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 +> ``` +> + ## Using `dotnet-dump` The next step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) can each create core dumps. diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/cli-tools/dotnet-trace.md index 3cc1120f3a0cd..dd2ec3939c46c 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-trace.md +++ b/docs/core/diagnostics/cli-tools/dotnet-trace.md @@ -22,6 +22,14 @@ dotnet tool install --global dotnet-trace For details and other options, see [Installing the diagnostics tools](installing.md). +> [!NOTE] +> At the time of this writing, the `dotnet-trace` tool has not been released. The prerelease version can be installed using: +> +> ``` +> dotnet tool install --global dotnet-trace --version 3.0.0-preview8.19412.1 +> ``` +> + ## `dotnet-trace` help ```bash From 43a3087dc46b31bbc4dc512474980b7f7530a52c Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 26 Aug 2019 13:04:45 -0400 Subject: [PATCH 20/45] Fix numbering --- docs/core/diagnostics/cli-tools/dotnet-counters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/cli-tools/dotnet-counters.md index a3a926b8504e2..e660752686f75 100644 --- a/docs/core/diagnostics/cli-tools/dotnet-counters.md +++ b/docs/core/diagnostics/cli-tools/dotnet-counters.md @@ -128,7 +128,7 @@ dotnet-counters [--version] CPU Usage (%) 24 GC Heap Size (MB) 811 - 2. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.) + 3. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.) > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal From 9726cbc75a710946f86183260018ef49ac21e1e7 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 26 Aug 2019 16:43:45 -0400 Subject: [PATCH 21/45] Fix broken link --- docs/toc.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toc.yml b/docs/toc.yml index 886a7b164280e..710b0d5127b27 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -273,8 +273,8 @@ href: core/diagnostics/logging-tracing.md - name: .NET Core CLI global tools items: - - name: Install - href: core/diagnostics/cli-tools/install.md + - name: Installing + href: core/diagnostics/cli-tools/installing.md - name: dotnet-counters href: core/diagnostics/cli-tools/dotnet-counters.md - name: dotnet-dump From 8cd54ffc8ef2b635b66ffdc1db76cfecfc45c677 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 26 Aug 2019 18:13:47 -0400 Subject: [PATCH 22/45] Cleanup index links --- docs/core/diagnostics/index.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/core/diagnostics/index.md b/docs/core/diagnostics/index.md index 763d8c94bb48e..151f169faa1f2 100644 --- a/docs/core/diagnostics/index.md +++ b/docs/core/diagnostics/index.md @@ -13,20 +13,23 @@ Software doesn't always behave as you would expect, but .NET Core has tools and This article helps you find the various tools you need. -## [Managed debuggers](managed-debuggers.md) -Managed debuggers allow you to interact with your program. Pausing, incrementally executing, examining, and resuming gives you insight into the behavior of your code. A debugger is the first choice for diagnosing functional problems that can be easily reproduced. +## Managed debuggers -## [Logging and tracing](logging-tracing.md) -Logging and tracing are related techniques. They refer to instrumenting code to create log files. The files record the details of what a program does. These details can be used to diagnose the most complex problems. When combined with time stamps, these techniques are also valuable in performance investigations. +[Managed debuggers](managed-debuggers.md) allow you to interact with your program. Pausing, incrementally executing, examining, and resuming gives you insight into the behavior of your code. A debugger is the first choice for diagnosing functional problems that can be easily reproduced. -## [Unit testing](../testing/index.md) -Unit testing is a key component of continuous integration and deployment of high-quality software. Unit tests are designed to give you an early warning when you break something. +## Logging and tracing + +[Logging and tracing](logging-tracing.md) are related techniques. They refer to instrumenting code to create log files. The files record the details of what a program does. These details can be used to diagnose the most complex problems. When combined with time stamps, these techniques are also valuable in performance investigations. + +## Unit testing + +[Unit testing](../testing/index.md) is a key component of continuous integration and deployment of high-quality software. Unit tests are designed to give you an early warning when you break something. ## .NET Core dotnet diagnostic global command-line tools ### dotnet-counters -[dotnet-counters](cli-tools/dotnet-counters.md)is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. +[dotnet-counters](cli-tools/dotnet-counters.md) is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. ### dotnet-dump From e134635cb91c501659b876a7978cdb1248ae77f1 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Thu, 19 Sep 2019 11:40:34 -0400 Subject: [PATCH 23/45] Remove one directory level per feedback --- docs/core/diagnostics/{cli-tools => }/dotnet-counters.md | 0 docs/core/diagnostics/{cli-tools => }/dotnet-dump.md | 0 docs/core/diagnostics/{cli-tools => }/dotnet-trace.md | 0 docs/core/diagnostics/index.md | 6 +++--- docs/core/diagnostics/{cli-tools => }/installing.md | 0 docs/toc.yml | 8 ++++---- 6 files changed, 7 insertions(+), 7 deletions(-) rename docs/core/diagnostics/{cli-tools => }/dotnet-counters.md (100%) rename docs/core/diagnostics/{cli-tools => }/dotnet-dump.md (100%) rename docs/core/diagnostics/{cli-tools => }/dotnet-trace.md (100%) rename docs/core/diagnostics/{cli-tools => }/installing.md (100%) diff --git a/docs/core/diagnostics/cli-tools/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md similarity index 100% rename from docs/core/diagnostics/cli-tools/dotnet-counters.md rename to docs/core/diagnostics/dotnet-counters.md diff --git a/docs/core/diagnostics/cli-tools/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md similarity index 100% rename from docs/core/diagnostics/cli-tools/dotnet-dump.md rename to docs/core/diagnostics/dotnet-dump.md diff --git a/docs/core/diagnostics/cli-tools/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md similarity index 100% rename from docs/core/diagnostics/cli-tools/dotnet-trace.md rename to docs/core/diagnostics/dotnet-trace.md diff --git a/docs/core/diagnostics/index.md b/docs/core/diagnostics/index.md index 151f169faa1f2..c7a59d17a9d6c 100644 --- a/docs/core/diagnostics/index.md +++ b/docs/core/diagnostics/index.md @@ -29,12 +29,12 @@ This article helps you find the various tools you need. ### dotnet-counters -[dotnet-counters](cli-tools/dotnet-counters.md) is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. +[dotnet-counters](dotnet-counters.md) is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. ### dotnet-dump -The [dotnet-dump](cli-tools/dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps all without any native debugger. +The [dotnet-dump](dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps all without any native debugger. ### dotnet-trace -.NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](cli-tools/dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. +.NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. diff --git a/docs/core/diagnostics/cli-tools/installing.md b/docs/core/diagnostics/installing.md similarity index 100% rename from docs/core/diagnostics/cli-tools/installing.md rename to docs/core/diagnostics/installing.md diff --git a/docs/toc.yml b/docs/toc.yml index 710b0d5127b27..5c0404fd471fa 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -274,13 +274,13 @@ - name: .NET Core CLI global tools items: - name: Installing - href: core/diagnostics/cli-tools/installing.md + href: core/diagnostics/installing.md - name: dotnet-counters - href: core/diagnostics/cli-tools/dotnet-counters.md + href: core/diagnostics/dotnet-counters.md - name: dotnet-dump - href: core/diagnostics/cli-tools/dotnet-dump.md + href: core/diagnostics/dotnet-dump.md - name: dotnet-trace - href: core/diagnostics/cli-tools/dotnet-trace.md + href: core/diagnostics/dotnet-trace.md - name: Unit Testing href: core/testing/index.md items: From c8e44291ef17910151b5ac10522572ce1ef2ea14 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Tue, 1 Oct 2019 18:04:42 -0400 Subject: [PATCH 24/45] Feedback --- docs/core/diagnostics/dotnet-counters.md | 150 ++++++++--------- docs/core/diagnostics/dotnet-dump.md | 203 +++++++++++++++-------- docs/core/diagnostics/dotnet-trace.md | 201 +++++++++++++--------- docs/core/diagnostics/index.md | 8 +- docs/core/tools/global-tools.md | 2 + docs/toc.yml | 2 - 6 files changed, 338 insertions(+), 228 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index e660752686f75..16a5cc036b59f 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -1,72 +1,67 @@ --- title: dotnet-counters - .NET Core -description: Installing and using the dotnet-counter command-line tool. +description: Learn how to install and use the dotnet-counter command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 08/21/2019 +ms.date: 10/01/2019 --- # dotnet-counters -## Intro - -`dotnet-counters` is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there's anything suspicious before diving into more serious performance investigation using `PerfView` or `dotnet-trace`. +**This article applies to: .NET Core 3.0 SDK and later versions ## Install dotnet-counters -To install the latest release version of the `dotnet-counters` [NuGet package](https://www.nuget.org/packages/dotnet-counters): +To install the latest release version of the `dotnet-counters` [NuGet package](https://www.nuget.org/packages/dotnet-counters), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: -``` +```console dotnet tool install --global dotnet-counters ``` For details and other options, see [Installing the diagnostics tools](installing.md). -> [!NOTE] -> At the time of this writing, the `dotnet-counters` tool has not been released. The prerelease version can be installed using: -> -> ``` -> dotnet tool install --global dotnet-counters --version 3.0.0-preview8.19412.1 -> ``` -> +## Synopsis -## Using dotnet-counters +```dotnetcli +dotnet-counters [-h, --help] [--version] -*SYNOPSIS* +dotnet-counters list [-h|--help] -``` -dotnet-counters [--version] - [-h, --help] - [] +dotnet-counters monitor [-h||--help] [-p|--process-id ] [--refreshInterval ] [counter_list] ``` -*OPTIONS* +## Description -``` - --version - Display the version of the dotnet-counters utility. - -h, --help - Show command line help -``` +`dotnet-counters` is a performance monitoring tool for ad-hoc health monitoring and first-level performance investigation. It can observe performance counter values that are published via the API. For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application to see if there's anything suspicious before diving into more serious performance investigation using `PerfView` or `dotnet-trace`. -*COMMANDS* +## Options -``` - list Display a list of counter names and descriptions - monitor Display periodically refreshing values of selected counters -``` +`--version` + +Display the version of the dotnet-counters utility. -*LIST* +`-h|--help` +Show command-line help. + +## Commands + +| Command | Function | +| --------------------------------------------------- | ------------------------------------------------------------ | +| [dotnet-counters list](#dotnet-counters-list) | Display a list of counter names and descriptions. | +| [dotnet-counters monitor](#dotnet-counters-monitor) | Display periodically refreshing values of selected counters. | + +## dotnet-counters list + +```dotnetcli +dotnet-counters list [-h|--help] ``` - dotnet-counters list [-h|--help] - Display a list of counter names and descriptions, grouped by provider. +Display a list of counter names and descriptions, grouped by provider. - -h, --help - Show command line help +### Example - dotnet-counters list - Examples: - > dotnet-counters list +```console +> dotnet-counters list Showing well-known counters only. Specific processes may support additional counters. System.Runtime @@ -79,59 +74,60 @@ dotnet-counters [--version] exception-count Number of Exceptions / sec ``` -*MONITOR* +## dotnet-counters monitor +```dotnetcli +dotnet-counters monitor [-h||--help] [-p|--process-id ] [--refreshInterval ] [counter_list] ``` - dotnet-counters monitor [-h||--help] - [-p|--process-id ] - [--refreshInterval ] - counter_list - Display periodically refreshing values of selected counters +Display periodically refreshing values of selected counters. - -h, --help - Show command line help +`-p|--process-id` - -p,--process-id - The ID of the process that will be monitored +The ID of the process that will be monitored. - --refresh-interval - The number of seconds to delay between updating the displayed counters +`--refresh-interval` - counter_list - A space separated list of counters. Counters can be specified provider_name[:counter_name]. If the - provider_name is used without a qualifying counter_name then all counters will be shown. To discover - provider and counter names, use the list command. +The number of seconds to delay between updating the displayed counters - Examples: +`counter_list` - 1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: +A space separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying `counter_name`, then all counters will be shown. To discover provider and counter names, use the [dotnet-counters list](#dotnet-counters-list) command. - > dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime +### Examples - dotnet-counters monitor - Press p to pause, r to resume, q to quit. - System.Runtime: - CPU Usage (%) 24 - Working Set (MB) 1982 - GC Heap Size (MB) 811 - Gen 0 GC / second 20 - Gen 1 GC / second 4 - Gen 2 GC / second 1 - Number of Exceptions / sec 4 +1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: - 2. Monitoring just CPU usage and GC heap size from `System.Runtime`: +```console +> dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime - > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size] +Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + Working Set (MB) 1982 + GC Heap Size (MB) 811 + Gen 0 GC / second 20 + Gen 1 GC / second 4 + Gen 2 GC / second 1 + Number of Exceptions / sec 4 +``` + +2. Monitoring just CPU usage and GC heap size from `System.Runtime`: - Press p to pause, r to resume, q to quit. - System.Runtime: - CPU Usage (%) 24 - GC Heap Size (MB) 811 +```console +> dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size] + +Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + GC Heap Size (MB) 811 +``` - 3. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md on how to do this.) +1. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md for details.) - > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal +```console +> dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal - Press p to pause, r to resume, q to quit. - request 100 +Press p to pause, r to resume, q to quit. + request 100 ``` diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 7361ad942ddb2..d10e3fb457a38 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -3,49 +3,160 @@ title: dotnet-dump - .NET Core description: Installing and using the dotnet-dump command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 08/21/2019 +ms.date: 10/01/2019 --- # Dump collection and analysis utility (`dotnet-dump`) -The `dotnet-dump` CLI global tool is a way to collect and analyze Windows and Linux dumps all without any native debugger involved like `lldb` on Linux. This tool 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 native stack frames aren't supported. +**This article applies to: .NET Core 3.0 SDK and later versions > [!NOTE] > `dotnet-dump` is not supported on macOS. ## Installing `dotnet-dump` -To install the latest release version of the `dotnet-dump` [NuGet package](https://www.nuget.org/packages/dotnet-dump): +To install the latest release version of the `dotnet-dump` [NuGet package](https://www.nuget.org/packages/dotnet-dump), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: -```bash +```dotnetcli dotnet tool install -g dotnet-dump ``` For details and other options, see [Installing the diagnostics tools](installing.md). -> [!NOTE] -> At the time of this writing, the `dotnet-dump` tool has not been released. The prerelease version can be installed using: -> -> ``` -> dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 -> ``` -> +## Synopsis -## Using `dotnet-dump` +```dotnetcli +dotnet-dump [-h|--help] [--version] + +dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] + +dotnet-dump analyze [-h|--help] [-c|--command ] +``` + +## Description + +The `dotnet-dump` CLI global tool is a way to collect and analyze Windows and Linux dumps without any native debugger involved like `lldb` on Linux. This tool is important on platforms like Alpine Linux where a fully working `lldb` isn't available. The `dotnet-dump` tool allows you to run SOS commands to analyze crashes and the garbage collector (GC), but it isn't a native debugger so things like displaying native stack frames aren't supported. + +## Options + +`--version` + +Display the version of the dotnet-counters utility. + +`-h|--help` + +Show command-line help. + +## Commands + +| Command | Function | +| ------------------------------------------- | ---------------------------------------------- | +| [dotnet-dump collect](#dotnet-dump-collect) | Capture a dump from a process. | +| [dotnet-dump analyze](#dotnet-dump-analyze) | Starts an interactive shell to explore a dump. | + +## dotnet-dump collect + +```dotnetcli +dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] +``` + +Capture a dump from a process. + +`-p|--process-id ` -The next step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) can each create core dumps. +The process to collect a memory dump from. -On Linux, the runtime version must be 3.0 or greater. +`--type ` -```bash +The dump type determines the kinds of information that are collected from the process. There are two types: + +- `Heap` - A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. +- `Mini` - A small dump containing module lists, thread lists, exception information, and all stacks. + +If not specified `Heap` is the default. + +`-o|--output ` + +The full path and file name where the collected dump should be written. + +If not specified: + +- Where YYYYMMDD is Year/Month/Day and HHMMSS is Hour/Minute/Second... +- Defaults to '.\dump_YYYYMMDD_HHMMSS.dmp' on Windows. +- Defaults to './core_YYYYMMDD_HHMMSS' on Linux. + +`--diag` + +Enable dump collection diagnostic logging. + +## dotnet-dump analyze + +```dotnetcli +dotnet-dump analyze [-h|--help] [-c|--command ] +``` + +Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-SOS-commands). + +`` + +Path to the dump file to analyze. + +`[-c|--command ]` + +Command to run in the shell on start. + +### Analyze SOS commands + +| Command | Function | +| ----------------------------------- | --------------------------------------------------------------------------------------------- | +| `soshelp` | Displays all available commands | +| `soshelp|help ` | Displays the specified command. | +| `exit|quit` | Exit interactive mode. | +| `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 JIT code. | +| `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 ` | Displays the garbage collection stress log relocations related to ``. | +| `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. | +| `lm|modules` | Displays the native modules in the process. | +| `name2ee ` | Displays the MethodTable structure and EEClass structure for the ``. | +| `pe|printexception ` | Displays any object derived from the Exception class at the address ``. | +| `setsymbolserver ` | Enables the symbol server support | +| `syncblk ` | Displays the SyncBlock holder info. | +| `threads|setthread ` | Sets or displays the current thread ID for the SOS commands. | + +## Using `dotnet-dump` + +The first step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) can each create core dumps. + +```dotnetcli $ 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. +Now analyze the core dump with the `analyze` command. -```bash +```console $ 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. @@ -55,7 +166,7 @@ Type 'quit' or 'exit' to exit the session. This action brings up an interactive session that accepts commands like: -```bash +```dotnetcli > clrstack OS Thread Id: 0x573d (0) Child SP IP Call Site @@ -69,9 +180,9 @@ OS Thread Id: 0x573d (0) 00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610] ``` -To see an unhandled exception that terminated your app: +To see an unhandled exception that killed your app: -```bash +```dotnetcli > pe -lines Exception object: 00007fb18c038590 Exception type: System.Reflection.TargetInvocationException @@ -90,52 +201,12 @@ StackTraceString: HResult: 80131604 ``` -To display the help: - - ```bash -> 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 -``` - ## Docker special instructions -If you're running under docker, dump collection requires `SYS_PTRACE` docker capabilities (`--cap-add=SYS_PTRACE or --privileged`). +If you're running under Docker, dump collection requires `SYS_PTRACE` capabilities (`--cap-add=SYS_PTRACE` or `--privileged`). + +On Microsoft .NET Core SDK Linux Docker images, some `dotnet-dump` commands can throw the following exception: + +`Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. -On Microsoft .NET Core SDK Linux docker images, some `dotnet-dump` commands 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. +To work around this problem, install the "libc6-dev" package. diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index dd2ec3939c46c..7995639c7830c 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -3,105 +3,148 @@ title: dotnet-trace - .NET Core description: Installing and using the dotnet-trace command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 08/21/2019 +ms.date: 10/01/2019 --- # Trace for performance analysis utility (`dotnet-trace`) -The `dotnet-trace` tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. It's built around the `EventPipe` technology of the .NET Core runtime as a cross-platform alternative to ETW on Windows and LTTng on Linux, which only work on a single platform. With `EventPipe`/`dotnet-trace`, we're trying to deliver the same experience on Windows, Linux, or macOS. - -> [!NOTE] -> `dotnet-trace` can be used on any .NET Core applications using versions .NET Core 3.0 Preview 7 or later. +**This article applies to: .NET Core 3.0 SDK and later versions ## Installing `dotnet-trace` -To install the latest release version of the `dotnet-trace` [NuGet package](https://www.nuget.org/packages/dotnet-trace): +To install the latest release version of the `dotnet-trace` [NuGet package](https://www.nuget.org/packages/dotnet-trace), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: -``` +```dotnetcli dotnet tool install --global dotnet-trace ``` For details and other options, see [Installing the diagnostics tools](installing.md). -> [!NOTE] -> At the time of this writing, the `dotnet-trace` tool has not been released. The prerelease version can be installed using: -> -> ``` -> dotnet tool install --global dotnet-trace --version 3.0.0-preview8.19412.1 -> ``` -> +## Synopsis -## `dotnet-trace` help +```dotnetcli +dotnet-trace [-h, --help] [--version] -```bash -dotnet.exe run -c Release --no-restore --no-build -- collect --help - -collect: - Collects a diagnostic trace from a currently running process - -Usage: - dotnet-trace collect [options] - -Options: - -h, --help - Shows this help message and exit. - - -p, --process-id - The process to collect the trace from - - -o, --output - The output path for the collected trace data. If not specified it defaults to 'trace.nettrace' - - --profile - A named pre-defined set of provider configurations that allows common tracing scenarios to be specified - succinctly. The options are: - runtime-basic Useful for tracking CPU usage and general runtime information. This the default option - if no profile is specified. - gc Tracks allocation and collection performance - gc-collect Tracks GC collection only at very low overhead - none Tracks nothing. Only providers specified by the --providers option will be available. - - --providers - A list of comma separated EventPipe providers to be enabled. - This option adds to the configuration already provided via the --profile argument. If the same provider is configured in both places, this option takes precedence. - A provider consists of the name and optionally the keywords, verbosity level, and custom key/value pairs. - - The string is written 'Provider[,Provider]' - Provider format: KnownProviderName[:Keywords[:Level][:KeyValueArgs]] - KnownProviderName - The provider's name - Keywords - 8 character hex number bit mask - Level - A number in the range [0, 5] - 0 - Always - 1 - Critical - 2 - Error - 3 - Warning - 4 - Informational - 5 - Verbose - KeyValueArgs - A semicolon separated list of key=value - KeyValueArgs format: '[key1=value1][;key2=value2]' - note: values that contain ';' or '=' characters should be surrounded by double quotes ("), e.g., 'key="value;with=symbols";key2=value2' - - --buffersize - Sets the size of the in-memory circular buffer in megabytes. Default 256 MB. - - -f, --format - The format of the output trace file. This defaults to "nettrace" on Windows and "speedscope" on other OSes. +dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] + [--providers ] [--profile ] [--format ] + +dotnet-trace list-processes [-h|--help] + +dotnet-trace list-profiles [-h|--help] + +dotnet-trace convert [-h|--help] [--format ] [-o|--output ] ``` -## Collect a trace with `dotnet-trace` +## Description + +The `dotnet-trace` tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process without any native profiler involved. It's built around the cross-platform `EventPipe` technology of the .NET Core runtime. `dotnet-trace` delivers the same experience on Windows, Linux, or macOS. + +## Options + +`--version` + +Display the version of the dotnet-counters utility. + +`-h|--help` + +Show command-line help. + +## Commands + +| Command | Function | +| ----------------------------------------------------------- | ------------------------------------------------------- | +| [dotnet-trace collect](#dotnet-trace-collect) | Collects a diagnostic trace from a running process. | +| [dotnet-trace convert](#dotnet-trace-convert) | Converts `nettrace` format traces to alternate formats. | +| [dotnet-trace list-processes](#dotnet-trace-list-processes) | Lists dotnet processes. | +| [dotnet-trace list-profiles](#dotnet-trace-list-profiles) | Lists pre-built tracing profiles. | + +## dotnet-trace collect + +```dotnetcli +dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] + [--providers ] [--profile ] [--format ] +``` + +Collects a diagnostic trace from a running process. + +`-p|--process-id ` + +The process to collect the trace from. + +`--buffersize ` + +Sets the size of the in-memory circular buffer in megabytes. Default 256 MB. + +`-o|--output ` + +The output path for the collected trace data. If not specified it defaults to `trace.nettrace`. + +`--providers ` + +A list of EventPipe providers to be enabled. These providers supplement any providers implied by the `--profile argument`. If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile. -To collect traces, using `dotnet-trace`, you'll need to: +This list of providers is in the form: -- First, find out the process identifier (pid) of the .NET Core application to collect traces from. +- `Provider[,Provider]` +- `Provider` is in the form: `KnownProviderName[:Flags[:Level][:KeyValueArgs]]`. +- `KeyValueArgs` is in the form: `[key1=value1][;key2=value2]`. - - On Windows, there are options such as using the task manager or the `tasklist` command on the cmd window. - - On Linux, the trivial option could be using `pidof` on the terminal window. +`--profile ` -You may also use the command `dotnet-trace list-processes` command to find out what .NET Core processes are running, along with their process IDs. +A named pre-defined set of provider configurations that allows common tracing scenarios to be specified succinctly. + +`--format ` + +Sets the output format for the trace file conversion. + +## dotnet-trace convert + +```dotnetcli +dotnet-trace convert [-h|--help] [--format ] [-o|--output ] +``` + +Converts `nettrace` traces to alternate formats for use with alternate trace analysis tools. + +`[--format ]` + +Sets the output format for the trace file conversion. + +`[-o|--output ]` + +Output filename. Extension of target format will be added. + +`` + +Input trace file to be converted. Defaults to 'trace.nettrace'. + +## dotnet-trace list-processes + +```dotnetcli +dotnet-trace list-processes [-h|--help] +``` + +Lists dotnet processes that can be traced. + +## dotnet-trace list-profiles + +```dotnetcli +dotnet-trace list-profiles [-h|--help] +``` + +Lists pre-built tracing profiles with a description of what providers and filters are in each profile. + +## Collect a trace with `dotnet-trace` + +- To collect traces using `dotnet-trace`, you'll need to first, find out the process identifier (PID) of the .NET Core application to collect traces from. + + - On Windows, there are options such as using the task manager or the `tasklist` command. + - On Linux, the trivial option could be using `ps` command. + +You may also use the [dotnet-trace list-processes](#dotnet-trace-list-processes) command to find out what .NET Core processes are running, along with their PIDs. - Then, run the following command: -```bash -dotnet-trace collect --process-id +```console +> dotnet-trace collect --process-id Press to exit... Connecting to process: /dotnet.exe @@ -110,11 +153,11 @@ Collecting to file: /trace.nettrace Recording trace 721.025 (KB) ``` -- Finally, stop collection by pressing the `` key, and `dotnet-trace` will finish logging events to *trace.nettrace* file. +- Finally, stop collection by pressing the `` key, and `dotnet-trace` will finish logging events to `trace.nettrace` file. ## Viewing the trace captured from `dotnet-trace` -On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can either move the trace to a Windows machine to be viewed on PerfView. +On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can move the trace to a Windows machine to be viewed on PerfView. You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at https://www.speedscope.app. @@ -126,7 +169,7 @@ If you're trying to use `EventCounter` for basic health monitoring in performan For example, if you want to collect runtime performance counter values, you can use the following command: -```bash +```dotnetcli dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 ``` diff --git a/docs/core/diagnostics/index.md b/docs/core/diagnostics/index.md index c7a59d17a9d6c..169c22122b702 100644 --- a/docs/core/diagnostics/index.md +++ b/docs/core/diagnostics/index.md @@ -3,7 +3,7 @@ title: Diagnostics tools overview - .NET Core description: An overview of the tools and techniques available to diagnose .NET Core applications. author: sdmaclea ms.author: stmaclea -ms.date: 08/05/2019 +ms.date: 10/01/2019 ms.topic: overview #Customer intent: As a .NET Core developer I want to find the best tools to help me diagnose problems so that I can be productive. --- @@ -25,15 +25,15 @@ This article helps you find the various tools you need. [Unit testing](../testing/index.md) is a key component of continuous integration and deployment of high-quality software. Unit tests are designed to give you an early warning when you break something. -## .NET Core dotnet diagnostic global command-line tools +## .NET Core dotnet diagnostic Global Tools ### dotnet-counters -[dotnet-counters](dotnet-counters.md) is a performance monitoring tool for ad-hoc health monitoring or first-level performance investigation. It can observe performance counter values that are published via the `EventCounter` [API](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventcounter). For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. +[dotnet-counters](dotnet-counters.md) is a performance monitoring tool for first-level health monitoring and performance investigation. It observes performance counter values published via the API. For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application. ### dotnet-dump -The [dotnet-dump](dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps all without any native debugger. +The [dotnet-dump](dotnet-dump.md) tool is a way to collect and analyze Windows and Linux core dumps without a native debugger. ### dotnet-trace diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md index a0fcfb33b80e7..3001edef1f830 100644 --- a/docs/core/tools/global-tools.md +++ b/docs/core/tools/global-tools.md @@ -33,6 +33,8 @@ You may also find tool recommendations in blog posts or in the [natemcmaster/dot You can also see the source code for the Global Tools created by the ASP.NET team at the [aspnet/DotNetTools](https://github.com/aspnet/DotNetTools/) GitHub repository. +See also [.NET Core dotnet diagnostic Global Tools](../diagnostics/index.md#net-core-dotnet-diagnostic-global-tools). + ## Check the author and statistics Since .NET Core Global Tools run in full trust and are generally installed on your path, they can be very powerful. Don't download tools from people you don't trust. diff --git a/docs/toc.yml b/docs/toc.yml index 5c0404fd471fa..652c3af2a0023 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -339,8 +339,6 @@ href: core/tools/global-tools-how-to-create.md - name: Troubleshoot tool usage issues href: core/tools/troubleshoot-usage-issues.md - - name: Diagnostics global tools - href: core/diagnostics/index.md#net-core-dotnet-diagnostic-global-command-line-tools - name: Elevated access href: core/tools/elevated-access.md - name: Extensibility Model From 95cf02eea5deb6357a0a76d22822f31e23fcf586 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 2 Oct 2019 11:12:31 -0400 Subject: [PATCH 25/45] Fix links --- docs/core/diagnostics/dotnet-dump.md | 2 +- docs/core/diagnostics/installing.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index d10e3fb457a38..00db92cac7742 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -94,7 +94,7 @@ Enable dump collection diagnostic logging. dotnet-dump analyze [-h|--help] [-c|--command ] ``` -Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-SOS-commands). +Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-sos-commands). `` diff --git a/docs/core/diagnostics/installing.md b/docs/core/diagnostics/installing.md index 40a96e0b56090..33abcdc95ab6b 100644 --- a/docs/core/diagnostics/installing.md +++ b/docs/core/diagnostics/installing.md @@ -9,10 +9,10 @@ ms.date: 08/21/2019 Depending on the diagnostics scenario, you can use one or more tools to get to root cause. -These tools are implemented as [.NET Core Global Tools](../../tools/global-tools.md). They're installed, upgraded, and uninstalled using the `dotnet tool` commands: -- [dotnet tool install](../../tools/dotnet-tool-install.md). -- [dotnet tool update](../../tools/dotnet-tool-update.md). -- [dotnet tool uninstall](../../tools/dotnet-tool-uninstall.md). +These tools are implemented as [.NET Core Global Tools](../tools/global-tools.md). They're installed, upgraded, and uninstalled using the `dotnet tool` commands: +- [dotnet tool install](../tools/dotnet-tool-install.md). +- [dotnet tool update](../tools/dotnet-tool-update.md). +- [dotnet tool uninstall](../tools/dotnet-tool-uninstall.md). ## Using prerelease versions @@ -27,7 +27,7 @@ The pre-release packages are published on [NuGet package](https://www.nuget.org/ ### Install -These prerelease versions can't be installed without an explicit `--version` option to the [dotnet tool install](../../tools/dotnet-tool-install.md) command. For instance: +These prerelease versions can't be installed without an explicit `--version` option to the [dotnet tool install](../tools/dotnet-tool-install.md) command. For instance: ```bash dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 @@ -35,7 +35,7 @@ dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 ### Upgrade -To upgrade from or to a prerelease version, [dotnet tool uninstall](../../tools/dotnet-tool-uninstall.md) the previous version of the tool before upgrade. Preview versions can't be automatically updated. For instance: +To upgrade from or to a prerelease version, [dotnet tool uninstall](../tools/dotnet-tool-uninstall.md) the previous version of the tool before upgrade. Preview versions can't be automatically updated. For instance: ```bash dotnet tool uninstall --global dotnet-dump @@ -47,7 +47,7 @@ dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 ### "Tool already installed" If you see the error message `Tool 'dotnet-...' is already installed`, you can either: -- [Uninstall](../../tools/dotnet-tool-uninstall.md) the global tool before reinstalling the tool. +- [Uninstall](../tools/dotnet-tool-uninstall.md) the global tool before reinstalling the tool. - Install to a different path. ### "Specified command or file was not found" From be964ef67fe6bd057a3c5ce0fa6ab5c276738c52 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Wed, 2 Oct 2019 12:26:34 -0400 Subject: [PATCH 26/45] Minor clean up --- docs/core/diagnostics/dotnet-counters.md | 18 +++++++++--------- docs/core/diagnostics/dotnet-dump.md | 12 ++++++------ docs/core/diagnostics/dotnet-trace.md | 14 +++++++------- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 16a5cc036b59f..ccdcf7b007f84 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -13,7 +13,7 @@ ms.date: 10/01/2019 To install the latest release version of the `dotnet-counters` [NuGet package](https://www.nuget.org/packages/dotnet-counters), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: -```console +```dotnetcli dotnet tool install --global dotnet-counters ``` @@ -21,8 +21,8 @@ For details and other options, see [Installing the diagnostics tools](installing ## Synopsis -```dotnetcli -dotnet-counters [-h, --help] [--version] +```console +dotnet-counters [-h|--help] [--version] dotnet-counters list [-h|--help] @@ -52,7 +52,7 @@ Show command-line help. ## dotnet-counters list -```dotnetcli +```console dotnet-counters list [-h|--help] ``` @@ -76,8 +76,8 @@ Display a list of counter names and descriptions, grouped by provider. ## dotnet-counters monitor -```dotnetcli -dotnet-counters monitor [-h||--help] [-p|--process-id ] [--refreshInterval ] [counter_list] +```console +dotnet-counters monitor [-h|--help] [-p|--process-id ] [--refreshInterval ] [counter_list] ``` Display periodically refreshing values of selected counters. @@ -96,7 +96,7 @@ A space separated list of counters. Counters can be specified `provider_name[:co ### Examples - dotnet-counters monitor -1. Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: +- Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: ```console > dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime @@ -112,7 +112,7 @@ Press p to pause, r to resume, q to quit. Number of Exceptions / sec 4 ``` -2. Monitoring just CPU usage and GC heap size from `System.Runtime`: +- Monitoring just CPU usage and GC heap size from `System.Runtime`: ```console > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size] @@ -123,7 +123,7 @@ Press p to pause, r to resume, q to quit. GC Heap Size (MB) 811 ``` -1. Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md for details.) +- Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md for details.) ```console > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 00db92cac7742..6214c0f7a5e78 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -24,7 +24,7 @@ For details and other options, see [Installing the diagnostics tools](installing ## Synopsis -```dotnetcli +```console dotnet-dump [-h|--help] [--version] dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] @@ -55,7 +55,7 @@ Show command-line help. ## dotnet-dump collect -```dotnetcli +```console dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] ``` @@ -90,7 +90,7 @@ Enable dump collection diagnostic logging. ## dotnet-dump analyze -```dotnetcli +```console dotnet-dump analyze [-h|--help] [-c|--command ] ``` @@ -147,7 +147,7 @@ Command to run in the shell on start. The first step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) can each create core dumps. -```dotnetcli +```console $ dotnet-dump collect --process-id 1902 Writing minidump to file ./core_20190226_135837 Written 98983936 bytes (24166 pages) to core file @@ -166,7 +166,7 @@ Type 'quit' or 'exit' to exit the session. This action brings up an interactive session that accepts commands like: -```dotnetcli +```console > clrstack OS Thread Id: 0x573d (0) Child SP IP Call Site @@ -182,7 +182,7 @@ OS Thread Id: 0x573d (0) To see an unhandled exception that killed your app: -```dotnetcli +```console > pe -lines Exception object: 00007fb18c038590 Exception type: System.Reflection.TargetInvocationException diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 7995639c7830c..6812a8a7797dc 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -21,7 +21,7 @@ For details and other options, see [Installing the diagnostics tools](installing ## Synopsis -```dotnetcli +```console dotnet-trace [-h, --help] [--version] dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] @@ -59,7 +59,7 @@ Show command-line help. ## dotnet-trace collect -```dotnetcli +```console dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] [--providers ] [--profile ] [--format ] ``` @@ -98,7 +98,7 @@ Sets the output format for the trace file conversion. ## dotnet-trace convert -```dotnetcli +```console dotnet-trace convert [-h|--help] [--format ] [-o|--output ] ``` @@ -118,7 +118,7 @@ Input trace file to be converted. Defaults to 'trace.nettrace'. ## dotnet-trace list-processes -```dotnetcli +```console dotnet-trace list-processes [-h|--help] ``` @@ -126,7 +126,7 @@ Lists dotnet processes that can be traced. ## dotnet-trace list-profiles -```dotnetcli +```console dotnet-trace list-profiles [-h|--help] ``` @@ -169,7 +169,7 @@ If you're trying to use `EventCounter` for basic health monitoring in performan For example, if you want to collect runtime performance counter values, you can use the following command: -```dotnetcli +```console dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 ``` @@ -177,7 +177,7 @@ This command will tell the runtime counters to be reported once every second for If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. -```bash +```console dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 ``` From de2a1ee9c485ababddc50bd3d6b91ff9b6b207ec Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Fri, 4 Oct 2019 15:31:26 -0700 Subject: [PATCH 27/45] fix formatting/change link --- docs/core/diagnostics/dotnet-counters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index ccdcf7b007f84..6324880850e49 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -7,7 +7,7 @@ ms.date: 10/01/2019 --- # dotnet-counters -**This article applies to: .NET Core 3.0 SDK and later versions +**This article applies to: ✓** .NET Core 3.0 SDK and later versions ## Install dotnet-counters @@ -17,7 +17,7 @@ To install the latest release version of the `dotnet-counters` [NuGet package](h dotnet tool install --global dotnet-counters ``` -For details and other options, see [Installing the diagnostics tools](installing.md). +For details and other options, see [Installing the diagnostics tools](install-tools.md). ## Synopsis From a74e36842452e20a2919f76ebe9da8fe64171f55 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Fri, 4 Oct 2019 15:45:56 -0700 Subject: [PATCH 28/45] formatting + change link --- docs/core/diagnostics/dotnet-dump.md | 89 +++++++++++++++------------- 1 file changed, 49 insertions(+), 40 deletions(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 6214c0f7a5e78..fc6fefd337c87 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -7,10 +7,10 @@ ms.date: 10/01/2019 --- # Dump collection and analysis utility (`dotnet-dump`) -**This article applies to: .NET Core 3.0 SDK and later versions +**This article applies to: ✓** .NET Core 3.0 SDK and later versions > [!NOTE] -> `dotnet-dump` is not supported on macOS. +> `dotnet-dump` isn't supported on macOS. ## Installing `dotnet-dump` @@ -20,16 +20,12 @@ To install the latest release version of the `dotnet-dump` [NuGet package](https dotnet tool install -g dotnet-dump ``` -For details and other options, see [Installing the diagnostics tools](installing.md). +For details and other options, see [Installing the diagnostics tools](install-tools.md). ## Synopsis ```console dotnet-dump [-h|--help] [--version] - -dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] - -dotnet-dump analyze [-h|--help] [-c|--command ] ``` ## Description @@ -38,71 +34,84 @@ The `dotnet-dump` CLI global tool is a way to collect and analyze Windows and Li ## Options -`--version` +- **`--version`** -Display the version of the dotnet-counters utility. +Displays the version of the dotnet-counters utility. -`-h|--help` +- **`-h|--help`** -Show command-line help. +Shows command-line help. ## Commands -| Command | Function | -| ------------------------------------------- | ---------------------------------------------- | -| [dotnet-dump collect](#dotnet-dump-collect) | Capture a dump from a process. | -| [dotnet-dump analyze](#dotnet-dump-analyze) | Starts an interactive shell to explore a dump. | +| Command | +| ------------------------------------------- | +| [dotnet-dump collect](#dotnet-dump-collect) | +| [dotnet-dump analyze](#dotnet-dump-analyze) | ## dotnet-dump collect +Captures a dump from a process. + +### Synopsis + ```console dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] ``` -Capture a dump from a process. +### Options -`-p|--process-id ` +- **`-h|--help`** -The process to collect a memory dump from. + Shows command-line help. -`--type ` +- **`-p|--process-id `** -The dump type determines the kinds of information that are collected from the process. There are two types: + Specifies the process ID number to collect a memory dump from. -- `Heap` - A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. -- `Mini` - A small dump containing module lists, thread lists, exception information, and all stacks. +- **`--type `** -If not specified `Heap` is the default. + Specifies the dumb type, which determines the kinds of information that are collected from the process. There are two types: -`-o|--output ` + - `Heap` - A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. + - `Mini` - A small dump containing module lists, thread lists, exception information, and all stacks. -The full path and file name where the collected dump should be written. + If not specified, `Heap` is the default. -If not specified: +- **`-o|--output `** -- Where YYYYMMDD is Year/Month/Day and HHMMSS is Hour/Minute/Second... -- Defaults to '.\dump_YYYYMMDD_HHMMSS.dmp' on Windows. -- Defaults to './core_YYYYMMDD_HHMMSS' on Linux. + The full path and file name where the collected dump should be written. -`--diag` + If not specified: -Enable dump collection diagnostic logging. + - Defaults to *.\dump_YYYYMMDD_HHMMSS.dmp* on Windows. + - Defaults to *./core_YYYYMMDD_HHMMSS* on Linux. + + YYYYMMDD is Year/Month/Day and HHMMSS is Hour/Minute/Second. + +- **`--diag`** + + Enables dump collection diagnostic logging. ## dotnet-dump analyze +Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-sos-commands). + +### Synopsis + ```console dotnet-dump analyze [-h|--help] [-c|--command ] ``` -Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-sos-commands). +### Options -`` +- **``** -Path to the dump file to analyze. +Specifies the path to the dump file to analyze. -`[-c|--command ]` +- **`[-c|--command ]`** -Command to run in the shell on start. +Specifies the [command](#analyze-sos-commands) to run in the shell on start. ### Analyze SOS commands @@ -110,10 +119,10 @@ Command to run in the shell on start. | ----------------------------------- | --------------------------------------------------------------------------------------------- | | `soshelp` | Displays all available commands | | `soshelp|help ` | Displays the specified command. | -| `exit|quit` | Exit interactive mode. | +| `exit|quit` | Exits interactive mode. | | `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. | +| `clrthreads ` | Lists the managed threads running. | +| `dumpasync ` | Displays information 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. | @@ -154,7 +163,7 @@ Written 98983936 bytes (24166 pages) to core file Complete ``` -Now analyze the core dump with the `analyze` command. +Now analyze the core dump with the `analyze` command: ```console $ dotnet-dump analyze ./core_20190226_135850 From 0cb9c9ab6b9ff4b8dc1bbf742df0b0562a258ba5 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Fri, 4 Oct 2019 15:53:08 -0700 Subject: [PATCH 29/45] Rename installing.md to install-tools.md --- docs/core/diagnostics/{installing.md => install-tools.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/core/diagnostics/{installing.md => install-tools.md} (100%) diff --git a/docs/core/diagnostics/installing.md b/docs/core/diagnostics/install-tools.md similarity index 100% rename from docs/core/diagnostics/installing.md rename to docs/core/diagnostics/install-tools.md From 4a79e7c7ffafd4a80017bb8669ee4d4d4d481e81 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Fri, 4 Oct 2019 15:53:37 -0700 Subject: [PATCH 30/45] Update toc.yml --- docs/toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toc.yml b/docs/toc.yml index 652c3af2a0023..d0c58af3339e5 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -274,7 +274,7 @@ - name: .NET Core CLI global tools items: - name: Installing - href: core/diagnostics/installing.md + href: core/diagnostics/install-tools.md - name: dotnet-counters href: core/diagnostics/dotnet-counters.md - name: dotnet-dump From bd1b3e6cfec0c31591969556c6d3354158107cb0 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Fri, 4 Oct 2019 15:58:22 -0700 Subject: [PATCH 31/45] edit --- docs/core/tools/global-tools.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/core/tools/global-tools.md b/docs/core/tools/global-tools.md index 3001edef1f830..a26d86ab343ec 100644 --- a/docs/core/tools/global-tools.md +++ b/docs/core/tools/global-tools.md @@ -25,15 +25,12 @@ If you want to use a .NET Core Global Tool: ## Find a .NET Core Global Tool -Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI). +Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI). The following are some recommendations on how to find tools: -You can find .NET Core Global Tools on [NuGet](https://www.nuget.org). However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools. - -You may also find tool recommendations in blog posts or in the [natemcmaster/dotnet-tools](https://github.com/natemcmaster/dotnet-tools) GitHub repository. - -You can also see the source code for the Global Tools created by the ASP.NET team at the [aspnet/DotNetTools](https://github.com/aspnet/DotNetTools/) GitHub repository. - -See also [.NET Core dotnet diagnostic Global Tools](../diagnostics/index.md#net-core-dotnet-diagnostic-global-tools). +* You can find .NET Core Global Tools on [NuGet](https://www.nuget.org). However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools. +* You may find tool recommendations in blog posts or in the [natemcmaster/dotnet-tools](https://github.com/natemcmaster/dotnet-tools) GitHub repository. +* You can see the source code for the Global Tools created by the ASP.NET team at the [aspnet/DotNetTools](https://github.com/aspnet/DotNetTools/) GitHub repository. +* You can learn about diagnostic tools at [.NET Core dotnet diagnostic Global Tools](../diagnostics/index.md#net-core-dotnet-diagnostic-global-tools). ## Check the author and statistics From ddf932d9e340c5a85eb00431be367b153ed7cfe6 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Sat, 5 Oct 2019 13:00:14 -0400 Subject: [PATCH 32/45] Remove install-tools.md --- docs/core/diagnostics/dotnet-counters.md | 2 - docs/core/diagnostics/dotnet-dump.md | 2 - docs/core/diagnostics/dotnet-trace.md | 2 - docs/core/diagnostics/install-tools.md | 60 ------------------------ docs/toc.yml | 2 - 5 files changed, 68 deletions(-) delete mode 100644 docs/core/diagnostics/install-tools.md diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 6324880850e49..e9b67960938d9 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -17,8 +17,6 @@ To install the latest release version of the `dotnet-counters` [NuGet package](h dotnet tool install --global dotnet-counters ``` -For details and other options, see [Installing the diagnostics tools](install-tools.md). - ## Synopsis ```console diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index fc6fefd337c87..e4e4840f8a62d 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -20,8 +20,6 @@ To install the latest release version of the `dotnet-dump` [NuGet package](https dotnet tool install -g dotnet-dump ``` -For details and other options, see [Installing the diagnostics tools](install-tools.md). - ## Synopsis ```console diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 6812a8a7797dc..2467cc81317cf 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -17,8 +17,6 @@ To install the latest release version of the `dotnet-trace` [NuGet package](http dotnet tool install --global dotnet-trace ``` -For details and other options, see [Installing the diagnostics tools](installing.md). - ## Synopsis ```console diff --git a/docs/core/diagnostics/install-tools.md b/docs/core/diagnostics/install-tools.md deleted file mode 100644 index 33abcdc95ab6b..0000000000000 --- a/docs/core/diagnostics/install-tools.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Installing dotnet diagnostic tools - .NET Core -description: Installing dotnet diagnostic command-line tools. -author: sdmaclea -ms.author: stmaclea -ms.date: 08/21/2019 ---- -# Installing the `dotnet` diagnostic command-line tools - -Depending on the diagnostics scenario, you can use one or more tools to get to root cause. - -These tools are implemented as [.NET Core Global Tools](../tools/global-tools.md). They're installed, upgraded, and uninstalled using the `dotnet tool` commands: -- [dotnet tool install](../tools/dotnet-tool-install.md). -- [dotnet tool update](../tools/dotnet-tool-update.md). -- [dotnet tool uninstall](../tools/dotnet-tool-uninstall.md). - -## Using prerelease versions - -As tools are developed, we initially release them with a pre-release version. - -### Finding available pre-release versions - -The pre-release packages are published on [NuGet package](https://www.nuget.org/). You can search for each package by name. Releases are listed on each packages page. For instance: -- [dotnet-counters](https://www.nuget.org/packages/dotnet-counters) -- [dotnet-dump](https://www.nuget.org/packages/dotnet-dump) -- [dotnet-trace](https://www.nuget.org/packages/dotnet-trace) - -### Install - -These prerelease versions can't be installed without an explicit `--version` option to the [dotnet tool install](../tools/dotnet-tool-install.md) command. For instance: - -```bash -dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 -``` - -### Upgrade - -To upgrade from or to a prerelease version, [dotnet tool uninstall](../tools/dotnet-tool-uninstall.md) the previous version of the tool before upgrade. Preview versions can't be automatically updated. For instance: - -```bash -dotnet tool uninstall --global dotnet-dump -dotnet tool install --global dotnet-dump --version 3.0.0-preview8.19412.1 -``` - -## Handling common install problems - -### "Tool already installed" - -If you see the error message `Tool 'dotnet-...' is already installed`, you can either: -- [Uninstall](../tools/dotnet-tool-uninstall.md) the global tool before reinstalling the tool. -- Install to a different path. - -### "Specified command or file was not found" - -If this install is the first global tool or you get message `Could not execute because the specified command or file was not found.`, you need to add the global tools directory to your path. - -| OS | Default global tool path | -|-------------|-------------------------------| -| Linux/macOS | `$HOME/.dotnet/tools` | -| Windows | `%USERPROFILE%\.dotnet\tools` | diff --git a/docs/toc.yml b/docs/toc.yml index d0c58af3339e5..d530b71195ed8 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -273,8 +273,6 @@ href: core/diagnostics/logging-tracing.md - name: .NET Core CLI global tools items: - - name: Installing - href: core/diagnostics/install-tools.md - name: dotnet-counters href: core/diagnostics/dotnet-counters.md - name: dotnet-dump From 725aea8abb04aa1759fb428fef09973566dfc3b5 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Sat, 5 Oct 2019 13:26:32 -0400 Subject: [PATCH 33/45] Revise formatiing to match dotnet-dump --- docs/core/diagnostics/dotnet-counters.md | 36 +++++++------ docs/core/diagnostics/dotnet-trace.md | 69 ++++++++++++------------ 2 files changed, 55 insertions(+), 50 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index e9b67960938d9..d27bf916a07ac 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -20,11 +20,7 @@ dotnet tool install --global dotnet-counters ## Synopsis ```console -dotnet-counters [-h|--help] [--version] - -dotnet-counters list [-h|--help] - -dotnet-counters monitor [-h||--help] [-p|--process-id ] [--refreshInterval ] [counter_list] +dotnet-counters [-h|--help] [--version] ``` ## Description @@ -33,29 +29,31 @@ dotnet-counters monitor [-h||--help] [-p|--process-id ] [--refreshInterval ## Options -`--version` +- **`--version`** Display the version of the dotnet-counters utility. -`-h|--help` +- **`-h|--help`** Show command-line help. ## Commands -| Command | Function | -| --------------------------------------------------- | ------------------------------------------------------------ | -| [dotnet-counters list](#dotnet-counters-list) | Display a list of counter names and descriptions. | -| [dotnet-counters monitor](#dotnet-counters-monitor) | Display periodically refreshing values of selected counters. | +| Command | +| --------------------------------------------------- | +| [dotnet-counters list](#dotnet-counters-list) | +| [dotnet-counters monitor](#dotnet-counters-monitor) | ## dotnet-counters list +Display a list of counter names and descriptions, grouped by provider. + +### Synopsis + ```console dotnet-counters list [-h|--help] ``` -Display a list of counter names and descriptions, grouped by provider. - ### Example - dotnet-counters list ```console @@ -74,21 +72,25 @@ Display a list of counter names and descriptions, grouped by provider. ## dotnet-counters monitor +### Synopsis + +Display periodically refreshing values of selected counters. + ```console dotnet-counters monitor [-h|--help] [-p|--process-id ] [--refreshInterval ] [counter_list] ``` -Display periodically refreshing values of selected counters. +### Options -`-p|--process-id` +- **`-p|--process-id`** The ID of the process that will be monitored. -`--refresh-interval` +- **`--refresh-interval`** The number of seconds to delay between updating the displayed counters -`counter_list` +- **`counter_list`** A space separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying `counter_name`, then all counters will be shown. To discover provider and counter names, use the [dotnet-counters list](#dotnet-counters-list) command. diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 2467cc81317cf..d95316c9a6be2 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -20,16 +20,7 @@ dotnet tool install --global dotnet-trace ## Synopsis ```console -dotnet-trace [-h, --help] [--version] - -dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] - [--providers ] [--profile ] [--format ] - -dotnet-trace list-processes [-h|--help] - -dotnet-trace list-profiles [-h|--help] - -dotnet-trace convert [-h|--help] [--format ] [-o|--output ] +dotnet-trace [-h, --help] [--version] ``` ## Description @@ -38,45 +29,49 @@ The `dotnet-trace` tool is a cross-platform CLI global tool that enables the col ## Options -`--version` +- **`--version`** Display the version of the dotnet-counters utility. -`-h|--help` +- **`-h|--help`** Show command-line help. ## Commands -| Command | Function | -| ----------------------------------------------------------- | ------------------------------------------------------- | -| [dotnet-trace collect](#dotnet-trace-collect) | Collects a diagnostic trace from a running process. | -| [dotnet-trace convert](#dotnet-trace-convert) | Converts `nettrace` format traces to alternate formats. | -| [dotnet-trace list-processes](#dotnet-trace-list-processes) | Lists dotnet processes. | -| [dotnet-trace list-profiles](#dotnet-trace-list-profiles) | Lists pre-built tracing profiles. | +| Command | +| ----------------------------------------------------------- | +| [dotnet-trace collect](#dotnet-trace-collect) | +| [dotnet-trace convert](#dotnet-trace-convert) | +| [dotnet-trace list-processes](#dotnet-trace-list-processes) | +| [dotnet-trace list-profiles](#dotnet-trace-list-profiles) | ## dotnet-trace collect +Collects a diagnostic trace from a running process. + +### Synopsis + ```console dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] [--providers ] [--profile ] [--format ] ``` -Collects a diagnostic trace from a running process. +### Options -`-p|--process-id ` +- **`-p|--process-id `** The process to collect the trace from. -`--buffersize ` +- **`--buffersize `** Sets the size of the in-memory circular buffer in megabytes. Default 256 MB. -`-o|--output ` +- **`-o|--output `** The output path for the collected trace data. If not specified it defaults to `trace.nettrace`. -`--providers ` +- **`--providers `** A list of EventPipe providers to be enabled. These providers supplement any providers implied by the `--profile argument`. If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile. @@ -86,50 +81,58 @@ This list of providers is in the form: - `Provider` is in the form: `KnownProviderName[:Flags[:Level][:KeyValueArgs]]`. - `KeyValueArgs` is in the form: `[key1=value1][;key2=value2]`. -`--profile ` +- **`--profile `** A named pre-defined set of provider configurations that allows common tracing scenarios to be specified succinctly. -`--format ` +- **`--format `** Sets the output format for the trace file conversion. ## dotnet-trace convert +Converts `nettrace` traces to alternate formats for use with alternate trace analysis tools. + +### Synopsis + ```console dotnet-trace convert [-h|--help] [--format ] [-o|--output ] ``` -Converts `nettrace` traces to alternate formats for use with alternate trace analysis tools. +### Options -`[--format ]` +- **`[--format ]`** Sets the output format for the trace file conversion. -`[-o|--output ]` +- **`[-o|--output ]`** Output filename. Extension of target format will be added. -`` +- **``** Input trace file to be converted. Defaults to 'trace.nettrace'. ## dotnet-trace list-processes +Lists dotnet processes that can be traced. + +### Synopsis + ```console dotnet-trace list-processes [-h|--help] ``` -Lists dotnet processes that can be traced. - ## dotnet-trace list-profiles +Lists pre-built tracing profiles with a description of what providers and filters are in each profile. + +### Synopsis + ```console dotnet-trace list-profiles [-h|--help] ``` -Lists pre-built tracing profiles with a description of what providers and filters are in each profile. - ## Collect a trace with `dotnet-trace` - To collect traces using `dotnet-trace`, you'll need to first, find out the process identifier (PID) of the .NET Core application to collect traces from. From 1de9cb3684f3e20106addd92aa4f055afd9a6969 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Sun, 13 Oct 2019 23:51:48 -0700 Subject: [PATCH 34/45] fix broken formatting --- docs/core/diagnostics/dotnet-trace.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index d95316c9a6be2..e2e84284fc549 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -7,7 +7,7 @@ ms.date: 10/01/2019 --- # Trace for performance analysis utility (`dotnet-trace`) -**This article applies to: .NET Core 3.0 SDK and later versions +**This article applies to:** .NET Core 3.0 SDK and later versions ## Installing `dotnet-trace` @@ -174,7 +174,7 @@ For example, if you want to collect runtime performance counter values, you can dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1 ``` -This command will tell the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (say 60) will allow you to collect a smaller trace with less granularity in the counter data. +This command tells the runtime counters to be reported once every second for lightweight health monitoring. Replacing `EventCounterIntervalSec=1` with a higher value (for example, 60) allows you to collect a smaller trace with less granularity in the counter data. If you want to disable runtime events to reduce the overhead (and trace size) even further, you can use the following command to disable runtime events and managed stack profiler. @@ -187,9 +187,8 @@ dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCoun The .NET Core runtime supports the following .NET providers. .NET Core uses the same keywords to enable both `Event Tracing for Windows (ETW)` and `EventPipe` traces. - Provider Name | Information - ------------------------------------- | ------------ -Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-runtime-provider)
[CLR Runtime Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#runtime) - -Microsoft-Windows-DotNETRuntimeRundown | [The Rundown Provider](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-providers#the-rundown-provider)
[CLR Rundown Keywords](https://docs.microsoft.com/dotnet/framework/performance/clr-etw-keywords-and-levels#rundown) -Microsoft-DotNETCore-SampleProfiler | Enable the sample profiler +| Provider name | Information | +|------------------------------------------|-------------| +| `Microsoft-Windows-DotNETRuntime` | [The Runtime Provider](../../framework/performance/clr-etw-providers.md#the-runtime-provider)
[CLR Runtime Keywords](../../framework/performance/clr-etw-keywords-and-levels.md#runtime) | +| `Microsoft-Windows-DotNETRuntimeRundown` | [The Rundown Provider](../../framework/performance/clr-etw-providers.md#the-rundown-provider)
[CLR Rundown Keywords](../../framework/performance/clr-etw-keywords-and-levels.md#rundown) | +| `Microsoft-DotNETCore-SampleProfiler` | Enables the sample profiler. | From 67150d3062fa456b8db816886c70242366d5e04c Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Sun, 13 Oct 2019 23:58:16 -0700 Subject: [PATCH 35/45] more formatting fixes --- docs/core/diagnostics/dotnet-trace.md | 33 ++++++++++++++------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index e2e84284fc549..04293fd10752e 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -61,33 +61,33 @@ dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [ - **`-p|--process-id `** -The process to collect the trace from. + The process to collect the trace from. - **`--buffersize `** -Sets the size of the in-memory circular buffer in megabytes. Default 256 MB. + Sets the size of the in-memory circular buffer in megabytes. Default 256 MB. - **`-o|--output `** -The output path for the collected trace data. If not specified it defaults to `trace.nettrace`. + The output path for the collected trace data. If not specified it defaults to `trace.nettrace`. - **`--providers `** -A list of EventPipe providers to be enabled. These providers supplement any providers implied by the `--profile argument`. If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile. + A list of EventPipe providers to be enabled. These providers supplement any providers implied by the `--profile argument`. If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile. -This list of providers is in the form: + This list of providers is in the form: -- `Provider[,Provider]` -- `Provider` is in the form: `KnownProviderName[:Flags[:Level][:KeyValueArgs]]`. -- `KeyValueArgs` is in the form: `[key1=value1][;key2=value2]`. + - `Provider[,Provider]` + - `Provider` is in the form: `KnownProviderName[:Flags[:Level][:KeyValueArgs]]`. + - `KeyValueArgs` is in the form: `[key1=value1][;key2=value2]`. - **`--profile `** -A named pre-defined set of provider configurations that allows common tracing scenarios to be specified succinctly. + A named pre-defined set of provider configurations that allows common tracing scenarios to be specified succinctly. - **`--format `** -Sets the output format for the trace file conversion. + Sets the output format for the trace file conversion. ## dotnet-trace convert @@ -103,15 +103,15 @@ dotnet-trace convert [-h|--help] [--format ] [-o|--output < - **`[--format ]`** -Sets the output format for the trace file conversion. + Sets the output format for the trace file conversion. - **`[-o|--output ]`** -Output filename. Extension of target format will be added. + Output filename. Extension of target format will be added. - **``** -Input trace file to be converted. Defaults to 'trace.nettrace'. + Input trace file to be converted. Defaults to 'trace.nettrace'. ## dotnet-trace list-processes @@ -160,9 +160,10 @@ Collecting to file: /trace.nettrace On Windows, `.nettrace` files can be viewed on [PerfView](https://github.com/microsoft/perfview) for analysis, just like traces collected with ETW or LTTng. For traces collected on Linux, you can move the trace to a Windows machine to be viewed on PerfView. -You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at https://www.speedscope.app. +You may also view the trace on a Linux machine by changing the output format of `dotnet-trace` to `speedscope`. You can change the output file format using the `-f|--format` option - `-f speedscope` will make `dotnet-trace` to produce a `speedscope` file. You can currently choose between `nettrace` (the default option) and `speedscope`. `Speedscope` files can be opened at . -Note: The .NET Core runtime generates traces in the `nettrace` format, and they're converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. +> [!NOTE] +> The .NET Core runtime generates traces in the `nettrace` format, and they're converted to speedscope (if specified) after the trace is completed. Since some conversions may result in loss of data, the original `nettrace` file is preserved next to the converted file. ## Using `dotnet-trace` to collect counter values over time @@ -182,7 +183,7 @@ If you want to disable runtime events to reduce the overhead (and trace size) ev dotnet-trace collect --process-id --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1 ``` -## More information on .NET Providers +## .NET Providers The .NET Core runtime supports the following .NET providers. .NET Core uses the same keywords to enable both `Event Tracing for Windows (ETW)` and `EventPipe` traces. From 9635142f29b1e475caaace07b8db7aab25474c57 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 00:31:45 -0700 Subject: [PATCH 36/45] fix formatting --- docs/core/diagnostics/dotnet-counters.md | 84 ++++++++++++------------ 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index d27bf916a07ac..96dad43187a83 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -31,11 +31,11 @@ dotnet-counters [-h|--help] [--version] - **`--version`** -Display the version of the dotnet-counters utility. + Displays the version of the dotnet-counters utility. - **`-h|--help`** -Show command-line help. + Shows command-line help. ## Commands @@ -46,7 +46,7 @@ Show command-line help. ## dotnet-counters list -Display a list of counter names and descriptions, grouped by provider. +Displays a list of counter names and descriptions, grouped by provider. ### Synopsis @@ -54,7 +54,7 @@ Display a list of counter names and descriptions, grouped by provider. dotnet-counters list [-h|--help] ``` -### Example - dotnet-counters list +### Example ```console > dotnet-counters list @@ -72,62 +72,62 @@ dotnet-counters list [-h|--help] ## dotnet-counters monitor -### Synopsis +Displays periodically refreshing values of selected counters. -Display periodically refreshing values of selected counters. +### Synopsis ```console -dotnet-counters monitor [-h|--help] [-p|--process-id ] [--refreshInterval ] [counter_list] +dotnet-counters monitor [-h|--help] [-p|--process-id] [--refreshInterval] [counter_list] ``` ### Options -- **`-p|--process-id`** +- **`-p|--process-id `** -The ID of the process that will be monitored. + The ID of the process to be monitored. -- **`--refresh-interval`** +- **`--refresh-interval `** -The number of seconds to delay between updating the displayed counters + The number of seconds to delay between updating the displayed counters -- **`counter_list`** +- **`counter_list `** -A space separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying `counter_name`, then all counters will be shown. To discover provider and counter names, use the [dotnet-counters list](#dotnet-counters-list) command. + A space separated list of counters. Counters can be specified `provider_name[:counter_name]`. If the `provider_name` is used without a qualifying `counter_name`, then all counters are shown. To discover provider and counter names, use the [dotnet-counters list](#dotnet-counters-list) command. -### Examples - dotnet-counters monitor +### Examples -- Monitoring all counters from `System.Runtime` at a refresh interval of 3 seconds: +- Monitor all counters from `System.Runtime` at a refresh interval of 3 seconds: -```console -> dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime - -Press p to pause, r to resume, q to quit. - System.Runtime: - CPU Usage (%) 24 - Working Set (MB) 1982 - GC Heap Size (MB) 811 - Gen 0 GC / second 20 - Gen 1 GC / second 4 - Gen 2 GC / second 1 - Number of Exceptions / sec 4 -``` + ```console + > dotnet-counters monitor --process-id 1902 --refresh-interval 3 System.Runtime -- Monitoring just CPU usage and GC heap size from `System.Runtime`: + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + Working Set (MB) 1982 + GC Heap Size (MB) 811 + Gen 0 GC / second 20 + Gen 1 GC / second 4 + Gen 2 GC / second 1 + Number of Exceptions / sec 4 + ``` -```console -> dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size] +- Monitor just CPU usage and GC heap size from `System.Runtime`: -Press p to pause, r to resume, q to quit. - System.Runtime: - CPU Usage (%) 24 - GC Heap Size (MB) 811 -``` + ```console + > dotnet-counters monitor --process-id 1902 System.Runtime[cpu-usage,gc-heap-size] -- Monitoring EventCounter values from user-defined EventSource: (see https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md for details.) + Press p to pause, r to resume, q to quit. + System.Runtime: + CPU Usage (%) 24 + GC Heap Size (MB) 811 + ``` -```console -> dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal +- Monitor `EventCounter` values from user-defined `EventSource`. For more information, see [Tutorial: How to measure performance for very frequent events using EventCounters](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md). -Press p to pause, r to resume, q to quit. - request 100 -``` + ```console + > dotnet-counters monitor --process-id 1902 Samples-EventCounterDemos-Minimal + + Press p to pause, r to resume, q to quit. + request 100 + ``` From 2b0ad14b8155a0cf64ca0a6faaa0536dd3c34f35 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 00:37:33 -0700 Subject: [PATCH 37/45] Update dotnet-dump.md --- docs/core/diagnostics/dotnet-dump.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index e4e4840f8a62d..3d9b6573ae4fa 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -28,17 +28,17 @@ dotnet-dump [-h|--help] [--version] ## Description -The `dotnet-dump` CLI global tool is a way to collect and analyze Windows and Linux dumps without any native debugger involved like `lldb` on Linux. This tool is important on platforms like Alpine Linux where a fully working `lldb` isn't available. The `dotnet-dump` tool allows you to run SOS commands to analyze crashes and the garbage collector (GC), but it isn't a native debugger so things like displaying native stack frames aren't supported. +The `dotnet-dump` global tool is a way to collect and analyze Windows and Linux dumps without any native debugger involved like `lldb` on Linux. This tool is important on platforms like Alpine Linux where a fully working `lldb` isn't available. The `dotnet-dump` tool allows you to run SOS commands to analyze crashes and the garbage collector (GC), but it isn't a native debugger so things like displaying native stack frames aren't supported. ## Options - **`--version`** -Displays the version of the dotnet-counters utility. + Displays the version of the dotnet-counters utility. - **`-h|--help`** -Shows command-line help. + Shows command-line help. ## Commands @@ -54,7 +54,7 @@ Captures a dump from a process. ### Synopsis ```console -dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o|--output ] [--diag] +dotnet-dump collect [-h|--help] [-p|--process-id] [--type] [-o|--output] [--diag] ``` ### Options @@ -63,7 +63,7 @@ dotnet-dump collect [-h|--help] [-p|--process-id ] [--type ] [-o Shows command-line help. -- **`-p|--process-id `** +- **`-p|--process-id `** Specifies the process ID number to collect a memory dump from. @@ -98,18 +98,20 @@ Starts an interactive shell to explore a dump. The shell accepts various [SOS co ### Synopsis ```console -dotnet-dump analyze [-h|--help] [-c|--command ] +dotnet-dump analyze [-h|--help] [-c|--command] ``` -### Options +### Arguments - **``** -Specifies the path to the dump file to analyze. + Specifies the path to the dump file to analyze. + +### Options - **`[-c|--command ]`** -Specifies the [command](#analyze-sos-commands) to run in the shell on start. + Specifies the [command](#analyze-sos-commands) to run in the shell on start. ### Analyze SOS commands @@ -208,12 +210,12 @@ StackTraceString: HResult: 80131604 ``` -## Docker special instructions +## Special instructions for Docker If you're running under Docker, dump collection requires `SYS_PTRACE` capabilities (`--cap-add=SYS_PTRACE` or `--privileged`). On Microsoft .NET Core SDK Linux Docker images, some `dotnet-dump` commands can throw the following exception: -`Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. +> 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. From 9420acf693ce7c3bb771c726a35519c1ae108cf7 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 14 Oct 2019 13:09:39 -0400 Subject: [PATCH 38/45] Improve localization --- docs/core/diagnostics/dotnet-dump.md | 4 ++-- docs/core/diagnostics/dotnet-trace.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 3d9b6573ae4fa..369ee7c4e666b 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -94,8 +94,8 @@ dotnet-dump collect [-h|--help] [-p|--process-id] [--type] [-o|--output] [--diag ## dotnet-dump analyze Starts an interactive shell to explore a dump. The shell accepts various [SOS commands](#analyze-sos-commands). - -### Synopsis + +### Synopsis ```console dotnet-dump analyze [-h|--help] [-c|--command] diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 04293fd10752e..40212160ff9e7 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -53,13 +53,13 @@ Collects a diagnostic trace from a running process. ### Synopsis ```console -dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [-o|--output ] - [--providers ] [--profile ] [--format ] +dotnet-trace collect [-h|--help] [-p|--process-id] [--buffersize ] [-o|--output ] + [--providers] [--profile ] [--format ] ``` ### Options -- **`-p|--process-id `** +- **`-p|--process-id `** The process to collect the trace from. @@ -73,7 +73,7 @@ dotnet-trace collect [-h|--help] [-p|--process-id ] [--buffersize ] [ - **`--providers `** - A list of EventPipe providers to be enabled. These providers supplement any providers implied by the `--profile argument`. If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile. + A comma-separated list of `EventPipe` providers to be enabled. These providers supplement any providers implied by `--profile `. If there's any inconsistency for a particular provider, the configuration here takes precedence over the implicit configuration from the profile. This list of providers is in the form: From 3e8404549c1448758e91436d348bb789465ff909 Mon Sep 17 00:00:00 2001 From: Steve MacLean Date: Mon, 14 Oct 2019 13:24:23 -0400 Subject: [PATCH 39/45] Fix indentation --- docs/core/diagnostics/dotnet-dump.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 369ee7c4e666b..055b9cc171c41 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -71,8 +71,8 @@ dotnet-dump collect [-h|--help] [-p|--process-id] [--type] [-o|--output] [--diag Specifies the dumb type, which determines the kinds of information that are collected from the process. There are two types: - - `Heap` - A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. - - `Mini` - A small dump containing module lists, thread lists, exception information, and all stacks. + - `Heap` - A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. + - `Mini` - A small dump containing module lists, thread lists, exception information, and all stacks. If not specified, `Heap` is the default. @@ -82,10 +82,10 @@ dotnet-dump collect [-h|--help] [-p|--process-id] [--type] [-o|--output] [--diag If not specified: - - Defaults to *.\dump_YYYYMMDD_HHMMSS.dmp* on Windows. - - Defaults to *./core_YYYYMMDD_HHMMSS* on Linux. + - Defaults to *.\dump_YYYYMMDD_HHMMSS.dmp* on Windows. + - Defaults to *./core_YYYYMMDD_HHMMSS* on Linux. - YYYYMMDD is Year/Month/Day and HHMMSS is Hour/Minute/Second. + YYYYMMDD is Year/Month/Day and HHMMSS is Hour/Minute/Second. - **`--diag`** From b2e14fcf8e86ab1a8c52d4462abe911ee5702e0a Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 11:38:10 -0700 Subject: [PATCH 40/45] fix options/arguments --- docs/core/diagnostics/dotnet-trace.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 40212160ff9e7..39aa42c95a3b2 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -53,8 +53,8 @@ Collects a diagnostic trace from a running process. ### Synopsis ```console -dotnet-trace collect [-h|--help] [-p|--process-id] [--buffersize ] [-o|--output ] - [--providers] [--profile ] [--format ] +dotnet-trace collect [-h|--help] [-p|--process-id] [--buffersize ] [-o|--output] + [--providers] [--profile ] [--format] ``` ### Options @@ -96,23 +96,25 @@ Converts `nettrace` traces to alternate formats for use with alternate trace ana ### Synopsis ```console -dotnet-trace convert [-h|--help] [--format ] [-o|--output ] +dotnet-trace convert [] [-h|--help] [--format] [-o|--output] ``` +### Arguments + +- **``** + + Input trace file to be converted. Defaults to *trace.nettrace*. + ### Options -- **`[--format ]`** +- **`--format `** Sets the output format for the trace file conversion. -- **`[-o|--output ]`** +- **`-o|--output `** Output filename. Extension of target format will be added. -- **``** - - Input trace file to be converted. Defaults to 'trace.nettrace'. - ## dotnet-trace list-processes Lists dotnet processes that can be traced. From 3eb1bc743d26992fdf01ec3430c07cfd796c9bd5 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 11:39:34 -0700 Subject: [PATCH 41/45] options formatting --- docs/core/diagnostics/dotnet-dump.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 055b9cc171c41..0320d37cbeb17 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -98,7 +98,7 @@ Starts an interactive shell to explore a dump. The shell accepts various [SOS co ### Synopsis ```console -dotnet-dump analyze [-h|--help] [-c|--command] +dotnet-dump analyze [-h|--help] [-c|--command] ``` ### Arguments @@ -109,7 +109,7 @@ dotnet-dump analyze [-h|--help] [-c|--command] ### Options -- **`[-c|--command ]`** +- **`-c|--command `** Specifies the [command](#analyze-sos-commands) to run in the shell on start. From b801bd8a612c4b7d151ca3649fa6adf1eed43190 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 11:40:07 -0700 Subject: [PATCH 42/45] update ms.date --- docs/core/diagnostics/dotnet-counters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 96dad43187a83..82588789d1988 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -3,7 +3,7 @@ title: dotnet-counters - .NET Core description: Learn how to install and use the dotnet-counter command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 10/01/2019 +ms.date: 10/14/2019 --- # dotnet-counters From 826758e6c0a6c1d5b77d7f49e83e382a06f639fc Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 11:40:27 -0700 Subject: [PATCH 43/45] update ms.date --- docs/core/diagnostics/dotnet-dump.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 0320d37cbeb17..e28420964014d 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -3,7 +3,7 @@ title: dotnet-dump - .NET Core description: Installing and using the dotnet-dump command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 10/01/2019 +ms.date: 10/14/2019 --- # Dump collection and analysis utility (`dotnet-dump`) From 6edd22b69aeecc5ebea9c529493284b55f1c9fd0 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 11:40:46 -0700 Subject: [PATCH 44/45] update ms.date --- docs/core/diagnostics/dotnet-trace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 39aa42c95a3b2..d3898ab90e2c8 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -3,7 +3,7 @@ title: dotnet-trace - .NET Core description: Installing and using the dotnet-trace command-line tool. author: sdmaclea ms.author: stmaclea -ms.date: 10/01/2019 +ms.date: 10/14/2019 --- # Trace for performance analysis utility (`dotnet-trace`) From fcd18b8e7a6258c40478452c8accfd7c04af615f Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 14 Oct 2019 11:41:10 -0700 Subject: [PATCH 45/45] update ms.date --- docs/core/diagnostics/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/index.md b/docs/core/diagnostics/index.md index 169c22122b702..255bbcd0a076d 100644 --- a/docs/core/diagnostics/index.md +++ b/docs/core/diagnostics/index.md @@ -3,7 +3,7 @@ title: Diagnostics tools overview - .NET Core description: An overview of the tools and techniques available to diagnose .NET Core applications. author: sdmaclea ms.author: stmaclea -ms.date: 10/01/2019 +ms.date: 10/14/2019 ms.topic: overview #Customer intent: As a .NET Core developer I want to find the best tools to help me diagnose problems so that I can be productive. ---