Issue ReactiveX#354: Add tag based micrometer metric binders

* Add micrometer circuit breaker metrics binder based on tags

* Add micrometer bulkhead metrics binder based on tags

* Add micrometer rate limiter metrics binder based on tags

* Add micrometer retry metrics binder based on tags

* Add micrometer async retry metrics binder based on tags

* Add documentation for tag based metrics

Author: voievodin

resilience4j-documentation/src/docs/asciidoc/addon_guides/micrometer.adoc

@@ -18,13 +18,21 @@ final Bulkhead boo = bulkheadRegistry.bulkhead("boo");
 // Register all bulkheads at once
 BulkheadMetrics bulkheadMetrics = BulkheadMetrics.ofBulkheadRegistry(bulkheadRegistry);
 bulkheadMetrics.bindTo(meterRegistry);
+
+// Or for tag based metrics
+TaggedBulkheadMetrics.ofBulkheadRegistry(bulkheadRegistry).bindTo(meterRegistry);
 --
 
 For each bulkhead this registry will export:
 
 * `available_concurrent_calls` - instantaneous read of the number of currently available concurrent calls `[int]`
 * `max_allowed_concurrent_calls` - maximum number of allowed concurrent calls `[int]`
 
+Tag based metrics:
+
+* `resilience4j_bulkhead_available_concurrent_calls{name="name of bulkhead"}` - number of available concurrent calls
+* `resilience4j_bulkhead_max_allowed_concurrent_calls{name="name of bulkhead"}` - maximum number of allowed concurrent calls
+
 ===== CircuitBreaker
 
 [source,java]
@@ -36,6 +44,9 @@ final CircuitBreaker boo = circuitBreakerRegistry.circuitBreaker("boo");
 // Register all circuit breakers at once
 CircuitBreakerMetrics circuitBreakerMetrics = CircuitBreakerMetrics.ofCircuitBreakerRegistry(circuitBreakerRegistry);
 circuitBreakerMetrics.bindTo(meterRegistry);
+
+// Or for tag based metrics
+TaggedCircuitBreakerMetrics.ofCircuitBreakerRegistry(circuitBreakerRegistry).bindTo(meterRegistry);
 --
 
 For each circuit breaker this registry will export:
@@ -47,6 +58,16 @@ For each circuit breaker this registry will export:
 * `buffered_max` - maximum number of buffered calls `[int]`
 * `not_permitted` - current number of not permitted calls `[int]`
 
+Tag based metrics:
+
+* `resilience4j_circuitbreaker_state{name="name of circuitbreaker"}` - the state of the circuit breaker where 0-CLOSED, 1-OPEN, 2-HALF-OPEN
+* `resilience4j_circuitbreaker_calls{name="name of circuitbreaker", kind="one of the values below"}` - the number of calls of a certain kind
+  - `successful` - indicates successful calls
+  - `failed` - indicates failed calls
+  - `not_permitted` - indicates not permitted calls
+* `resilience4j_circuitbreaker_buffered_calls{name="name of circuitbreaker"}` - the number of buffered calls
+* `resilience4j_circuitbreaker_max_buffered_calls{name="name of circuitbreaker"}` - the maximum number of buffered calls
+
 ===== RateLimiter
 
 [source,java]
@@ -57,13 +78,21 @@ final RateLimiter rateLimiter = rateLimiterRegistry.rateLimiter("testLimit");
 // Register rate limiters at once
 RateLimiterMetrics rateLimiterMetrics = RateLimiterMetrics.ofRateLimiterRegistry(rateLimiterRegistry);
 rateLimiterMetrics.bindTo(meterRegistry);
+
+// Or for tag based metrics
+TaggedRateLimiterMetrics.ofRateLimiterRegistry(rateLimiterRegistry).bindTo(meterRegistry);
 --
 
 For each rate limiter this registry will export:
 
 * `available_permissions` - current number of available permissions `[int]`
 * `number_of_waiting_threads` - current number of threads waiting for permission `[int]`
 
+Tag based metrics:
+
+* `resilience4j_ratelimiter_available_permissions{name="name of ratelimiter"}` - the number of available permissions
+* `resilience4j_ratelimiter_waiting_threads{name="name of ratelimiter"}` - the number of threads waiting for permission
+
 ===== Retry
 
 [source,java]
