From b8df68b614ca6fb25a65e9acd741a3713558dc74 Mon Sep 17 00:00:00 2001 From: John Salem Date: Tue, 15 Dec 2020 13:35:12 -0800 Subject: [PATCH] Update --providers help text with details on filter strings (#542) * Initial update to help text * Move more complex examples to documentation since they don't format well in the help text * Change example in help text --- documentation/dotnet-trace-instructions.md | 23 ++++++++++++++++++- .../CommandLine/Commands/CollectCommand.cs | 9 +++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/documentation/dotnet-trace-instructions.md b/documentation/dotnet-trace-instructions.md index 83791ead5..d3544f1e4 100644 --- a/documentation/dotnet-trace-instructions.md +++ b/documentation/dotnet-trace-instructions.md @@ -166,6 +166,27 @@ Microsoft-Windows-DotNETRuntime | [The Runtime Provider](https://docs.mi 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 +## Example Providers + +See the help text below for the encoding of Providers. + +Examples of valid specifications: +``` +Microsoft-Windows-DotNETRuntime:0xFFF:5 + +Microsoft-Diagnostics-DiagnosticSource:0x00000003:5:FilterAndPayloadSpecs="Microsoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:Command.CommandText;\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:" +``` + +If the provider you are using makes use of filter strings, make sure you +are properly encoding the key-value arguments. Values that contain +`;` or `=` characters need to be surrounded by double quotes `"`. +Depending on your shell environment, you may need to escape the `"` +characters and/or surround the entire argument in quotes, e.g., +```bash +$ dotnet trace collect -p 1234 --providers 'Microsoft-Diagnostics-DiagnosticSource:0x00000003:5:FilterAndPayloadSpecs=\"Microsoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:Command.CommandText;\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:\"' +``` + + ## *dotnet-trace* help ```cmd @@ -204,7 +225,7 @@ Options: 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]] + 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] diff --git a/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs b/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs index 69b9f3bb5..841a7515d 100644 --- a/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs +++ b/src/Tools/dotnet-trace/CommandLine/Commands/CollectCommand.cs @@ -325,7 +325,14 @@ namespace Microsoft.Diagnostics.Tools.Trace private 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: 'KnownProviderName[:Flags[:Level][:KeyValueArgs]]', and KeyValueArgs is in the form: '[key1=value1][;key2=value2]'. These providers are in addition to any providers implied by the --profile argument. If there is any discrepancy for a particular provider, the configuration here takes precedence over the implicit configuration from the profile.") + description: @"A comma delimitted list of EventPipe providers to be enabled. This is in the form 'Provider[,Provider]'," + + @"where Provider is in the form: 'KnownProviderName[:[Flags][:[Level][:[KeyValueArgs]]]]', and KeyValueArgs is in the form: " + + @"'[key1=value1][;key2=value2]'. Values in KeyValueArgs that contain ';' or '=' characters need to be surrounded by '""', " + + @"e.g., FilterAndPayloadSpecs=""MyProvider/MyEvent:-Prop1=Prop1;Prop2=Prop2.A.B;"". Depending on your shell, you may need to " + + @"escape the '""' characters and/or surround the entire provider specification in quotes, e.g., " + + @"--providers 'KnownProviderName:0x1:1:FilterSpec=\""KnownProviderName/EventName:-Prop1=Prop1;Prop2=Prop2.A.B;\""'. These providers are in " + + @"addition to any providers implied by the --profile argument. If there is any discrepancy for a particular provider, the " + + @"configuration here takes precedence over the implicit configuration from the profile. See documentation for examples.") { Argument = new Argument(name: "list-of-comma-separated-providers", getDefaultValue: () => string.Empty) // TODO: Can we specify an actual type? }; -- 2.34.1