* Move instructions under documentation.
* Update docs with current help string, new option, and repo readme.
* Making dotnet-trace a packable tool
* Updating default CircularBufferSizeMB to 256MB.
* Making RuntimeClient packable.
* Enable `ports` as `endpoints` for end-users
* processId must be greater than zero.
**Currently under construction**
-This repository contains the source code for various .NET Core runtime diagnostic tools. It currently contains SOS, the managed portion of SOS and the lldb SOS plugin. The goals of this repo is to build SOS and the lldb SOS plugin for the portable (glibc based) Linux platform (Centos 7) and the platforms not supported by the portable (musl based) build (Centos 6, Alpine, and macOS) and to test across various indexes in a very large matrix: OSs/distros (Centos 6/7, Ubuntu, Alpine, Fedora, Debian, RHEL 7.2), architectures (x64, x86, arm, arm64), lldb versions (3.9, 4.0, 5.0, 6.0) and .NET Core versions (1.1, 2.0.x, 2.1).
+This repository contains the source code for various .NET Core runtime diagnostic tools. It currently contains SOS, the managed portion of SOS and the lldb SOS plugin. The goals of this repo is to build SOS and the lldb SOS plugin for the portable (glibc based) Linux platform (Centos 7) and the platforms not supported by the portable (musl based) build (Centos 6, Alpine, and macOS) and to test across various indexes in a very large matrix: OSs/distros (Centos 6/7, Ubuntu, Alpine, Fedora, Debian, RHEL 7.2), architectures (x64, x86, arm, arm64), lldb versions (3.9, 4.0, 5.0, 6.0) and .NET Core versions (1.1, 2.0.x, 2.1).
-Another goal to make it easier to obtain a version of lldb (currently 3.9) with scripts and documentation for platforms/distros like Centos, Alpine, Fedora, etc. that by default provide really old versions.
+Another goal to make it easier to obtain a version of lldb (currently 3.9) with scripts and documentation for platforms/distros like Centos, Alpine, Fedora, etc. that by default provide really old versions.
This repo will also allow out of band development of new SOS and lldb plugin features like symbol server support for the .NET Core runtime and solve the source build problem having SOS.NETCore (managed portion of SOS) in the coreclr repo.
## Building the Repository
The build depends on Git, CMake, Python and of course a C++ compiler. Once these prerequisites are installed
-the build is simply a matter of invoking the 'build' script (`build.cmd` or `build.sh`) at the base of the
-repository.
+the build is simply a matter of invoking the 'build' script (`build.cmd` or `build.sh`) at the base of the
+repository.
The details of installing the components differ depending on the operating system. See the following
-pages based on your OS. There is no cross-building across OS (only for ARM, which is built on X64).
-You have to be on the particular platform to build that platform.
+pages based on your OS. There is no cross-building across OS (only for ARM, which is built on X64).
+You have to be on the particular platform to build that platform.
To install the platform's prerequisites:
* [Windows Instructions](documentation/building/windows-instructions.md)
* [Linux Instructions](documentation/building/linux-instructions.md)
* [MacOS Instructions](documentation/building/osx-instructions.md)
- * [FreeBSD Instructions](documentation/building/freebsd-instructions.md)
+ * [FreeBSD Instructions](documentation/building/freebsd-instructions.md)
* [NetBSD Instructions](documentation/building/netbsd-instructions.md)
To build under Windows, run build.cmd from the root of the repository:
```bat
-build.cmd
+build.cmd
[Lots of build spew]
```sh
./test.sh
```
-
-## Getting lldb
+
+## Getting lldb
Getting a version of lldb that works for your platform can be a problem sometimes. The version has to be at least 3.9 or greater because of a bug running SOS on a core dump that was fixed. Some Linux distros like Ubuntu it is easy as `sudo apt-get install lldb-3.9 python-lldb-3.9`. On other distros, you will need to build lldb. The directions below should give you some guidance.
* [Linux Instructions](documentation/lldb/linux-instructions.md)
* [MacOS Instructions](documentation/lldb/osx-instructions.md)
-* [FreeBSD Instructions](documentation/lldb/freebsd-instructions.md)
+* [FreeBSD Instructions](documentation/lldb/freebsd-instructions.md)
* [NetBSD Instructions](documentation/lldb/netbsd-instructions.md)
## Installing SOS
* [Linux and MacOS Instructions](documentation/installing-sos-instructions.md)
* [Windows Instructions](documentation/installing-sos-windows-instructions.md)
-
+
## Using SOS
* [SOS debugging for Linux/MacOS](documentation/sos-debugging-extension.md)
## Tools
* [dotnet-dump](documentation/dotnet-dump-instructions.md) - Dump collection and analysis utility.
+* [dotnet-trace](documentation/dotnet-trace-instructions.md) - Enable the collection of events for a running .NET Core Application to a local trace file.
## New Features
Symbol server support - The `setsymbolserver` command enables downloading the symbol files (portable PDBs) for managed assemblies during commands like `clrstack`, etc. See `soshelp setsymbolserver` for more details.
-
+
(lldb) setsymbolserver -ms
Before executing the "bt" command to dump native frames to load the native symbols (for live debugging only):
[-o|--output <trace-file-path>]
[--pack]
[--profile <profile_name>]
- [--provider <provider_configuration>]
+ [--providers <list-of-comma-separated-providers>]
Collects a diagnostic trace from a currently running process
asp-net-basic Useful starting point for ASP.Net performance investigations
gc Tracks allocation and collection performance
gc-collect Tracks GC collection only at very low overhead
- none Tracks nothing. Only providers specified by the --provider option will be available.
-
- --provider
- A provider configuration specified here adds to the configuration already provided via the --profile
- argument. If the same provider is configured in both places, this option takes precedence.
- A configuration consists of the provider name and optionally keywords, a verbosity level, and custom
- key/value pairs. It is written Name[:Keywords[:Level[:KeyValueArgs]]]
- Name - the provider's name
- Keywords - 8 character hex number bit mask
- Level - 2 character hex number
- KeyValueArgs - a semicolon separated list of key=value
- This argument can be specified multiple times to add any number of provider configurations.
-
+ 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: (GUID|KnownProviderName)[:Keywords[:Level][:KeyValueArgs]]
+ GUID|KnownProviderName - The provider's name
+ Keywords - 8 character hex number bit mask
+ Level - A number in the range [0, 5]
+ KeyValueArgs - A semicolon separated list of key=value
+ KeyValueArgs format: '[key1=value1][;key2=value2]'
+
+ --buffersize <Size>
+ Sets the size of the in-memory circular buffer in megabytes. Default 256 MB.
Examples:
--- /dev/null
+# 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 an alternative to ETW on Windows and LTTNG on non-Windows.
+
+## Installing dotnet-trace
+
+The first step is to install the dotnet-trace CLI global tool. This requires at least version 2.1 of the SDK to be installed.
+
+```cmd
+$ dotnet tool install --global dotnet-trace --version 1.0.3-preview5.19217.3 --add-source https://dotnetfeed.blob.core.windows.net/dotnet-core/index.json
+You can invoke the tool using the following command: dotnet-trace
+Tool 'dotnet-trace' (version '1.0.3-preview5.19217.3') was successfully installed.
+```
+
+## Using dotnet-trace
+
+In order to collect traces you will need to:
+
+- First, find out the process identifier (pid) of the .NET Core 3.0 app 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.
+
+- Then, run the following command:
+
+```cmd
+dotnet-trace collect --process-id <PID> --providers Microsoft-Windows-DotNETRuntime
+
+Press <Enter> to exit...
+Connecting to process: <Full-Path-To-Process-Being-Profiled>/dotnet.exe
+Collecting to file: <Full-Path-To-Trace>/trace.netperf
+ Session Id: <SessionId>
+ Recording trace 721.025 (KB)
+```
+
+- Finally, stop collection by pressing the \<Enter> key, and *dotnet-trace* will finish logging events to *trace.netperf* 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.<br>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.<br>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 ETW.
+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 ETW 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)<br>[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)<br>[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 <pid>
+ The process to collect the trace from
+
+ -o, --output <trace-file-path>
+ The output path for the collected trace data. If not specified it defaults to 'trace.netperf'
+
+ --providers <list-of-comma-separated-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 if 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: (GUID|KnownProviderName)[:Keywords[:Level][:KeyValueArgs]]
+ GUID|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]'
+
+ --buffersize <Size> Sets the size of the in-memory circular buffer
+ in megabytes. Default 256 MB.
+```
<OutputType>Library</OutputType>
<TargetFramework>netcoreapp2.1</TargetFramework>
<RootNamespace>Microsoft.Diagnostics.Tools.RuntimeClient</RootNamespace>
- </PropertyGroup>
+ <GenerateDocumentationFile>True</GenerateDocumentationFile>
- <PropertyGroup>
- <IsPackable>False</IsPackable>
+ <Description>.NET Core Diagnostics Runtime Client</Description>
+ <IsPackable>True</IsPackable>
+ <PackageTags>Diagnostic</PackageTags>
+ <PackageReleaseNotes>$(Description)</PackageReleaseNotes>
</PropertyGroup>
<PropertyGroup>
{
if (output == null)
throw new ArgumentNullException(nameof(output));
+ if (processId <= 0)
+ throw new ArgumentException(nameof(processId));
var configuration = new SessionConfiguration(
circularBufferSizeMB: buffersize,
--- /dev/null
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Microsoft.Diagnostics.Tools.RuntimeClient;
+using System;
+using System.CommandLine;
+using System.Diagnostics;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace Microsoft.Diagnostics.Tools.Trace
+{
+ internal static class EndPointsCommandHandler
+ {
+ public static async Task<int> GetActivePorts(IConsole console)
+ {
+ try
+ {
+ var processes = EventPipeClient.ListAvailablePorts()
+ .Select(GetProcessById)
+ .Where(process => process != null)
+ .OrderBy(process => process.ProcessName)
+ .ThenBy(process => process.Id);
+
+ foreach (var process in processes)
+ Console.Out.WriteLine($"{process.Id, 10} {process.ProcessName, -10} {process.MainModule.FileName}");
+
+ await Task.FromResult(0);
+ return 0;
+ }
+ catch (Exception ex)
+ {
+ Console.Error.WriteLine($"[ERROR] {ex.ToString()}");
+ return 1;
+ }
+ }
+
+ private static Process GetProcessById(int processId)
+ {
+ try
+ {
+ return Process.GetProcessById(processId);
+ }
+ catch (ArgumentException)
+ {
+ return null;
+ }
+ }
+
+ public static Command ActivePortsCommand() =>
+ new Command(
+ name: "endpoints",
+ description: "List all active DotNet Core Diagnostic endpoints.",
+ handler: System.CommandLine.Invocation.CommandHandler.Create<IConsole>(GetActivePorts),
+ isHidden: false);
+ }
+}
+++ /dev/null
-// Licensed to the .NET Foundation under one or more agreements.
-// The .NET Foundation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using Microsoft.Diagnostics.Tools.RuntimeClient;
-using System;
-using System.CommandLine;
-using System.Diagnostics;
-using System.Linq;
-using System.Threading.Tasks;
-
-namespace Microsoft.Diagnostics.Tools.Trace
-{
- internal static class PortsCommandHandler
- {
- public static async Task<int> GetActivePorts(IConsole console)
- {
- try
- {
- var processes = EventPipeClient.ListAvailablePorts()
- .Select(GetProcessById)
- .Where(process => process != null)
- .OrderBy(process => process.ProcessName);
-
- foreach (var process in processes)
- Console.Out.WriteLine($"{process.Id, 10} {process.ProcessName, -10} - {process.MainModule.FileName}");
-
- await Task.FromResult(0);
- return 0;
- }
- catch (Exception ex)
- {
- Console.Error.WriteLine($"[ERROR] {ex.ToString()}");
- return 1;
- }
- }
-
- private static Process GetProcessById(int processId)
- {
- try
- {
- return Process.GetProcessById(processId);
- }
- catch (ArgumentException)
- {
- return null;
- }
- }
-
- public static Command ActivePortsCommand() =>
- new Command(
- name: "ports",
- description: "List all active DotNet Core Diagnostic ports.",
- handler: System.CommandLine.Invocation.CommandHandler.Create<IConsole>(GetActivePorts),
- isHidden: true);
- }
-}
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
-using System;
using System.CommandLine;
namespace Microsoft.Diagnostics.Tools.Trace
new Option(
aliases: new[] { "-p", "--process-id" },
description: "The process to collect the trace from",
- argument: new Argument<int> { Name = "pid" });
+ argument: new Argument<int> { Name = "pid" },
+ isHidden: false);
public static Option OutputPathOption() =>
new Option(
aliases: new[] { "-o", "--output" },
description: "The output path for the collected trace data. If not specified it defaults to 'trace.netperf'",
- argument: new Argument<string>(defaultValue: $"trace.netperf") { Name = "trace-file-path" });
+ argument: new Argument<string>(defaultValue: $"trace.netperf") { Name = "trace-file-path" },
+ isHidden: false);
public static Option ProvidersOption() =>
new Option(
alias: "--providers",
description: @"A list of EventPipe providers to be enabled. This is in the form 'Provider[,Provider]', where Provider is in the form: '(GUID|KnownProviderName)[:Flags[:Level][:KeyValueArgs]]', and KeyValueArgs is in the form: '[key1=value1][;key2=value2]'",
- argument: new Argument<string> { Name = "list-of-comma-separated-providers" }); // TODO: Can we specify an actual type?
+ argument: new Argument<string> { Name = "list-of-comma-separated-providers" }, // TODO: Can we specify an actual type?
+ isHidden: false);
// This is a hidden option, currently not in the design-doc spec.
- private static uint DefaultCircularBufferSizeInMB => 64;
+ private static uint DefaultCircularBufferSizeInMB => 256;
public static Option CircularBufferOption() =>
new Option(
alias: "--buffersize",
description: $"Sets the size of the in-memory circular buffer in megabytes. Default {DefaultCircularBufferSizeInMB} MB",
argument: new Argument<uint>(defaultValue: DefaultCircularBufferSizeInMB) { Name = "size" },
- isHidden: true);
+ isHidden: false);
}
}
{
var parser = new CommandLineBuilder()
#if DEBUG
- .AddCommand(PortsCommandHandler.ActivePortsCommand())
.AddCommand(ProvidersCommandHandler.KnownProvidersCommand())
.AddCommand(StopCommandHandler.StopCommand())
#endif
.AddCommand(CollectCommandHandler.CollectCommand())
+ .AddCommand(EndPointsCommandHandler.ActivePortsCommand())
.UseDefaults()
.Build();
<TargetFramework>netcoreapp2.1</TargetFramework>
<RootNamespace>Microsoft.Diagnostics.Tools.Trace</RootNamespace>
<GenerateDocumentationFile>False</GenerateDocumentationFile>
- </PropertyGroup>
- <PropertyGroup>
- <IsPackable>False</IsPackable>
- <PackAsTool>False</PackAsTool>
+ <ToolCommandName>dotnet-trace</ToolCommandName>
+ <Description>.NET Core Performance Trace Tool</Description>
+ <PackageTags>Diagnostic</PackageTags>
+ <PackageReleaseNotes>$(Description)</PackageReleaseNotes>
+ <!-- Need to put the shims here to sign -->
+ <PackagedShimOutputRootDirectory>$(OutputPath)</PackagedShimOutputRootDirectory>
+
+ <IsPackable>True</IsPackable>
+ <PackAsTool>True</PackAsTool>
+ <RuntimeFrameworkVersion>2.1.0</RuntimeFrameworkVersion>
+ <PackAsToolShimRuntimeIdentifiers>win-x64;win-x86;osx-x64</PackAsToolShimRuntimeIdentifiers>
</PropertyGroup>
<ItemGroup>
projects / platform / core / dotnet / diagnostics.git / commitdiff