Update diagnostic-port details (#45669)

noahfalk · gewarren · web-flow · commit f3091f7ec20e · 2025-04-10T07:57:26.000Z
* Update diagnostic-port details

- Include the diagnostic-port option for dotnet-gcdump which previously lacked it
- Give a bit more detail about how diagnostic-port should be specified for all the tools that currently support it
- Move the warnings about sharing the TMPDIR to the specific --name and --process-id arguments because it shouldn't be a requirement when specifying a full path using --diagnostic-port

* Apply suggestions from code review

Co-authored-by: Genevieve Warren &lt;24882762+gewarren@users.noreply.github.com&gt;
diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md
@@ -79,13 +79,29 @@ dotnet-counters collect [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic-
 
   The ID of the process to collect counter data from.
 
+  > [!NOTE]
+  > On Linux and macOS, using this option requires the target application and `dotnet-counters` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
+
 - **`-n|--name <name>`**
 
   The name of the process to collect counter data from.
 
-- **`--diagnostic-port`**
+  > [!NOTE]
+  > On Linux and macOS, using this option requires the target application and `dotnet-counters` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
 
-  The name of the diagnostic port to create. See [using diagnostic port](#using-diagnostic-port) for how to use this option to start monitoring counters from app startup.
+- **`--diagnostic-port <port-address[,(listen|connect)]>`**
+
+  Sets the [diagnostic port](diagnostic-port.md) used to communicate with the process to be monitored. dotnet-counters and the .NET runtime inside the target process must agree on the port-address, with one listening and the other connecting. dotnet-counters automatically determines the correct port when attaching using the `--process-id` or `--name` options, or when launching a process using the `-- <command>` option. It's usually only necessary to specify the port explicitly when waiting for a process that will start in the future or communicating to a process that is running inside a container that isn't part of the current process namespace.
+
+  The `port-address` differs by OS:
+
+  - Linux and macOS - a path to a Unix domain socket such as `/foo/tool1.socket`.
+  - Windows - a path to a named pipe such as `\\.\pipe\my_diag_port1`.
+  - Android, iOS, and tvOS - an IP:port such as `127.0.0.1:9000`.
+  
+  By default, dotnet-counters listens at the specified address. You can request dotnet-counters to connect instead by appending `,connect` after the address. For example, `--diagnostic-port /foo/tool1.socket,connect` will connect to a .NET runtime process that's listening to the `/foo/tool1.socket` Unix domain socket.
+
+  For information about how to use this option to start monitoring counters from app startup, see [using diagnostic port](#using-diagnostic-port).
 
 - **`--refresh-interval <SECONDS>`**
 
@@ -113,9 +129,6 @@ dotnet-counters collect [-h|--help] [-p|--process-id] [-n|--name] [--diagnostic-
   > [!NOTE]
   > Launching a .NET executable via dotnet-counters will redirect its input/output 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. If you need to use stdin/stdout, you can use the `--diagnostic-port` option. See [Using diagnostic port](#using-diagnostic-port) for more information.
 
-> [!NOTE]
-> On Linux and macOS, this command expects the target application and `dotnet-counters` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
-
 > [!NOTE]
 > To collect metrics using `dotnet-counters`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
 
diff --git a/docs/core/diagnostics/dotnet-gcdump.md b/docs/core/diagnostics/dotnet-gcdump.md
@@ -93,6 +93,9 @@ dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-f
 
   The process ID to collect the GC dump from.
 
+  > [!NOTE]
+  > On Linux and macOS, using this option requires the target application and `dotnet-gcdump` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
+
 - **`-o|--output <gcdump-file-path>`**
 
   The path where collected GC dumps should be written. Defaults to *.\\YYYYMMDD\_HHMMSS\_\<pid>.gcdump*.
@@ -109,8 +112,20 @@ dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-f
 
   The name of the process to collect the GC dump from.
 
-> [!NOTE]
-> On Linux and macOS, this command expects the target application and `dotnet-gcdump` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
+  > [!NOTE]
+  > On Linux and macOS, using this option requires the target application and `dotnet-gcdump` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
+
+- **`--diagnostic-port <port-address[,(listen|connect)]>`**
+
+  Sets the [diagnostic port](diagnostic-port.md) used to communicate with the process to be dumped. dotnet-gcdump and the .NET runtime inside the target process must agree on the port-address, with one listening and the other connecting. dotnet-gcdump automatically determines the correct port when attaching using the `--process-id` or `--name` options. It's usually only necessary to specify the port explicitly when communicating to a process that's running inside a container that isn't part of the current process namespace.
+
+  The `port-address` differs by OS:
+
+  - Linux and macOS - a path to a Unix domain socket such as `/foo/tool1.socket`.
+  - Windows - a path to a named pipe such as `\\.\pipe\my_diag_port1`.
+  - Android, iOS, and tvOS - an IP:port such as `127.0.0.1:9000`.
+  
+  By default, dotnet-gcdump listens at the specified address. You can request dotnet-gcdump to connect instead by appending `,connect` after the address. For example, `--diagnostic-port /foo/tool1.socket,connect` will connect to a .NET runtime process that's listening to the `/foo/tool1.socket` Unix domain socket.
 
 > [!NOTE]
 > To collect a GC dump using `dotnet-gcdump`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md
@@ -161,9 +161,22 @@ dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--
 
   The name of the process to collect the trace from.
 
-- **`--diagnostic-port <path-to-port>`**
+  > [!NOTE]
+  > On Linux and macOS, using this option requires the target application and `dotnet-trace` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
+
+- **`--diagnostic-port <port-address[,(listen|connect)]>`**
+
+  Sets the [diagnostic port](diagnostic-port.md) used to communicate with the process to be traced. dotnet-trace and the .NET runtime inside the target process must agree on the port-address, with one listening and the other connecting. dotnet-trace automatically determines the correct port when attaching using the `--process-id` or `--name` options, or when launching a process using the `-- <command>` option. It's usually only necessary to specify the port explicitly when waiting for a process that will start in the future or communicating to a process that is running inside a container that isn't part of the current process namespace.
 
-  The name of the diagnostic port to create. See [Use diagnostic port to collect a trace from app startup](#use-diagnostic-port-to-collect-a-trace-from-app-startup) to learn how to use this option to collect a trace from app startup.
+  The `port-address` differs by OS:
+
+  - Linux and macOS - a path to a Unix domain socket such as `/foo/tool1.socket`.
+  - Windows - a path to a named pipe such as `\\.\pipe\my_diag_port1`.
+  - Android, iOS, and tvOS - an IP:port such as `127.0.0.1:9000`.
+  
+  By default, `dotnet-trace` listens at the specified address. You can request `dotnet-trace` to connect instead by appending `,connect` after the address. For example, `--diagnostic-port /foo/tool1.socket,connect` will connect to a .NET runtime process that is listening to the `/foo/tool1.socket` Unix domain socket.
+  
+  To learn how to use this option to collect a trace from app startup, see [Use diagnostic port to collect a trace from app startup](#use-diagnostic-port-to-collect-a-trace-from-app-startup).
   
 - **`--duration <time-to-run>`**
 
@@ -177,6 +190,9 @@ dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--
 
   The process ID to collect the trace from.
 
+  > [!NOTE]
+  > On Linux and macOS, using this option requires the target application and `dotnet-trace` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
+
 - **`--profile <profile-name>`**
 
   A named pre-defined set of provider configurations that allows common tracing scenarios to be specified succinctly. The following profiles are available:
@@ -230,8 +246,6 @@ dotnet-trace collect [--buffersize <size>] [--clreventlevel <clreventlevel>] [--
 
 > - 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.
 
-> - On Linux and macOS, this command expects the target application and `dotnet-trace` to share the same `TMPDIR` environment variable. Otherwise, the command will time out.
-
 > - To collect a trace using `dotnet-trace`, it needs to be run as the same user as the user running the target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
 
 > - 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.
