Add instructions on dotnet-counter and dotnet-trace usage at startup (#1681)

* Add instructions on dotnet-counter and dotnet-trace usage on monitor/collect at startup

* typo

diff --git a/documentation/dotnet-counters-instructions.md b/documentation/dotnet-counters-instructions.md
index 4ae22cd17b7548a3dd322942dc3eafdd21a9c84e..6afc9d221aef3c3f0f94a554d3d66712e3dc8e26 100644 (file)
--- a/documentation/dotnet-counters-instructions.md
+++ b/documentation/dotnet-counters-instructions.md
@@ -105,13 +105,28 @@ dotnet tool install --global dotnet-counters
     Press p to pause, r to resume, q to quit.
         request                                      100
 
+    4. Launch `my-aspnet-server.exe` with `arg1` and `arg2` as command-line arguments and monitor its GC heap size and working set from startup.
+
+    NOTE: This works for apps running .NET 5.0 or later only.
+
+     ```console
+    > dotnet-counters monitor --counters System.Runtime[assembly-count] -- my-aspnet-server.exe arg1 arg2
+
+    Press p to pause, r to resume, q to quit.
+        Status: Running
+
+    [System.Runtime]
+        GC Heap Size (MB)                                 39
+        Working Set (MB)                                  59
+    ```
 
     ### Syntax:
 
     dotnet-counters monitor [-h||--help]
                             [-p|--process-id <pid>]
                             [--refresh-interval <sec>]
-                            counter_list
+                            [--counters <counters>]
+                            [-- <command>]
     
     Display periodically refreshing values of selected counters
     
@@ -124,11 +139,14 @@ dotnet tool install --global dotnet-counters
     --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
+    --counters
+        A comma 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.
 
+    -- <command> (for target applications running .NET 5.0 or later only)
+        After the collection configuration parameters, the user can append `--` followed by a command to start a .NET application with at least a 5.0 runtime. `dotnet-counters` will launch a process with the provided command and collect the requested metrics.
+
 *COLLECT*
 
 ### Examples: 
@@ -145,6 +163,13 @@ dotnet tool install --global dotnet-counters
     dotnet-counters collect --process-id 863148 --output mycounter --format csv System.Runtime Microsoft.AspNetCore.Hosting
 ```
 
+3. Launch `my-aspnet-server` and collect the assembly-count counter from its startup.
+
+  NOTE: This works for apps running .NET 5.0 or later only.
+
+```bash
+$ dotnet-counters monitor --counters System.Runtime[assembly-count] -- my-aspnet-server.exe
+```
 
     ### Syntax:
 
@@ -153,8 +178,9 @@ dotnet tool install --global dotnet-counters
                             [-n|--name <name>]
                             [-o|--output <name>]
                             [--format <csv|json>]
-                            [--refreshInterval <sec>]
-                            counter_list
+                            [--refresh-interval <sec>]
+                            [--counters <counters>]
+                            [-- <command>]
     
     Periodically collect selected counter values and export them into a specified file format for post-processing.
     
@@ -176,7 +202,10 @@ dotnet tool install --global dotnet-counters
     --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
+    --counters
+        A comma 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.
+
+    -- <command> (for target applications running .NET 5.0 or later only)
+        After the collection configuration parameters, the user can append `--` followed by a command to start a .NET application with at least a 5.0 runtime. `dotnet-counters` will launch a process with the provided command and collect the requested metrics.
\ No newline at end of file

diff --git a/documentation/dotnet-trace-instructions.md b/documentation/dotnet-trace-instructions.md
index d3d78c158b8e96c01b6f07a6ad9afa9c9ad8ee7f..da36014b7fe19aba78491cb8c8ca51e40fabc7a1 100644 (file)
--- a/documentation/dotnet-trace-instructions.md
+++ b/documentation/dotnet-trace-instructions.md
@@ -52,7 +52,43 @@ If you want to disable runtime events to reduce the overhead (and trace size) ev
 ```cmd
 dotnet-trace collect --process-id <PID> --providers System.Runtime:0:1:EventCounterIntervalSec=1,Microsoft-Windows-DotNETRuntime:0:1,Microsoft-DotNETCore-SampleProfiler:0:1
 ```
- 
+
+## Using dotnet-trace to launch a child process and trace it from startup.
+
+Sometimes it may be useful to collect a trace of a process from its startup. For apps running .NET 5.0 or later, it is possible to do this by using dotnet-trace.
+
+This will launch `hello.exe` with `arg1` and `arg2` as its command line arguments and collect a trace from its runtime startup:
+
+```console
+dotnet-trace collect -- hello.exe arg1 arg2
+```
+
+The preceding command generates output similar to the following:
+
+```console
+No profile or providers specified, defaulting to trace profile 'cpu-sampling'
+
+Provider Name                           Keywords            Level               Enabled By
+Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile
+Microsoft-Windows-DotNETRuntime         0x00000014C14FCCBD  Informational(4)    --profile
+
+Process        : E:\temp\gcperfsim\bin\Debug\net5.0\gcperfsim.exe
+Output File    : E:\temp\gcperfsim\trace.nettrace
+
+
+[00:00:00:05]   Recording trace 122.244  (KB)
+Press <Enter> or <Ctrl+C> to exit...
+```
+
+You can stop collecting the trace by pressing `<Enter>` or `<Ctrl + C>` key. Doing this will also exit `hello.exe`.
+
+### NOTE
+* Launching `hello.exe` via dotnet-trace will make its input/output to be redirected and you won't be able to interact with its stdin/stdout.
+
+* Exiting the tool via CTRL+C or SIGTERM will safely end both the tool and the child process.
+
+* If the child process exits before the tool, the tool will exit as well and the trace should be safely viewable.
+
 
 ## Viewing the trace captured from dotnet-trace
 
@@ -219,3 +255,6 @@ Options:
 
   -f, --format
     The format of the output trace file.  This defaults to "nettrace" on Windows and "speedscope" on other OSes.
+
+  -- <command> (for target applications running .NET 5.0 or later only)
+    The command to run to launch a child process and trace from startup.
\ No newline at end of file