[docs] update notes about dotnet-trace and dotnet-gcdump

[jonathanpeppers]

• Mention dotnet-dsrouter android

dotnet/diagnostics#4337

Was fixed by .NET 8 GA, so we can remove the section mentioning it.

• Mention the relationship between the debug.mono.profile Android system property and $DOTNET_DiagnosticPorts.

• Mention suspend vs nosuspend.

• Mention libmono-component-diagnostics_tracing.so and the Mono diagnostic component.

These all came up from conversations with customers, so I think it will be useful for anyone.

[jonpryor]

This doc needs to be usable/make sense to someone who doesn't know what they're doing.

Fortunately, I don't know what I'm doing either!

Missing context: the filename is tracing.md, but the title is "Using a device connected via USB". This feels like a mismatch and/or poor ordering.

For starters, "Set up reverse port forwarding" is the first section. Why is this first, especially when it isn't needed for emulator use? This section should be move into the "For profiling an Android application running on an Android device:" section.

Missing sections: it will be handy to be able to link to specific sub-sections. There aren't enough sections to make that useful, e.g. there's no way to link to the "on-device hardware" setup instructions vs. the "emulator" instructions, as they're both in the same "Start the tracing router/proxy on host" section.

I think we need a structure similar to:

• Tracing: what is it, why would you want to do it? (Surely there are dotnet docs for this. Link to them!)
• Dependencies: what do you need to trace? How do you get them?
  • dotnet-dsrouter
  • dotnet-trace
  • dotnet-gcdump
• Configuration/Setup: What do you need to before you begin tracing?
  • Emulator configuration
  • Hardware configuration: presumably here is where you'd mention adb reverse
  • Run dotnet-dsrouter (is here the right spot?)
• Execution: how do you begin tracing? Presumably "Compile and run the application" would go here. What output is produced? Where is it?
• Analysis: how do you read the output produced by Execution
  • GC Dumps
  • .nettrace and speedscope files
• Examples

[AlexeiNaabal]

• Mention dotnet-dsrouter android

dotnet/diagnostics#4337

Was fixed by .NET 8 GA, so we can remove the section mentioning it.

• Mention the relationship between the debug.mono.profile Android system property and $DOTNET_DiagnosticPorts.
• Mention suspend vs nosuspend.
• Mention libmono-component-diagnostics_tracing.so and the Mono diagnostic component.

These all came up from conversations with customers, so I think it will be useful for anyone.

@jonathanpeppers Thanks for mentioning these.
I would also like to point out that, if the 9000 port (by default) is occupied by other process, we have to use the server-server config instead, to manually set a different tcps address. In such scenario, one should NOT set the ipcs with option -ipcs, just leave it as the default "", when start the dotnet-dsrouter, otherwise the dotnet-gcdump will not be able to connect the mono application running on the device. I think the ipcs should be able to config in such scenario, making the dsrouter startup config consistent with other tool's (like dotnet-trace) workflow?

[jonathanpeppers]

@AlexeiNaabal if you think something is missing/incorrect can you file an issue here? (just be sure to mention Android)

https://github.com/dotnet/diagnostics/issues

[AlexeiNaabal]

@***@***.***… After some re-thinking I realize that since we do have work around, it is actually not necessary to add more options to the "dotnet-dsrouter android" command, since it will just basically be a wrapper of the "blabla -ipcs blabla -tcps blabla". The missing part is official documentation, telling people when the default 9000 is occupied, what to do next. I would like to raise a Documentation Request. Best regards, | | jamesramirez | | ***@***.*** | ---- Replied Message ---- | From | Jonathan ***@***.***> | | Date | 2/21/2024 06:22 | | To | ***@***.***> | | Cc | ***@***.***>, ***@***.***> | | Subject | Re: [xamarin/xamarin-android] [docs] update notes about `dotnet-trace` and `dotnet-gcdump` (PR #8713) | @AlexeiNaabal if you think something is missing/incorrect can you file an issue here? (just be sure to mention Android) https://github.com/dotnet/diagnostics/issues — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[roubachof]

I just followed this improved doc and easily created a speedscope file on a real device.

[AlexeiNaabal]

I just followed this improved doc and easily created a speedscope file on a real device.

would you like checkout port 9000 is free? If it is free, a simple way to occupy it will be like start the mono debugger connection with port 9000, let the debugger module will occupy the port 9000.