update Sling Commons Metrics with latest changes
diff --git a/src/main/jbake/content/documentation/bundles/metrics.md b/src/main/jbake/content/documentation/bundles/metrics.md
index 22c5a95..c6205c2 100644
--- a/src/main/jbake/content/documentation/bundles/metrics.md
+++ b/src/main/jbake/content/documentation/bundles/metrics.md
@@ -44,12 +44,12 @@
Refer to [Metric Getting Started][2] guide to see how various types
of Metric instances can be used. Note that when using Sling Commons Metrics
-bundle class names belong to `org.apache.sling.commons.metrics` package
+bundle class names belong to the `org.apache.sling.commons.metrics` package.
## Best Practices
1. Use descriptive names - Qualify the name with class/package name where the
- metric is being used
+ metric is being used.
2. Do not use the metrics for operation which take less than 1E-7s i.e. 1000 nano
seconds otherwise timer overhead (Metrics makes use of System.nanoTime)
would start affecting the performance.
@@ -64,9 +64,33 @@
* [org.apache.sling.commons.metrics.Timer][6] - Similar to [Dropwizard Timer][dw-timer]
* [org.apache.sling.commons.metrics.Counter][5] - Similar to [Dropwizard Counter][dw-counter]
* [org.apache.sling.commons.metrics.Histogram][7] - Similar to [Dropwizard Histogram][dw-histogram]
+* [org.apache.sling.commons.metrics.Gauge][8] - Similar to [Dropwizard Gauge][dw-gauge]
Further it provides a `MetricsService` which enables creation of different
-type of Metrics like Meter, Timer, Counter and Histogram.
+type of Metrics like Meter, Timer, Counter and Histogram, Gauge.
+
+### The special case of Gauge
+
+Unlike other metric types, the gauge metric is a generic class, through which it can support many different types of gauge values.
+It can be easiest used by providing a Supplier or Lambda to return the requested value. Here the example of a gauge which returns a constant value.
+
+ ::java
+ import org.apache.sling.metrics.Gauge;
+ import org.apache.sling.metrics.MetricsService;
+
+ @Reference
+ private MetricsService metricsService;
+
+ private Gauge<Integer> cacheHitRatio;
+
+ @Activate
+ private void activate(){
+ cacheHitRatio = metricsService.counter("org.myapp.metrics.constantValue", () -> {
+ return 42;
+ });
+ }
+
+
### Requirement of wrapper interfaces
@@ -79,7 +103,7 @@
overhead. Turning on and off can also be done on individual metric basis.
It also allows us to later extend the type of data collected. For e.g. we can also collect
-[TimerSeries][8] type of data for each metric without modifying the caller logic.
+[TimerSeries][9] type of data for each metric without modifying the caller logic.
### Access to Dropwizard Metrics API
@@ -113,29 +137,32 @@
then that would be prefixed to the Metric names from that registry. This allows
use of same name in different registry instances.
-## Installation
+## JMX support
+This library also registers all metrics as MBeans by default. That means that existing JMX-based monitoring can be used to access
+the metrics as well.
-Add following Maven dependency to your pom.xml:
+## JMX Exporter
+Starting with version 1.2.12 Sling Commons Metrics also supports the other way around. As some third-party libraries provide metrics data only via JMX, the JMX Exporter Factory can be used to export those values as metrics.
- ::xml
- <dependency>
- <groupId>org.apache.sling</groupId>
- <artifactId>org.apache.sling.commons.metrics</artifactId>
- <version>1.0.0</version>
- </dependency>
-
-Or download from [here][9]
+Create an instance of the "JMX to Metrics Exporter" (pid: `org.apache.sling.commons.metrics.internal.JmxExporterFactory`) and provide the name of the MBean you want to export in the `objectname` property (multi-value). All attributes of these MBeans matching the following types will be exported as metrics (others are silently ignored):
+
+* Long
+* String
+* Double
+* Boolean (with [SLING-11509](https://issues.apache.org/jira/browse/SLING-11509))
+
[1]: http://metrics.dropwizard.io/
-[dw-meter]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#meters
-[dw-counter]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#counters
-[dw-histogram]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#histograms
-[dw-timer]: https://dropwizard.github.io/metrics/3.1.0/manual/core/#timers
-[2]: https://dropwizard.github.io/metrics/3.1.0/getting-started/#counters
+[dw-meter]: https://metrics.dropwizard.io/3.2.3/manual/core.html#man-core-meters
+[dw-counter]: https://metrics.dropwizard.io/3.2.3/manual/core.html#man-core-counters
+[dw-histogram]: https://metrics.dropwizard.io/3.2.3/manual/core.html#man-core-histograms
+[dw-timer]: https://metrics.dropwizard.io/3.2.3/manual/core.html#man-core-timers
+[dw-gauge]: https://metrics.dropwizard.io/3.2.3/manual/core.html#man-core-gauges
+[2]: https://dropwizard.github.io/metrics/3.2.3/getting-started/#counters
[3]: https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/MetricsService.java
[4]: https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Meter.java
[5]: https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Counter.java
[6]: https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Timer.java
[7]: https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Histogram.java
-[8]: https://jackrabbit.apache.org/api/2.6/org/apache/jackrabbit/api/stats/TimeSeries.html
-[9]: http://sling.apache.org/downloads.cgi
+[8]: https://github.com/apache/sling/blob/trunk/bundles/commons/metrics/src/main/java/org/apache/sling/commons/metrics/Gauge.java
+[9]: https://jackrabbit.apache.org/api/2.6/org/apache/jackrabbit/api/stats/TimeSeries.html
