From 8879f6d142fa3cc60a2ce172c3144cbee47e7d01 Mon Sep 17 00:00:00 2001 From: mdh1418 Date: Thu, 26 Oct 2023 16:13:43 -0400 Subject: [PATCH 1/4] [diagnostics] Update dotnet-trace collect output default --- docs/core/diagnostics/dotnet-trace.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index e04917e3afd76..2706f62632586 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -161,7 +161,7 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- - **`-o|--output `** - The output path for the collected trace data. If not specified, it defaults to `trace.nettrace`. + The output path for the collected trace data. If not specified it defaults to `__.nettrace`, e.g., `myapp_20210315_111514.nettrace``. - **`-p|--process-id `** From f3743025eb104dbfad6217efc2e29f46089f5bd8 Mon Sep 17 00:00:00 2001 From: mdh1418 Date: Thu, 26 Oct 2023 16:14:39 -0400 Subject: [PATCH 2/4] [diagnostics] Add dotnet-trace collect --resume-runtime and --stopping-event-* options --- docs/core/diagnostics/dotnet-trace.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 2706f62632586..2a8c1cfeeddcd 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -200,6 +200,22 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- Shows the input and output streams of a launched child process in the current console. +- **`--resume-runtime`** + + Resume runtime once session has been initialized, defaults to true. Disable resume of runtime using --resume-runtime:false. + +- **`--stopping-event-provider-name`** + + A string, parsed as-is, that will stop the trace upon hitting an event with the matching provider name. For a more specific stopping event, additionally provide `--stopping-event-event-name` and/or `--stopping-event-payload-filter`. + +- **`--stopping-event-event-name`** + + A string, parsed as-is, that will stop the trace upon hitting an event with the matching event name. Requires `--stopping-event-provider-name` to be set. For a more specific stopping event, additionally provide `--stopping-event-payload-filter`. + +- **`--stopping-event-payload-filter`** + + A string, parsed as [payload_field_name]:[payload_field_value] pairs separated by commas, that will stop the trace upon hitting an event with a matching payload. Requires `--stopping-event-provider-name` and `--stopping-event-event-name` to be set. + > [!NOTE] > - Stopping the trace may take a long time (up to minutes) for large applications. The runtime needs to send over the type cache for all managed code that was captured in the trace. From ac92b5c3020303e62d15c22e423924aba4219697 Mon Sep 17 00:00:00 2001 From: mdh1418 Date: Thu, 26 Oct 2023 16:25:53 -0400 Subject: [PATCH 3/4] [diagnostics] Update dotnet-trace options summary --- docs/core/diagnostics/dotnet-trace.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 2a8c1cfeeddcd..f6452a811c189 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -82,8 +82,11 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- [--format ] [-h|--help] [--duration dd:hh:mm:ss] [-n, --name ] [--diagnostic-port] [-o|--output ] [-p|--process-id ] [--profile ] [--providers ] - [--show-child-io] [-- ] (for target applications running .NET 5 or later) + [--show-child-io] [--resume-runtime] + [--stopping-event-provider-name ] + [--stopping-event-event-name ] + [--stopping-event-payload-filter ] ``` ### Options From 63bbd1589c341db95864a2f19b9249d80e63ee0b Mon Sep 17 00:00:00 2001 From: mdh1418 Date: Fri, 27 Oct 2023 12:40:50 -0400 Subject: [PATCH 4/4] [diagnostics] Provide examples of stopping event options and add note --- docs/core/diagnostics/dotnet-trace.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index f6452a811c189..fe7922717a1a2 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -209,15 +209,15 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- - **`--stopping-event-provider-name`** - A string, parsed as-is, that will stop the trace upon hitting an event with the matching provider name. For a more specific stopping event, additionally provide `--stopping-event-event-name` and/or `--stopping-event-payload-filter`. + A string, parsed as-is, that will stop the trace upon hitting an event with the matching provider name. For a more specific stopping event, additionally provide `--stopping-event-event-name` and/or `--stopping-event-payload-filter`. e.g. `--stopping-event-provider-name Microsoft-Windows-DotNETRuntime` to stop the trace upon hitting the first event emitted by the `Microsoft-Windows-DotNETRuntime` event provider. - **`--stopping-event-event-name`** - A string, parsed as-is, that will stop the trace upon hitting an event with the matching event name. Requires `--stopping-event-provider-name` to be set. For a more specific stopping event, additionally provide `--stopping-event-payload-filter`. + A string, parsed as-is, that will stop the trace upon hitting an event with the matching event name. Requires `--stopping-event-provider-name` to be set. For a more specific stopping event, additionally provide `--stopping-event-payload-filter`. e.g. `--stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted` to stop the trace upon hitting the first `Method/JittingStarted` event emitted by the `Microsoft-Windows-DotNETRuntime` event provider. - **`--stopping-event-payload-filter`** - A string, parsed as [payload_field_name]:[payload_field_value] pairs separated by commas, that will stop the trace upon hitting an event with a matching payload. Requires `--stopping-event-provider-name` and `--stopping-event-event-name` to be set. + A string, parsed as [payload_field_name]:[payload_field_value] pairs separated by commas, that will stop the trace upon hitting an event containing all specified payload pairs. Requires `--stopping-event-provider-name` and `--stopping-event-event-name` to be set. e.g. `--stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick` to stop the trace upon the first `Method/JittingStarted` event for the method `OnButtonClick` in the `Program` namespace emitted by the `Microsoft-Windows-DotNETRuntime` event provider. > [!NOTE] @@ -231,6 +231,8 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- > - If you experience an unhandled exception while running `dotnet-trace collect`, this results in an incomplete trace. If finding the root cause of the exception is your priority, navigate to [Collect dumps on crash](collect-dumps-crash.md). As a result of the unhandled exception, the trace is truncated when the runtime shuts down to prevent other undesired behavior such as a hang or data corruption. Even though the trace is incomplete, you can still open it to see what happened leading up to the failure. However, it will be missing Rundown information (this happens at the end of a trace) so stacks might be unresolved (depending on what providers were turned on). Open the trace by executing PerfView with the `/ContinueOnError` flag at the command line. The logs will also contain the location the exception was fired. +> - When specifying a stopping event through the `--stopping-event-*` options, as the EventStream is being parsed asynchronously, there will be some events that pass through between the time a trace event matching the specified stopping event options is parsed and the EventPipeSession is stopped. + ## dotnet-trace convert Converts `nettrace` traces to alternate formats for use with alternate trace analysis tools.