Add POH events

[davmason]

Summary

dotnet/runtime#34549 added new GC events to the runtime and this PR updates the docs to include them. I did not include private events that the prior versions are not inlcuded in the docs (BGCOverflow and GCGenerationRange)

Fixes #17995

[noahfalk]

👍

Woot! Love to see docs : )

[hoyosjs]

It's great to see events getting updated. Just a couple of comments:

• The current path will make it look like this is applicable to .NET Framework, which is a bit confusing/unfortunate. Can't think of a better path under core. Maybe add a remark on the events only existing in .NET 5+?
• The date and description on the metadata header for the doc should be updated.

[noahfalk]

The current path will make it look like this is applicable to .NET Framework

Excellent catch : ) @sywhang did you ever chat with the doc team about the idea of splitting up these events .Net Core vs. desktop or somehow adding versioning information similar to what we have for APIs? No worries if not but didn't want us to duplicate work if there was already a plan.

[sywhang]

@noahfalk Yes I did. I believe the suggestion I received from the docs team was to add the documentation on new runtime events to https://docs.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing.

[gewarren]

@noahfalk Yes I did. I believe the suggestion I received from the docs team was to add the documentation on new runtime events to https://docs.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing.

Another thing we could consider is added a tracing section under /dotnet/standard that could apply to both Framework and Core, and we could annotate each event with the version it applies to. Thoughts @BillWagner? I think we have a new Performance section planned for the .NET 5 revamp too, correct?

[noahfalk]

Thanks!

Having a location that is applicable across multiple runtime implementations (Framework, Core, Mono) would be ideal as many of the events will be relevant for more than one runtime. We could then document which events are supported where similar to what we do for APIs. /dotnet/standard/... seems like it could fit that bill.

For all the content currently under dotnet/core, is there any plan to move or forward it after .NET 5 removes the term "core" from the branding? I'm trying to figure out if it would be odd to put content referencing .Net Framework support for many events under what is currently the https://docs.microsoft.com/en-us/dotnet/core/diagnostics/... area?

I think we have a new Performance section planned for the .NET 5 revamp too, correct?

FWIW instrumentation events often get associated with performance investigations, but they also can have a lot of utility for non-performance related diagnostic purposes.

[gewarren]

For all the content currently under dotnet/core, is there any plan to move or forward it after .NET 5 removes the term "core" from the branding? I'm trying to figure out if it would be odd to put content referencing .Net Framework support for many events under what is currently the https://docs.microsoft.com/en-us/dotnet/core/diagnostics/... area?

Yes, we do plan to change the folder structure.

[noahfalk]

Thanks @gewarren!

Yes, we do plan to change the folder structure.

Is it written down somewhere or could you describe what changes are coming? Other than it being different I don't know what to expect yet : )

[gewarren]

@noahfalk Bill Wagner wrote up a detailed plan here. If you have any feedback, we'd love to hear it.

[noahfalk]

Thanks, if I understand the plan correctly our current https://docs.microsoft.com/en-us/dotnet/core/diagnostics/... area would move under Fundamentals/Environment and Runtime/Tools and productivity/Diagnostics and Instrumentation/. That seems like a very reasonable place for the event definitions to end up.

In terms of lining that up, is our best bet to copy the docs rooted under https://github.com/dotnet/docs/blob/9c9f8b35f08fc56cfebd37cdeb02ccbabc9f1bd1/docs/framework/performance/etw-events.md over to https://docs.microsoft.com/en-us/dotnet/core/diagnostics/ and then start making modifications to indicate which events are supported on which runtime SKU/versions?

[gewarren]

In terms of lining that up, is our best bet to copy the docs rooted under https://github.com/dotnet/docs/blob/9c9f8b35f08fc56cfebd37cdeb02ccbabc9f1bd1/docs/framework/performance/etw-events.md over to https://docs.microsoft.com/en-us/dotnet/core/diagnostics/ and then start making modifications to indicate which events are supported on which runtime SKU/versions?

I don't think it's necessary to copy those .NET Framework files over to /core/diagnostics, since they will end up being moved/renamed again soon, and then we'd need to add redirects. If it works for you, I'd just add the .NET Core events in the existing docs (like you've done in this PR), and we'll make sure to incorporate these in the new Fundamentals/Environment and Runtime/Tools and productivity/Diagnostics and Instrumentation/ section.

[noahfalk]

If it works for you...

That sounds even easier, thanks! : )

[davmason]

Sorry, got distracted on other things. It sounds like the end result of the conversation above is that we're going to check this in as is and then deal with core versus desktop later?

I addressed the one issue @gewarren identified, are there any other requests outstanding?

[noahfalk]

It sounds like the end result of the conversation above is that we're going to check this in as is and then deal with core versus desktop later?

Yep, that was my understanding : )

[baal2000]

@davmason
Should rather be SyncBlockCount, but from looking at the code looks like it the name is cut in stone
https://github.com/dotnet/runtime/blob/921bca0ae0d07a7dfd83d5d70eaf49759ab8463b/src/coreclr/vm/gctoclreventsink.h#L29