Link observability section to Micrometer Observation Handler docs

[david0]

To me http_server_requests_active_seconds seems to be completly undocumented, so it would be nice to document that metric somewhere.

I also think that all of these metrics should have a help text on prometheus. At least that is where I rely on usually and I do not see a reason why not to have it.

[bclozel]

I'm not sure we should document that at the Spring Framework level, because I think it ultimately depends on the Micrometer configuration directly. I believe this is a long task timer automatically configured with micrometer observations, but this can be disabled. Maybe we should point to some Micrometer Observation reference documentation for that, but I couldn't find a particular section.

As for the "prometheus help text", are you referring to the description field for metrics? If so, this is not supported directly at the moment by Micrometer.

Pinging @shakuzen @jonatan-ivanov to get their opinion.

[david0]

As for the "prometheus help text", are you referring to the description field for metrics?

Yes, in micrometer terminology its description.
I see its not easy and also micrometer needs to be changed, still I think it should be done somehow.

Besides that, I think it really should be in the Spring Reference documentation. Even if its just implicitly brought in with micrometer, I assume its what most people have and also what a lot of people are interested in to understand.

[jonatan-ivanov]

I also think that all of these metrics should have a help text on prometheus. At least that is where I rely on usually and I do not see a reason why not to have it.

Please see this comment on the issue that Brian linked: micrometer-metrics/micrometer#5478 (comment).
TL;DR: it is only used for metrics, there are not a lot of backends that support it, and other than this issue we only saw one request for this functionality. The disadvantage is adding an extra reference to the Observation.Context (performance).

I think it would be nice to have it, although I don't know any use-case for this other than Prometheus on top of my hear right now. Maybe we could use this in docs-gen when we generate documentation for Observations?

To me http_server_requests_active_seconds seems to be completly undocumented, so it would be nice to document that metric somewhere.

In order to document this, there are a few things we need to consider:

1. This metric name only exists as-is if you use Prometheus. We support 20+ protocols/formats. Maybe we could document the names of the meters: http.server.requests and http.server.requests.active. Would that help?
2. Metrics are optional and when Spring Framework instruments itself it does not know what meters will be created. But it knows what observations are created which is available in the docs.
3. Maybe in the Micrometer docs, we could create a section for DefaultMeterObservationHandler and describe what metrics it will create and reference that from the framework docs?

[shakuzen]

Maybe we should point to some Micrometer Observation reference documentation for that, but I couldn't find a particular section.

Maybe in the Micrometer docs, we could create a section for DefaultMeterObservationHandler and describe what metrics it will create and reference that from the framework docs?

I've opened micrometer-metrics/micrometer#6361 for that.