@@ -75,6 +104,9 @@ final Retry retry = retryRegistry.retry("testLimit");
 // Register all retries at once
 RetryMetrics retryMetrics = RetryMetrics.ofRetryRegistry(retryRegistry);
 retryMetrics.bindTo(meterRegistry);
+
+// Or for tag baed metrics
+TaggedRetryMetrics.ofRetryRegistry(retryRegistry).bindTo(meterRegistry);
 --
 
 For each retry this registry will export:
@@ -84,3 +116,12 @@ For each retry this registry will export:
 * `failed_calls_without_retry` - the number of failed calls without a retry attempt `[long]`
 * `failed_calls_with_retry` - the number of failed calls after all retry attempts `[long]`
 
+Tag based metrics:
+
+* `resilience4j_retry_calls{name="retry name", kind="one of the values below"}` - the number of calls of a certain kind
+  - `successful_without_retry` - indicates successful calls without retry
+  - `successful_with_retry` - indicates successful calls with retry
+  - `failed_without_retry` - indicates failed calls without retry
+  - `failed_with_retry` - indicates failed calls with retry
+
+Note the same set of metrics is exposed for async retry, metric name is `resilience4j_async_retry_calls`.

resilience4j-micrometer/src/main/java/io/github/resilience4j/micrometer/tagged/TagNames.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2019 Yevhenii Voievodin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.resilience4j.micrometer.tagged;
+
+/** Common constants for metric binder implementations based on tags. */
+public final class TagNames {
+    public static final String NAME = "name";
+    public static final String KIND = "kind";
+}

resilience4j-micrometer/src/main/java/io/github/resilience4j/micrometer/tagged/TaggedAsyncRetryMetrics.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2019 Yevhenii Voievodin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.resilience4j.micrometer.tagged;
+
+import io.github.resilience4j.micrometer.AsyncRetryMetrics;
+import io.github.resilience4j.retry.AsyncRetry;
+import io.github.resilience4j.retry.AsyncRetry.Metrics;
+import io.github.resilience4j.retry.AsyncRetryRegistry;
+import io.micrometer.core.instrument.Gauge;
+import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.binder.MeterBinder;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * A micrometer binder that is used to register retry exposed {@link Metrics metrics}.
+ * The main difference from {@link AsyncRetryMetrics} is that this binder uses tags
+ * to distinguish between metrics.
+ */
+public class TaggedAsyncRetryMetrics implements MeterBinder {
+
+    /**
+     * Creates a new binder that uses given {@code registry} as source of retries.
+     *
+     * @param registry the source of async retries
+     */
+    public static TaggedAsyncRetryMetrics ofAsyncRetryRegistry(AsyncRetryRegistry registry) {
+        return new TaggedAsyncRetryMetrics(MetricNames.ofDefaults(), registry.getAllRetries());
+    }
+
+    /**
+     * Creates a new binder that uses given {@code registry} as source of retries.
+     *
+     * @param names custom metric names
+     * @param registry the source of retries
+     */
+    public static TaggedAsyncRetryMetrics ofAsyncRetryRegistry(MetricNames names, AsyncRetryRegistry registry) {
+        return new TaggedAsyncRetryMetrics(names, registry.getAllRetries());
+    }
+
+    private final MetricNames names;
+    private final Iterable<? extends AsyncRetry> asyncRetries;
+
+    private TaggedAsyncRetryMetrics(MetricNames names, Iterable<? extends AsyncRetry> asyncRetries) {
+        this.names = requireNonNull(names);
+        this.asyncRetries = requireNonNull(asyncRetries);
+    }
+
+    @Override
+    public void bindTo(MeterRegistry registry) {
+        for (AsyncRetry asyncRetry : asyncRetries) {
+            Gauge.builder(names.getCallsMetricName(), asyncRetry, (art) -> art.getMetrics().getNumberOfSuccessfulCallsWithoutRetryAttempt())
+                    .tag(TagNames.NAME, asyncRetry.getName())
+                    .tag(TagNames.KIND, "successful_without_retry")
+                    .register(registry);
+            Gauge.builder(names.getCallsMetricName(), asyncRetry, (art) -> art.getMetrics().getNumberOfSuccessfulCallsWithRetryAttempt())
+                    .tag(TagNames.NAME, asyncRetry.getName())
+                    .tag(TagNames.KIND, "successful_with_retry")
+                    .register(registry);
+            Gauge.builder(names.getCallsMetricName(), asyncRetry, (art) -> art.getMetrics().getNumberOfFailedCallsWithoutRetryAttempt())
+                    .tag(TagNames.NAME, asyncRetry.getName())
+                    .tag(TagNames.KIND, "failed_without_retry")
+                    .register(registry);
+            Gauge.builder(names.getCallsMetricName(), asyncRetry, (art) -> art.getMetrics().getNumberOfFailedCallsWithRetryAttempt())
+                    .tag(TagNames.NAME, asyncRetry.getName())
+                    .tag(TagNames.KIND, "failed_with_retry")
+                    .register(registry);
+        }
+    }
+
+    /** Defines possible configuration for metric names. */
+    public static class MetricNames {
+
+        public static final String DEFAULT_ASYNC_RETRY_CALLS = "resilience4j_async_retry_calls";
+
+        /**
+         * Returns a builder for creating custom metric names.
+         * Note that names have default values, so only desired metrics can be renamed.
+         */
+        public static Builder custom() {
+            return new Builder();
+        }
+
+        /** Returns default metric names. */
+        public static MetricNames ofDefaults() {
+            return new MetricNames();
+        }
+
+        private String callsMetricName = DEFAULT_ASYNC_RETRY_CALLS;
+
+        private MetricNames() {}
+
+        /** Returns the metric name for async retry calls, defaults to {@value DEFAULT_ASYNC_RETRY_CALLS}. */
+        public String getCallsMetricName() {
+            return callsMetricName;
+        }
+
+        /** Helps building custom instance of {@link MetricNames}. */
+        public static class Builder {
+            private final MetricNames metricNames = new MetricNames();
+
+            /** Overrides the default metric name {@value MetricNames#DEFAULT_ASYNC_RETRY_CALLS} with a given one. */
+            public Builder callsMetricName(String callsMetricName) {
+                metricNames.callsMetricName = requireNonNull(callsMetricName);
+                return this;
+            }
+
+            /** Builds {@link MetricNames} instance. */
+            public MetricNames build() {
+                return metricNames;
+            }
+        }
+    }
+}

