dotnet-dsrouter and dotnet-gcdump doc needed when default port is occupied

[AlexeiNaabal]

*Edit: This doc request is for .net 8+, where the runtime and diagnostics added dotnet-gcdump support for mobile devices.

dotnet-dsrouter add some useful command to make mobile device interaction more conveniently, such as the dotnet-dsrouter android command.

The instructions provided by current document works fine when the default ip address is free, (checking the source code, it is 127.0.0.1:9000 by default), but there will be cases that port 9000 is occupied by other process, such as firm-wise internal security application, which one is not able or hard to alter.

Under such scenario, when working with dotnet-gcdump, the dotnet-dsrouter setup instructions provided with dotnet-dsrouter, dotnet-gcdump are not working.

By browsing the source code of dotnet-dsrouter and manual testing, the actually working dotnet-dsrouter config (manually checked with android device) is dotnet-dsrouter server-server -tcps 127.0.0.1:{port} -fp Android, with no ipcs option. If ipcs option added, dotnet-gcdump will not be able to collect the gcdump from mobile device, but only the dotnet-dsrouter's.

I only checked the work-around with android device though.

Please verify the work-around and consider add documentation for such scenario.

[hoyosjs]

cc @mdh1418

[tommcdon]

@lateralusX would you be interested in taking a look?

[lateralusX]

The default dsrouter modes -android, -android-emu are just simplified defaults, the full configuration of dsrouter can be found here https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-dsrouter, you can also find the underlying documentation here, https://github.com/dotnet/runtime/blob/main/docs/design/mono/diagnostics-tracing.md#custom-configuration-4. dotnet Android SDK also have some docs, https://github.com/dotnet/android/blob/main/Documentation/guides/tracing.md. If you decide to setup a custom named IPC server for dotnet-dsrouter, then you use the --diagnostic-port argument for dotnet-gcdump to connect to the specific IPC endpoint, if you don't use a custom named IPC server (like you have in your case), then you connect using the pid to dsrouter for the tooling as you normally do.

Your dsrouter configuration looks OK, it will setup an IPC server that can be connected to using dsrouter pid from diagnostic tooling, its setup a local TCP server binding to loopback interface (127.0.0.1) on selected port and -fp will start Android port forward/reverse automatically behind the scenes. Since you use the port forwarding/reverse this configuration will work both for devices and emulator. You will get information from dotnet-dsrouter on how to configure the DOTNET_DiagnosticPorts env variable for the app to connect back to the tooling.

So far none of the diagnostic tools have any specific documentation related to dotnet-dsrouter, not sure if we should add specific documentation into respective tools or add scenarios to dotnet-dsrouter documentation page. We currently have examples how to collect traces in dotnet-dsrouter, https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-dsrouter#collect-a-startup-trace-using-dotnet-trace-from-a-net-application-running-on-android, and the steps there are universal for other tools as well, so we could add more scenarios to that documentation and add some section what to do when defaults won't work. We could then update the existing docs on each tool with reference to dotnet-dsrouter documentation when targeting mobile or WASM. Thougths?

Looks like dotnet-gcdump lacks "new" --diagnostic-port argument in its documentation, that should be updated on dotnet-gcdump documentation page, maybe other tools lack documentation for this argument as well. I know all tools connecting against an IPC channel except dotnet-stack currently supports --diagnostic-port argument.

[noahfalk]

We could then update the existing docs on each tool with reference to dotnet-dsrouter documentation when targeting mobile or WASM. Thougths?

I think it would be fine to include a link and/or a small amount of explanatory text that assists with dsrouter usage on the various tool pages. It could go after the command reference and the local scenario examples.

For tools that support the --dsrouter option it would also be useful to have explicit documentation in the command reference section of the tools.

Looks like dotnet-gcdump lacks "new" --diagnostic-port argument in its documentation, that should be updated on dotnet-gcdump documentation page, maybe other tools lack documentation for this argument as well.

I created dotnet/docs#45669 to fix that part.

I know all tools connecting against an IPC channel except dotnet-stack currently supports --diagnostic-port argument.

dotnet-dump had the support added very recently and it hasn't shipped yet. I expect we'll have it out pretty soon but I didn't want to document it before it was accessible.

[noahfalk]

@lateralusX heads up I went ahead and assigned this issue to you. Happy to leave it to your discretion what (if any) dotnet-dsrouter related additional documentation you want to create.

[lateralusX]

@noahfalk, should we add --diagnostic-port argument to dotnet-stack as well, I believe its not been added to that tool, so its not just a documentation issue, but also something that needs to be implemented.

[noahfalk]

Sorry, I missed the GH notification. Yes I think adding --diagnostic-port to dotnet-stack would be good but I don't think we need to block this issue on it.
#5444

[noahfalk]

Also just fyi, a little more doc coverage of the --diagnostic-port option here: dotnet/docs#45821