From 846efe3e28d51b96ef0cc313ef3bf4d851b4c25c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Rivero?= Date: Wed, 24 Apr 2019 17:16:10 -0700 Subject: [PATCH] Renaming non-spec options on dotnet-trace (#192) * Rename the "profiles" verb to "list-profiles" * Rename the "endpoints" verb to "list-processes" * Move pack option/verb to future. * Move the 'g' command (capture GC heap snapshot) to future. * Updating docs with missing functionality. --- documentation/design-docs/dotnet-tools.md | 147 +++++++++--------- .../CommandLine/Commands/CollectCommand.cs | 4 +- ...dler.cs => ListProcessesCommandHandler.cs} | 8 +- ...ndler.cs => ListProfilesCommandHandler.cs} | 8 +- src/Tools/dotnet-trace/Program.cs | 4 +- 5 files changed, 89 insertions(+), 82 deletions(-) rename src/Tools/dotnet-trace/CommandLine/Commands/{EndPointsCommandHandler.cs => ListProcessesCommandHandler.cs} (88%) rename src/Tools/dotnet-trace/CommandLine/Commands/{ProfilesCommandHandler.cs => ListProfilesCommandHandler.cs} (92%) diff --git a/documentation/design-docs/dotnet-tools.md b/documentation/design-docs/dotnet-tools.md index 746e36a51..39a5e80ee 100644 --- a/documentation/design-docs/dotnet-tools.md +++ b/documentation/design-docs/dotnet-tools.md @@ -45,7 +45,6 @@ For analyzing CPU usage, IO, lock contention, allocation rate, etc the investiga Recording trace 38MB 's' - stop tracing - 'g' - capture GC heap snapshot ...Hit 's'... @@ -232,9 +231,7 @@ MONITOR SYNOPSIS - dotnet-trace [--version] - [-h, --help] - [] + dotnet-trace [options] [command] [] OPTIONS @@ -246,16 +243,16 @@ OPTIONS COMMANDS - collect Collects a diagnostic trace from a currently running process - convert Converts traces to alternate formats for use with alternate trace analysis tools - pack Compresses a trace and any necessary symbols into a single zip file for easy off-machine analysis + collect Collects a diagnostic trace from a currently running process + list-processes Lists dotnet processes that can be attached to. + list-profiles Lists pre-built tracing profiles with a description of what providers and filters are in each profile. + convert Converts traces to alternate formats for use with alternate trace analysis tools COLLECT dotnet-trace collect -p|--process-id [-h|--help] [-o|--output ] - [--pack] [--profile ] [--providers ] [-f|--format ] @@ -271,16 +268,11 @@ COLLECT -o, --output The output path for the collected trace data. If not specified it defaults to ./trace.netperf - --pack - Automatically runs the pack command after collection is complete. Use dotnet-trace pack --help for more - details. - --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. - 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 --providers option will be available. @@ -306,19 +298,10 @@ COLLECT Examples: - > dotnet trace collect --process-id 1902 --pack + > dotnet trace collect --process-id 1902 Recording trace 38MB 's' - stop tracing - 'g' - capture GC heap snapshot - - - - > dotnet trace collect --process-id 1902 --pack - Recording trace 107MB - Recording complete (process exited) - Packing... - Trace complete: ~/trace.netperf.zip CONVERT @@ -348,53 +331,6 @@ CONVERT Writing: ./trace.speedscope.json Conversion complete -PACK - - dotnet-trace pack [-h|--help] - [-o|--output ] - [--verbose] - - - Compresses a trace and any necessary symbols into a single zip file for easy off-machine analysis - - -h, --help - Show command line help - - -o, --output - The path where the pack is written. If unspecified the pack is written in the current directory - using the same base filename as the input file and the .zip extension. - - --verbose - Logs detailed information about what the pack command is doing. - - trace_file_path - The path to the trace file that should be packed. - - - Examples: - > dotnet-trace pack trace.netperf - Packing: ./trace.netperf.zip - Pack complete - - > dotnet-trace pack --verbose trace.netperf - Packing: /usr/home/noahfalk/trace.netperf.zip - Compressing /usr/home/noahfalk/trace.netperf - Checking /usr/bin/dotnet/shared/3.0.170/System.Private.CoreLib.dll - Not packing symbols - Policy skips Microsoft binary - Checking /usr/bin/dotnet/shared/3.0.170/System.Diagnostics.dll - Not packing symbols - Policy skips Microsoft binary - Checking /usr/home/noahfalk/MyApp/Newtonsoft.Json.dll - Searching for Newtonsoft.Json.pdb - Searching /usr/home/noahfalk/MyApp/Newtonsoft.Json.pdb - Not packing symbols - Newtonsoft.Json.pdb not found - Checking /usr/home/noahfalk/MyApp/MyApp.dll - Searching for MyApp.pdb - Searching /usr/home/noahfalk/MyApp/MyApp.pdb - Found matching symbol file - Compressing symbol file /usr/home/noahfalk/MyApp/MyApp.pdb - ... - Pack Complete - ### dotnet-dump SYNOPSIS @@ -681,6 +617,75 @@ Dumps a snapshot of counters on demand. In order to make this command fast the E ### dotnet-trace +- Capture GC heap snapshot + +Add a command to `dotnet-trace collect` that enables the collection of GC heap snapshots on an active tracing session. + +- Compress a trace and any necessary symbols into a single zip file for easy off-machine analysis + + OPTION + + [--pack] Automatically runs the pack command after collection is complete. Use dotnet-trace pack --help for more details. + + USAGE + + > dotnet trace collect --process-id 1902 --pack + Recording trace 107MB + Recording complete (process exited) + Packing... + Trace complete: ~/trace.netperf.zip + + VERB + + pack Compresses a trace and any necessary symbols into a single zip file for easy off-machine analysis + + PACK + + dotnet-trace pack [-h|--help] + [-o|--output ] + [--verbose] + + + Compresses a trace and any necessary symbols into a single zip file for easy off-machine analysis + + -h, --help + Show command line help + + -o, --output + The path where the pack is written. If unspecified the pack is written in the current directory + using the same base filename as the input file and the .zip extension. + + --verbose + Logs detailed information about what the pack command is doing. + + trace_file_path + The path to the trace file that should be packed. + + + Examples: + > dotnet-trace pack trace.netperf + Packing: ./trace.netperf.zip + Pack complete + + > dotnet-trace pack --verbose trace.netperf + Packing: /usr/home/noahfalk/trace.netperf.zip + Compressing /usr/home/noahfalk/trace.netperf + Checking /usr/bin/dotnet/shared/3.0.170/System.Private.CoreLib.dll + Not packing symbols - Policy skips Microsoft binary + Checking /usr/bin/dotnet/shared/3.0.170/System.Diagnostics.dll + Not packing symbols - Policy skips Microsoft binary + Checking /usr/home/noahfalk/MyApp/Newtonsoft.Json.dll + Searching for Newtonsoft.Json.pdb + Searching /usr/home/noahfalk/MyApp/Newtonsoft.Json.pdb + Not packing symbols - Newtonsoft.Json.pdb not found + Checking /usr/home/noahfalk/MyApp/MyApp.dll + Searching for MyApp.pdb + Searching /usr/home/noahfalk/MyApp/MyApp.pdb + Found matching symbol file + Compressing symbol file /usr/home/noahfalk/MyApp/MyApp.pdb + ... + Pack Complete + - Multi-process collection Make the --process-id argument optional or let it take a list of ids to create multi-process traces @@ -809,6 +814,8 @@ Show a snapshot of all a processes threads with a callstack for each. ### dotnet-trace +- Add a useful starting point profile for ASP.NET performance investigations + - Does dotnet-trace support other tracing systems or EventPipe only? EventPipe only, at least for now. Trying to be a front-end for various other tracing systems (etw, perf, lttng) comes with a substantial increase in complexity and other tools are already doing that such as PerfView and perfcollect. Although creating a unified front-end might have a little value, it is lower priority than doing a good job at our key goal - providing a platform agnostic solution for managed CPU and memory investigations. diff --git a/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs b/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs index 507eee49a..9343723a7 100644 --- a/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs +++ b/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs @@ -39,7 +39,7 @@ namespace Microsoft.Diagnostics.Tools.Trace if (profile == null) throw new ArgumentNullException(nameof(profile)); - var selectedProfile = ProfilesCommandHandler.DotNETRuntimeProfiles + var selectedProfile = ListProfilesCommandHandler.DotNETRuntimeProfiles .FirstOrDefault(p => p.Name.Equals(profile, StringComparison.OrdinalIgnoreCase)); if (selectedProfile == null) throw new ArgumentException($"Invalid profile name: {profile}"); @@ -189,7 +189,7 @@ namespace Microsoft.Diagnostics.Tools.Trace private static Option CircularBufferOption() => new Option( alias: "--buffersize", - description: $"Sets the size of the in-memory circular buffer in megabytes. Default {DefaultCircularBufferSizeInMB} MB", + description: $"Sets the size of the in-memory circular buffer in megabytes. Default {DefaultCircularBufferSizeInMB} MB.", argument: new Argument(defaultValue: DefaultCircularBufferSizeInMB) { Name = "size" }, isHidden: false); diff --git a/src/Tools/dotnet-trace/CommandLine/Commands/EndPointsCommandHandler.cs b/src/Tools/dotnet-trace/CommandLine/Commands/ListProcessesCommandHandler.cs similarity index 88% rename from src/Tools/dotnet-trace/CommandLine/Commands/EndPointsCommandHandler.cs rename to src/Tools/dotnet-trace/CommandLine/Commands/ListProcessesCommandHandler.cs index 62f1e1002..0e0cfa21a 100644 --- a/src/Tools/dotnet-trace/CommandLine/Commands/EndPointsCommandHandler.cs +++ b/src/Tools/dotnet-trace/CommandLine/Commands/ListProcessesCommandHandler.cs @@ -11,7 +11,7 @@ using System.Threading.Tasks; namespace Microsoft.Diagnostics.Tools.Trace { - internal static class EndPointsCommandHandler + internal static class ListProcessesCommandHandler { public static async Task GetActivePorts(IConsole console) { @@ -48,10 +48,10 @@ namespace Microsoft.Diagnostics.Tools.Trace } } - public static Command ActivePortsCommand() => + public static Command ListProcessesCommand() => new Command( - name: "endpoints", - description: "List all active DotNet Core Diagnostic endpoints.", + name: "list-processes", + description: "Lists dotnet processes that can be attached to.", handler: System.CommandLine.Invocation.CommandHandler.Create(GetActivePorts), isHidden: false); } diff --git a/src/Tools/dotnet-trace/CommandLine/Commands/ProfilesCommandHandler.cs b/src/Tools/dotnet-trace/CommandLine/Commands/ListProfilesCommandHandler.cs similarity index 92% rename from src/Tools/dotnet-trace/CommandLine/Commands/ProfilesCommandHandler.cs rename to src/Tools/dotnet-trace/CommandLine/Commands/ListProfilesCommandHandler.cs index cf8f0e99b..d0cfe22a5 100644 --- a/src/Tools/dotnet-trace/CommandLine/Commands/ProfilesCommandHandler.cs +++ b/src/Tools/dotnet-trace/CommandLine/Commands/ListProfilesCommandHandler.cs @@ -13,7 +13,7 @@ using System.Threading.Tasks; namespace Microsoft.Diagnostics.Tools.Trace { - internal sealed class ProfilesCommandHandler + internal sealed class ListProfilesCommandHandler { public static async Task GetProfiles(IConsole console) { @@ -32,10 +32,10 @@ namespace Microsoft.Diagnostics.Tools.Trace } } - public static Command ProfilesCommand() => + public static Command ListProfilesCommand() => new Command( - name: "profiles", - description: "List pre-defined set of provider aliases that allows common tracing scenarios to be specified.", + name: "list-profiles", + description: "Lists pre-built tracing profiles with a description of what providers and filters are in each profile.", handler: CommandHandler.Create(GetProfiles), isHidden: false); diff --git a/src/Tools/dotnet-trace/Program.cs b/src/Tools/dotnet-trace/Program.cs index be774b562..c0099a2c0 100644 --- a/src/Tools/dotnet-trace/Program.cs +++ b/src/Tools/dotnet-trace/Program.cs @@ -17,8 +17,8 @@ namespace Microsoft.Diagnostics.Tools.Trace .AddCommand(StopCommandHandler.StopCommand()) #endif .AddCommand(CollectCommandHandler.CollectCommand()) - .AddCommand(EndPointsCommandHandler.ActivePortsCommand()) - .AddCommand(ProfilesCommandHandler.ProfilesCommand()) + .AddCommand(ListProcessesCommandHandler.ListProcessesCommand()) + .AddCommand(ListProfilesCommandHandler.ListProfilesCommand()) .UseDefaults() .Build(); -- 2.34.1