resilience4j-micrometer/src/main/java/io/github/resilience4j/micrometer/tagged/TaggedBulkheadMetrics.java

@@ -0,0 +1,138 @@
+/*
+ * Copyright 2019 Yevhenii Voievodin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.resilience4j.micrometer.tagged;
+
+import io.github.resilience4j.bulkhead.Bulkhead;
+import io.github.resilience4j.bulkhead.Bulkhead.Metrics;
+import io.github.resilience4j.bulkhead.BulkheadRegistry;
+import io.github.resilience4j.micrometer.BulkheadMetrics;
+import io.micrometer.core.instrument.Gauge;
+import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.binder.MeterBinder;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * A micrometer binder that is used to register bulkhead exposed {@link Metrics metrics}.
+ * The main difference from {@link BulkheadMetrics} is that this binder uses tags
+ * to distinguish between metrics.
+ */
+public class TaggedBulkheadMetrics implements MeterBinder {
+
+    /**
+     * Creates a new binder that uses given {@code registry} as source of bulkheads.
+     *
+     * @param registry the source of bulkheads
+     */
+    public static TaggedBulkheadMetrics ofBulkheadRegistry(BulkheadRegistry registry) {
+        return new TaggedBulkheadMetrics(MetricNames.ofDefaults(), registry.getAllBulkheads());
+    }
+
+    /**
+     * Creates a new binder defining custom metric names and
+     * using given {@code registry} as source of bulkheads.
+     *
+     * @param names custom names of the metrics
+     * @param registry the source of bulkheads
+     */
+    public static TaggedBulkheadMetrics ofBulkheadRegistry(MetricNames names, BulkheadRegistry registry) {
+        return new TaggedBulkheadMetrics(names, registry.getAllBulkheads());
+    }
+
+    private final MetricNames names;
+    private final Iterable<? extends Bulkhead> bulkheads;
+
+    private TaggedBulkheadMetrics(MetricNames names, Iterable<? extends Bulkhead> bulkheads) {
+        this.names = requireNonNull(names);
+        this.bulkheads = requireNonNull(bulkheads);
+    }
+
+    @Override
+    public void bindTo(MeterRegistry registry) {
+        for (Bulkhead bulkhead : bulkheads) {
+            Gauge.builder(names.getAvailableConcurrentCallsMetricName(), bulkhead, (bh) -> bh.getMetrics().getAvailableConcurrentCalls())
+                    .tag(TagNames.NAME, bulkhead.getName())
+                    .register(registry);
+            Gauge.builder(names.getMaxAllowedConcurrentCallsMetricName(), bulkhead, (bh) -> bh.getMetrics().getMaxAllowedConcurrentCalls())
+                    .tag(TagNames.NAME, bulkhead.getName())
+                    .register(registry);
+        }
+    }
+
+    /** Defines possible configuration for metric names. */
+    public static class MetricNames {
+
+        public static final String DEFAULT_BULKHEAD_AVAILABLE_CONCURRENT_CALLS_METRIC_NAME = "resilience4j_bulkhead_available_concurrent_calls";
+        public static final String DEFAULT_BULKHEAD_MAX_ALLOWED_CONCURRENT_CALLS_METRIC_NAME = "resilience4j_bulkhead_max_allowed_concurrent_calls";
+
+        /**
+         * Returns a builder for creating custom metric names.
+         * Note that names have default values, so only desired metrics can be renamed.
+         */
+        public static Builder custom() {
+            return new Builder();
+        }
+
+        /** Returns default metric names. */
+        public static MetricNames ofDefaults() {
+            return new MetricNames();
+        }
+
+        private String availableConcurrentCallsMetricName = DEFAULT_BULKHEAD_AVAILABLE_CONCURRENT_CALLS_METRIC_NAME;
+        private String maxAllowedConcurrentCallsMetricName = DEFAULT_BULKHEAD_MAX_ALLOWED_CONCURRENT_CALLS_METRIC_NAME;
+
+        private MetricNames() {}
+
+        /**
+         * Returns the metric name for bulkhead concurrent calls,
+         * defaults to {@value DEFAULT_BULKHEAD_AVAILABLE_CONCURRENT_CALLS_METRIC_NAME}.
+         */
+        public String getAvailableConcurrentCallsMetricName() {
+            return availableConcurrentCallsMetricName;
+        }
+
+        /**
+         * Returns the metric name for bulkhead max available concurrent calls,
+         * defaults to {@value DEFAULT_BULKHEAD_MAX_ALLOWED_CONCURRENT_CALLS_METRIC_NAME}.
+         */
+        public String getMaxAllowedConcurrentCallsMetricName() {
+            return maxAllowedConcurrentCallsMetricName;
+        }
+
+        /** Helps building custom instance of {@link MetricNames}. */
+        public static class Builder {
+
+            private final MetricNames metricNames = new MetricNames();
+
+            /** Overrides the default metric name {@value MetricNames#DEFAULT_BULKHEAD_AVAILABLE_CONCURRENT_CALLS_METRIC_NAME} with a given one. */
+            public Builder availableConcurrentCallsMetricName(String availableConcurrentCallsMetricNames) {
+                metricNames.availableConcurrentCallsMetricName = requireNonNull(availableConcurrentCallsMetricNames);
+                return this;
+            }
+
+            /** Overrides the default metric name {@value MetricNames#DEFAULT_BULKHEAD_MAX_ALLOWED_CONCURRENT_CALLS_METRIC_NAME} with a given one. */
+            public Builder maxAllowedConcurrentCallsMetricName(String maxAllowedConcurrentCallsMetricName) {
+                metricNames.maxAllowedConcurrentCallsMetricName = requireNonNull(maxAllowedConcurrentCallsMetricName);
+                return this;
+            }
+
+            /** Builds {@link MetricNames} instance. */
+            public MetricNames build() {
+                return metricNames;
+            }
+        }
+    }
+}