Add docs for EF Core metrics

[cincuranet]

---

Internal previews

📄 File	🔗 Preview link
docs/core/diagnostics/built-in-metrics-efcore.md	Entity Framework Core metrics
docs/core/diagnostics/built-in-metrics.md	Built-in metrics in .NET

[noahfalk]

Looks good to me, one question inline.

[roji]

@cincuranet shouldn't we document these inside the EF docs, and point to that page from the .NET docs (i.e. from docs/core/diagnostics/built-in-metrics.md)?

Note that we already have an EF docs page on event counters; I'd merge this information into there, renaming it to "metrics" and keeping the current event counter information as a legacy thing at the bottom. Otherwise, as things are, people looking at the EF docs have no idea about the new metrics, and only see the event counter stuff, with no mention of it being legacy.

If we go down this path of an EF metrics page, I'd probably start with a quick intro mentioning the new support from EF 9.0, and the legacy event counters being available in the older versions (we can also point to this page for a comparison of the two APIs).

[cincuranet]

shouldn't we document these inside the EF docs, and point to that page from the .NET docs (i.e. from docs/core/diagnostics/built-in-metrics.md)?

@noahfalk requested it here and ASP.NET Core has it here as well. 🤷‍♂️

Note that we already have an EF docs page on event counters; I'd merge this information into there, renaming it to "metrics" and keeping the current event counter information as a legacy thing at the bottom. Otherwise, as things are, people looking at the EF docs have no idea about the new metrics, and only see the event counter stuff, with no mention of it being legacy.

We can as well link to here from EF Core docs.

[roji]

@noahfalk requested it here and ASP.NET Core has it here as well. 🤷‍♂️
[...]
We can as well link to here from EF Core docs.

So far we've generally been keeping EF docs, well, in the EF docs - after all this stuff is part of EF.. I don't think I'd want an EF user to need to go out of the EF docs sites just because they want to see the metrics we support...

@noahfalk would you be against the docs for the EF metrics living inside a page in the EF docs, and being linked to from this page?

[noahfalk]

@noahfalk would you be against the docs for the EF metrics living inside a page in the EF docs, and being linked to from this page?

Thats just fine by me. I don't think readers will care what the path to the content is as long as the link is there.

[cincuranet]

OK. Will redo it.

[roji]

Thanks @cincuranet

[noahfalk]

I'm guessing "since last observation" means since the last time the ObservableGauge callback function was called? Not a doc issue, but that may be a functional/design issue for this metric. There is no guarantee that only one observer exists or what the relative timings are between observations. For example imagine the app developer sets up OpenTelemetry polling at 1 minute intervals, but then sometimes they also run dotnet-counters reporting at 1 second intervals. Your callback might get invoked:

t=0:01 (dotnet-counters)
t=0:02 (dotnet-counters)
...
t=0:59 (dotnet-counters)
t=1:00 (dotnet-counters)
t=1:00 (OpenTelemetry)
t=1:01 (dotnet-counters)

Those two calls at the 1 minute mark probably aren't going to be exactly the same time, maybe 10 microseconds happens to pass between them. OpenTelemetry is now reporting the cache hit rate for a period of time 10 microseconds long which might well be 0 hits of 0 attempts.

You generally want to pick metrics that do not vary based on when the metric was last queried because that is an unpredictable time interval. You could report total hits and total attempts since the cache initialized and let users do a query to compute (hits_now-hits_last)/(total_now-total_last). Alternatively you could do the % hit rate over a time window that is not based on past observations. Hit rate since process start, hit rate in the last minute.

[cincuranet]

Noted. I guess we have the same problem with "old" event counters as well. I added dotnet/efcore#33959 to keep track of it.

[roji]

Yeah, I wouldn't worry about fixing the old event counters at this point, better just leave them as they are - but we should fix the new metric before releasing.