micrometer-metrics / docs-pages

0 stars 0 forks source link

MeterTag docs suggest availability of a `SpelValueExpressionResolver` which is not (yet) a real API #1

Open cmacq2 opened 1 month ago

cmacq2 commented 1 month ago

The reference documentation for @MeterTag at https://docs.micrometer.io/micrometer/reference/concepts/timers.html#_metertag_on_method_parameters suggests that there could be a SpelValueExpressionResolver available to users of Micrometer. However, it looks like this is currently not the case because, while this class does indeed exist, it resides in a test package for Micrometer itself: https://github.com/micrometer-metrics/micrometer/blob/main/micrometer-core/src/test/java/io/micrometer/core/aop/SpelValueExpressionResolver.java

As a result. it is not possible to simply copy the example code and fix up imports, because the class is not available.

Depending on your perspective either the documentation could use some clarification that this is merely a "hypothetical" example, in which case embedding the actual SpelValueExpressionResolver implementation somewhere might make sense as an additional convenience for users, or the SpelValueExpressionResolver class should be published somewhere as part of the suite of Micrometer libraries/APIs.

Either way, right now the documentation is a little confusing (suggestive) on this point and might get the hopes up of users that were looking for a convenient feature like a SpelValueExpressionResolver to use with their own @MeterTag annotations.

jonatan-ivanov commented 1 month ago

ValueExpressionResolver is something that the framework should implement (i.e.: SpelValueExpressionResolver for Spring) or you if your framework does not so ideally you don't need to do anything. The docs of Micrometer Tracing has an example, I think we should do the same in the Micrometer docs too.

The Micrometer docs even have that class but it is not inlined in the asciidoc files, see: SpelValueExpressionResolver.

Would you be interested filing a PR and inlining the SpelValueExpressionResolver example in the Micrometer docs the same way the Micrometer Tracing docs does (I can help)?