Docs: document the replacement of the PerformanceCounter and how to use it.

[John0King]

The PerformanceCounter doesn't cross platform, and the EventCounter is the future. There already some document on github , but not exits on http://docs.microsft.com .
The original issue is here https://github.com/dotnet/runtime/issues/31921

[Thraka]

@sdmaclea Checking https://docs.microsoft.com/en-us/dotnet/core/diagnostics/logging-tracing I don't see really a mention of EventCounter although you do reference tools that can read that data, there is nothing that describes using it to capture counters.

[sdmaclea]

/cc @dotnet/dotnet-diag

[sdmaclea]

https://docs.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters is the document. We have scenario we have to revise to conform to docs.microsoft.com standards. https://github.com/dotnet/diagnostics/blob/master/documentation/tutorial/app_running_slow_highcpu.md. I have a draft, but it still needs a few days work.

[sdmaclea]

We are also probably missing documentation on how to use the API from C# code. i.e. the API.

[Thraka]

Yes that was what I was talking about, using the API from C#. The github tutorial linked at the end of dotnet-counters has that information.

[cshung]

Probably should move this one to an appropriate home too.
https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md

[Rick-Anderson]

@sdmaclea writes:

https://docs.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters is the document.

That's the doc on the performance monitoring tool, not EventCounter. The following GitHub Readme.MD files need to be migrated to docs on this repo:

• EventCounters in .NET Core 3.0
• Introduction Tutorial: How to measure performance for very frequent events using EventCounters as suggested by @cshung

The following links provide additional info:

• Introducing diagnostics improvements in .NET Core 3.0
• Diagnostics in .Net Core 3: Event Counters
• .NET Core Counters internals: how to integrate counters in your monitoring pipeline

@Thraka can we get this work scheduled? I need to document the EventCounters emitted by ASP.NET Core

[shirhatti]

I have a draft, but it still needs a few days work.

@sdmaclea I'd be happy to jump in and help if you can point me to your draft

[sywhang]

@sdmaclea @shirhatti I can also help out with any documentation work regarding this space. Please let me know if any extra hands are needed

[sdmaclea]

I found the old branch and resurrected it here.

https://github.com/sdmaclea/docs/tree/scenarios_rebase

• I was trying to add the three tutorials in one PR and the review was taking too long.
• I dropped the two tutorials so we could focus on a single tutorial.
• The memory leak tutorial which is on tip was cleaned up and now we have a sample of what these need to become.

I spent a few minutes doing the simple & obvious things I remember from the memory leak review.

I think there are likely a few things left to do with these.

• Replace screen shot images with sample text from recent actual tool usage.
• Split code from text which should be translated. Do not put instructional text in code blocks...
• Fix broken links (stuff moved around as part of the review)
• Conform to the tone and style of docs/core. Use the memory-leak tutorial as an example. And docs cited by @mairaw in https://github.com/dotnet/docs/pull/14110#discussion_r336278247.

We are also missing docs and or tutorials for

• dotnet sos - should be fairly simple /cc @mikem8361
• dotnet-gcdump - I haven't looked /cc @josalem
• perfview - /cc @brianrob
• Linux perf w/ and w/o jitdump /cc @sdmaclea
• There are probably others....

[John0King]

When will the document available on docs.microsoft.com ?
by the way , I suggest to add a new section of "ObsolateApi and replacement" Section on .net core docs

[noahfalk]

I don't think #19534 has resolved the need for this documentation. #19534 has some nice scenario walkthroughs, including one which looks at the CPU perf counter, but I don't expect one example of usage to adequately describe the overall feature for most of our customers. Customers are also unlikely to think to read a scenario about CPU usage if their goal is to learn about EventCounter. These are some questions I anticipate customers would ask us and hope to find in our documentation:

1. If want to collect metrics what tools does .Net Core provide? (the walkthrough touches on this one)
2. If I want to create my own custom metrics, how can I do that?
3. If I want to integrate these metrics into existing metric collection pipelines and dashboards, how can I do that? (it wouldn't be straightforward today)
4. What happened to performance counters? Can I still use them? Why use EventCounter instead?
5. What metrics does .Net Core provide out-of-the-box?

The comment above had links to a bunch of relevant info in this area.

[IEvangelist]

I don't think #19534 has resolved the need for this documentation. #19534 has some nice scenario walkthroughs, including one which looks at the CPU perf counter, but I don't expect one example of usage to adequately describe the overall feature for most of our customers. Customers are also unlikely to think to read a scenario about CPU usage if their goal is to learn about EventCounter. These are some questions I anticipate customers would ask us and hope to find in our documentation:

1. If want to collect metrics what tools does .Net Core provide? (the walkthrough touches on this one)
2. If I want to create my own custom metrics, how can I do that?
3. If I want to integrate these metrics into existing metric collection pipelines and dashboards, how can I do that? (it wouldn't be straightforward today)
4. What happened to performance counters? Can I still use them? Why use EventCounter instead?
5. What metrics does .Net Core provide out-of-the-box?

The comment above had links to a bunch of relevant info in this area.

Hi @noahfalk - thanks for keeping me honest, good catch! I'll add these articles too. 👍