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

diff --git a/documentation/dotnet-trace-instructions.md b/documentation/dotnet-trace-instructions.md
index 83791ead5fa8fd71c23642391d244ab79d8cdaf5..d3544f1e437d39c9940c108063ce807e9a4f66d1 100644 (file)
--- 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)<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
 
+## 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 69b9f3bb524ecfe7284b5f1c6ad35f925c391e50..841a7515d7eeab156c03379854b8a2a6f6daec4e 100644 (file)
--- 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<string>(name: "list-of-comma-separated-providers", getDefaultValue: () => string.Empty) // TODO: Can we specify an actual type?
             };