Metrics lacks clear documentation

[nerdni]

For example metrics related RabbitMq:

spring_rabbitmq_listener_seconds_count 
spring_rabbitmq_listener_seconds_sum
spring_rabbitmq_listener_seconds_max
rabbitmq_not_acknowledged_published_total
rabbitmq_rejected_total
rabbitmq_acknowledged_published_total  
rabbitmq_consumed_total  

In my application I have both subscribers and publishers to RabbitMQ and it confuses me which metric is for my published messages and which is for consumed.

[MrR0807]

Agree. I found myself scratching my head numerous time of what they actually mean. For example in documentation:

• https://micrometer.io/docs/registry/prometheus
• https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#production-ready-metrics-export-prometheus

There is no information about exposed metric names or what they mean. Then I'm left to wonder in google and rely on something like this:

• https://tomgregory.com/monitoring-a-spring-boot-application-part-2-prometheus/

If somebody would at least point towards the direction where to look up in code, I could offer to contribute to documentation.

[shakuzen]

I think there are perhaps two separate issues here: documentation of metrics instrumentation maintained by the Micrometer team, and discovery of metrics instrumentation maintained by the third-party library/tool being instrumented. Generally the latter is in that library/tool's documentation.

RabbitMQ metrics are not part of Micrometer core. It looks like the metrics mentioned are provided by the RabbitMQ Java client metrics and the Spring AMQP project. Any library can support metrics via Micrometer; trying to document something not maintained by the Micrometer team here would quickly be out-of-date and inaccurate. We could have a section in our documentation linking to popular libraries' documentation of Micrometer support, though.

Is that something that would be useful to users? If you think so, we could focus this issue on that and open a separate issue for improving the documentation of metrics maintained in Micrometer core.

[nerdni]

Agree, micrometer core metrics documentation could be improved to know which metrics belongs to micrometer core, so it would be clear that others are third party metrics.

[MrR0807]

If you could point where to look for metrics supported by Micrometer core, I could look into during the weekend.

Any library can support metrics via Micrometer; trying to document something not maintained by the Micrometer team here would quickly be out-of-date and inaccurate. We could have a section in our documentation linking to popular libraries' documentation of Micrometer support, though.

Agree. Maybe both of these sections: Micrometer core metrics and 3rd party support library list could next to each other?

[shakuzen]

I was discussing options with @jonatan-ivanov for this, and I was wondering if we can't use the JavaDocs site for this somehow, as long as we make sure the JavaDoc comments used to generate it are up-to-date and informative enough. I was hoping we could essentially point to the io.micrometer.core.instrument.binder package and say all the instrumentation is in classes in sub-packages from there. Of course, sub-packages aren't really a thing and it's just a convention of hierarchical naming, so this isn't as usable as I had hoped, but it's still not terrible to find each package from the index due to alphabetical ordering.
https://www.javadoc.io/doc/io.micrometer/micrometer-core/latest/index.html

We could, of course, manually make documentation of all the provided metrics, but this would require a lot of work to keep up-to-date, and a significant amount of the information is version-dependent. The reference documentation currently is not versioned. Since the JavaDocs sites are versioned, that's another reason I would like to leverage that. Note: we currently have a limited selection of documentation of metrics we provide: JVM, Cache, OkHttpClient. We have a lot more undocumented. Some reorganization would probably be in order.

Perhaps if we update the package descriptions (JavaDocs) to point readers at which classes to look for which metrics, it would be more usable. I noticed while looking into this that currently we have the license header as a JavaDoc, which was probably a mistake.

As for the third-party libraries with Micrometer metrics, we would have to collect these and link to them.

[shakuzen]

Looking back at the open issues here, it looks like this is a duplicate of micrometer-metrics/micrometer#4626 and #57. Let's continue the conversation in those respective issues.