[Metrics] List of metrics built into .NET

[JamesNK]

https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics should have a list of metrics built into .NET. This would be like the well-known counters page - https://learn.microsoft.com/en-us/dotnet/core/diagnostics/available-counters.

For each meter name, there should be a table with the counter names, descriptions, .NET added versions. The counter name could link to OTel semantic conventions site. That allows people to see more information about the counter and its attributes.

Open question: Should the list here be just the dotnet/runtime metrics, or should it include ASP.NET Core metrics?

---

Proposal:

• There are separate built-in metrics docs pages for runtime and aspnetcore. There are too many instruments and attributes for one page, and we'll only add more in the future.
  • Runtime (containing DNS and HttpClient instruments)
  • ASP.NET Core (HTTP, Kestrel, middleware, signalr, etc).
• Each page starts with a summary that has a bullet point list of meter names and a description of what kind of counters a meter has. The name links to meter group on the page.
• Instruments are grouped on the page by meter name. Linked to by the page summary.
• Instrument name, type, unit, and description are displayed along with attribute name, type, description, example (maybe), and presence. There is a PR in ASP.NET Core that shows this layout - Built in metrics /2 RC 2 hold AspNetCore.Docs#29760 (this proposal eventually replaces the PR)
• Under each instrument, there is a link to its definition on OTel Semantic Conventions. Our docs will never go into the level of detail of OTel docs, so the goal is to provide enough information on learn.microsoft.com for someone to use a counter successfully and then a link to view the full definition if required.

Items:

• Add built-in metrics docs pages.
• Update ASP.NET Core metrics docs to link to ASP.NET Core built-in metrics page.
• Add .NET metrics to OTel Semantic Conventions. Done when Add .NET metrics open-telemetry/semantic-conventions#283 is merged.
• After merge, update ASP.NET Core RC1 blog post to point at merged .NET metrics at Semantic Conventions. Currently pointing at the PR.
• After merge, update the built-in metrics docs pages to have links to definitions at Semantic Conventions.

[noahfalk]

Should the list here be just the dotnet/runtime metrics, or should it include ASP.NET Core metrics?

I'd propose to have the list include ASP.NET Core metrics because I imagine that is simpler for users and follows precedent we already set with EventCounters. Does that sound good or do you see a particular benefit in separating them?

[JamesNK]

I think having them in the same document (or child doc if all counters are too much for one doc) is fine.

They just need to be grouped under an ASP.NET Core section that we can link to from ASP.NET Core docs.

If it turns out to be a problem in the future then it's simple to change.

[JamesNK]

@noahfalk @antonfirsov @joperezr @Rick-Anderson @lmolkova I updated the issue with a proposal for displaying built-in metrics in our docs. Feedback welcome.

I also added a list of tasks to complete.

[noahfalk]

What you suggested seems fine. I'll probably have a better sense for it once I've got an initial draft after which feedback is welcome. Its still in my todo list, just not at the top quite yet, almost there.

[noahfalk]

@Rick-Anderson - now that #37213 is merged and you are taking over on editing, mind if I assign this issue to you? I think the remaining work is mostly editing and cross-referencing once all the content is live.