From e30323829185dcd016ad9291316a1f54cb2615a9 Mon Sep 17 00:00:00 2001 From: Jon Schneider Date: Tue, 20 Feb 2018 12:30:44 -0600 Subject: [PATCH] Fix all Javadoc warnings, fix SignalFx tag key naming convention --- .../micrometer/atlas/AtlasMeterRegistry.java | 4 +- .../io/micrometer/datadog/DatadogConfig.java | 16 ++-- .../io/micrometer/ganglia/GangliaConfig.java | 20 ++--- .../micrometer/graphite/GraphiteConfig.java | 20 ++--- .../io/micrometer/influx/InfluxConfig.java | 21 +++-- .../micrometer/newrelic/NewRelicConfig.java | 7 +- .../prometheus/PrometheusConfig.java | 9 ++- .../PrometheusDistributionSummary.java | 2 + .../prometheus/PrometheusMeterRegistry.java | 6 +- .../prometheus/PrometheusTimer.java | 4 +- .../micrometer/signalfx/SignalFxConfig.java | 11 ++- .../signalfx/SignalFxNamingConvention.java | 36 +++++---- .../SignalFxNamingConventionTest.java | 22 +++-- .../io/micrometer/statsd/StatsdConfig.java | 30 ++++--- .../statsd/StatsdMeterRegistry.java | 4 +- .../statsd/internal/MemoizingFunction.java | 4 +- .../micrometer/wavefront/WavefrontConfig.java | 19 +++-- .../io/micrometer/core/aop/TimedAspect.java | 3 - .../micrometer/core/instrument/Counter.java | 8 +- .../core/instrument/DistributionSummary.java | 35 ++++++-- .../core/instrument/FunctionCounter.java | 3 +- .../core/instrument/FunctionTimer.java | 25 ++++-- .../io/micrometer/core/instrument/Gauge.java | 10 ++- .../core/instrument/LongTaskTimer.java | 34 +++++--- .../core/instrument/Measurement.java | 8 +- .../io/micrometer/core/instrument/Meter.java | 14 +++- .../core/instrument/MeterRegistry.java | 67 ++++++++++----- .../micrometer/core/instrument/Metrics.java | 14 +++- .../micrometer/core/instrument/TimeGauge.java | 18 ++++- .../io/micrometer/core/instrument/Timer.java | 81 ++++++++++++++----- .../binder/cache/CacheMeterBinder.java | 4 +- .../binder/cache/CaffeineCacheMetrics.java | 4 + .../binder/cache/GuavaCacheMetrics.java | 2 + .../binder/cache/HazelcastCacheMetrics.java | 18 +++-- .../binder/cache/JCacheMetrics.java | 20 +++-- .../binder/reactor/ReactorMetrics.java | 56 ------------- .../reactor/ReactorMetricsSubscriber.java | 62 -------------- .../composite/CompositeMeterRegistry.java | 4 +- .../core/instrument/config/MeterFilter.java | 4 + .../cumulative/CumulativeTimer.java | 3 - .../PercentileHistogramBuckets.java | 6 +- .../dropwizard/DropwizardConfig.java | 7 +- .../dropwizard/DropwizardMeterRegistry.java | 4 +- .../core/instrument/simple/SimpleConfig.java | 11 ++- .../simple/SimpleMeterRegistry.java | 4 +- .../core/instrument/step/StepCounter.java | 3 - .../core/instrument/step/StepDouble.java | 2 +- .../core/instrument/step/StepLong.java | 2 +- .../instrument/step/StepMeterRegistry.java | 4 +- .../instrument/step/StepRegistryConfig.java | 12 +-- .../core/instrument/step/StepTimer.java | 3 - .../core/instrument/util/MathUtils.java | 4 +- .../core/instrument/util/TimeDecayingMax.java | 16 +++- .../java/io/micrometer/core/lang/NonNull.java | 2 - .../io/micrometer/core/lang/NonNullApi.java | 2 - .../micrometer/core/lang/NonNullFields.java | 2 - .../io/micrometer/core/lang/Nullable.java | 2 - .../jersey2/server/AnnotationFinder.java | 9 ++- .../MetricsAutoConfiguration.java | 4 +- .../SimpleMetricsExportAutoConfiguration.java | 5 -- .../servlet/ServletMetricsConfiguration.java | 7 +- .../spring/web/servlet/WebMvcTags.java | 13 +-- .../core/samples/FunctionTimerSample.java | 4 +- .../core/samples/utils/SampleConfig.java | 9 +-- .../core/samples/utils/SampleRegistries.java | 3 +- 65 files changed, 496 insertions(+), 376 deletions(-) rename micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/package-info.java => implementations/micrometer-registry-signalfx/src/test/java/io/micrometer/signalfx/SignalFxNamingConventionTest.java (56%) delete mode 100644 micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetrics.java delete mode 100644 micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetricsSubscriber.java diff --git a/implementations/micrometer-registry-atlas/src/main/java/io/micrometer/atlas/AtlasMeterRegistry.java b/implementations/micrometer-registry-atlas/src/main/java/io/micrometer/atlas/AtlasMeterRegistry.java index 1bae80ee1c..91b1791052 100644 --- a/implementations/micrometer-registry-atlas/src/main/java/io/micrometer/atlas/AtlasMeterRegistry.java +++ b/implementations/micrometer-registry-atlas/src/main/java/io/micrometer/atlas/AtlasMeterRegistry.java @@ -162,8 +162,8 @@ protected io.micrometer.core.instrument.Gauge newGauge(Meter.Id id, @Nullabl } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { - FunctionCounter fc = new StepFunctionCounter<>(id, clock, atlasConfig.step().toMillis(), obj, valueFunction); + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { + FunctionCounter fc = new StepFunctionCounter<>(id, clock, atlasConfig.step().toMillis(), obj, countFunction); newMeter(id, Meter.Type.COUNTER, fc.measure()); return fc; } diff --git a/implementations/micrometer-registry-datadog/src/main/java/io/micrometer/datadog/DatadogConfig.java b/implementations/micrometer-registry-datadog/src/main/java/io/micrometer/datadog/DatadogConfig.java index 187b436344..b6e6936d7e 100644 --- a/implementations/micrometer-registry-datadog/src/main/java/io/micrometer/datadog/DatadogConfig.java +++ b/implementations/micrometer-registry-datadog/src/main/java/io/micrometer/datadog/DatadogConfig.java @@ -20,7 +20,7 @@ import io.micrometer.core.lang.Nullable; /** - * Configuration for Datadog exporting. + * Configuration for {@link DatadogMeterRegistry}. * * @author Jon Schneider */ @@ -37,18 +37,22 @@ default String prefix() { default String apiKey() { String v = get(prefix() + ".apiKey"); - if(v == null) + if (v == null) throw new MissingRequiredConfigurationException("apiKey must be set to report metrics to Datadog"); return v; } + /** + * @return The Datadog application key. This is only required if you care for metadata like base units, description, + * and meter type to be published to Datadog. + */ @Nullable default String applicationKey() { return get(prefix() + ".applicationKey"); } /** - * The tag that will be mapped to "host" when shipping metrics to datadog, or {@code null} if + * @return The tag that will be mapped to "host" when shipping metrics to datadog, or {@code null} if * host should be omitted on publishing. */ @Nullable @@ -58,7 +62,7 @@ default String hostTag() { } /** - * The URI to ship metrics to. If you need to publish metrics to an internal proxy en route to + * @return The URI to ship metrics to. If you need to publish metrics to an internal proxy en route to * datadoghq, you can define the location of the proxy with this. */ default String uri() { @@ -67,13 +71,11 @@ default String uri() { } /** - * {@code true} if meter descriptions should be sent to Datadog. + * @return {@code true} if meter descriptions should be sent to Datadog. * Turn this off to minimize the amount of data sent on each scrape. */ default boolean descriptions() { String v = get(prefix() + ".descriptions"); return v == null || Boolean.valueOf(v); } - - } diff --git a/implementations/micrometer-registry-ganglia/src/main/java/io/micrometer/ganglia/GangliaConfig.java b/implementations/micrometer-registry-ganglia/src/main/java/io/micrometer/ganglia/GangliaConfig.java index 6945bb0447..75da552c1a 100644 --- a/implementations/micrometer-registry-ganglia/src/main/java/io/micrometer/ganglia/GangliaConfig.java +++ b/implementations/micrometer-registry-ganglia/src/main/java/io/micrometer/ganglia/GangliaConfig.java @@ -22,6 +22,8 @@ import java.util.concurrent.TimeUnit; /** + * Configuration for {@link GangliaMeterRegistry}. + * * @author Jon Schneider */ public interface GangliaConfig extends DropwizardConfig { @@ -33,16 +35,14 @@ public interface GangliaConfig extends DropwizardConfig { /** * Get the value associated with a key. * - * @param key - * Key to lookup in the config. - * @return - * Value for the key or null if no key is present. + * @param key Key to lookup in the config. + * @return Value for the key or null if no key is present. */ @Nullable String get(String key); /** - * Property prefix to prepend to configuration names. + * @return Property prefix to prepend to configuration names. */ default String prefix() { return "ganglia"; @@ -60,9 +60,9 @@ default TimeUnit durationUnits() { default String protocolVersion() { String v = get(prefix() + ".protocolVersion"); - if(v == null) + if (v == null) return "3.1"; - if(!v.equals("3.1") && !v.equals("3.0")) { + if (!v.equals("3.1") && !v.equals("3.0")) { throw new IllegalArgumentException("Ganglia version must be one of 3.1 or 3.0 (check property " + prefix() + ".protocolVersion)"); } return v; @@ -70,9 +70,9 @@ default String protocolVersion() { default GMetric.UDPAddressingMode addressingMode() { String v = get(prefix() + ".addressingMode"); - if(v == null) + if (v == null) return GMetric.UDPAddressingMode.MULTICAST; - if(!v.equalsIgnoreCase("unicast") && !v.equalsIgnoreCase("multicast")) { + if (!v.equalsIgnoreCase("unicast") && !v.equalsIgnoreCase("multicast")) { throw new IllegalArgumentException("Ganglia UDP addressing mode must be one of 'unicast' or 'multicast' (check property " + prefix() + ".addressingMode)"); } return GMetric.UDPAddressingMode.valueOf(v.toUpperCase()); @@ -94,7 +94,7 @@ default int port() { } /** - * Returns true if publishing is enabled. Default is {@code true}. + * @return {@code true} if publishing is enabled. Default is {@code true}. */ default boolean enabled() { String v = get(prefix() + ".enabled"); diff --git a/implementations/micrometer-registry-graphite/src/main/java/io/micrometer/graphite/GraphiteConfig.java b/implementations/micrometer-registry-graphite/src/main/java/io/micrometer/graphite/GraphiteConfig.java index f54e61b0ab..64ccdf520b 100644 --- a/implementations/micrometer-registry-graphite/src/main/java/io/micrometer/graphite/GraphiteConfig.java +++ b/implementations/micrometer-registry-graphite/src/main/java/io/micrometer/graphite/GraphiteConfig.java @@ -21,6 +21,8 @@ import java.util.concurrent.TimeUnit; /** + * Configuration for {@link GraphiteMeterRegistry}. + * * @author Jon Schneider */ public interface GraphiteConfig extends DropwizardConfig { @@ -32,23 +34,21 @@ public interface GraphiteConfig extends DropwizardConfig { /** * Get the value associated with a key. * - * @param key - * Key to lookup in the config. - * @return - * Value for the key or null if no key is present. + * @param key Key to lookup in the config. + * @return Value for the key or null if no key is present. */ @Nullable String get(String key); /** - * Property prefix to prepend to configuration names. + * @return Property prefix to prepend to configuration names. */ default String prefix() { return "graphite"; } /** - * For the default naming convention, turn the specified tag keys into + * @return For the default naming convention, turn the specified tag keys into * part of the metric prefix. */ default String[] tagsAsPrefix() { @@ -76,7 +76,7 @@ default int port() { } /** - * Returns true if publishing is enabled. Default is {@code true}. + * @return {@code true} if publishing is enabled. Default is {@code true}. */ default boolean enabled() { String v = get(prefix() + ".enabled"); @@ -84,16 +84,16 @@ default boolean enabled() { } /** - * Protocol to use while shipping data to Graphite. + * @return Protocol to use while shipping data to Graphite. */ default GraphiteProtocol protocol() { String v = get(prefix() + ".protocol"); - if(v == null) + if (v == null) return GraphiteProtocol.PICKLED; for (GraphiteProtocol flavor : GraphiteProtocol.values()) { - if(flavor.toString().equalsIgnoreCase(v)) + if (flavor.toString().equalsIgnoreCase(v)) return flavor; } diff --git a/implementations/micrometer-registry-influx/src/main/java/io/micrometer/influx/InfluxConfig.java b/implementations/micrometer-registry-influx/src/main/java/io/micrometer/influx/InfluxConfig.java index da7ccc91aa..0107acd22b 100644 --- a/implementations/micrometer-registry-influx/src/main/java/io/micrometer/influx/InfluxConfig.java +++ b/implementations/micrometer-registry-influx/src/main/java/io/micrometer/influx/InfluxConfig.java @@ -19,6 +19,8 @@ import io.micrometer.core.lang.Nullable; /** + * Configuration for {@link InfluxMeterRegistry}. + * * @author Jon Schneider */ public interface InfluxConfig extends StepRegistryConfig { @@ -33,7 +35,7 @@ default String prefix() { } /** - * The db to send metrics to. Defaults to "mydb". + * @return The db to send metrics to. Defaults to "mydb". */ default String db() { String v = get(prefix() + ".db"); @@ -41,20 +43,18 @@ default String db() { } /** - * Sets the write consistency for each point. The Influx default is 'one'. Must - * be one of 'any', 'one', 'quorum', or 'all'. - * - * Only available for InfluxEnterprise clusters. + * @return Sets the write consistency for each point. The Influx default is 'one'. Must + * be one of 'any', 'one', 'quorum', or 'all'. Only available for InfluxEnterprise clusters. */ default InfluxConsistency consistency() { String v = get(prefix() + ".consistency"); - if(v == null) + if (v == null) return InfluxConsistency.ONE; return InfluxConsistency.valueOf(v.toUpperCase()); } /** - * Authenticate requests with this user. By default is {@code null}, and the registry will not + * @return Authenticate requests with this user. By default is {@code null}, and the registry will not * attempt to present credentials to Influx. */ @Nullable @@ -63,7 +63,7 @@ default String userName() { } /** - * Authenticate requests with this password. By default is {@code null}, and the registry will not + * @return Authenticate requests with this password. By default is {@code null}, and the registry will not * attempt to present credentials to Influx. */ @Nullable @@ -72,7 +72,7 @@ default String password() { } /** - * Influx writes to the DEFAULT retention policy if one is not specified. + * @return Influx writes to the DEFAULT retention policy if one is not specified. */ @Nullable default String retentionPolicy() { @@ -80,8 +80,7 @@ default String retentionPolicy() { } /** - * Returns the URI for the Influx backend. The default is - * {@code http://localhost:8086/write}. + * @return The URI for the Influx backend. The default is {@code http://localhost:8086}. */ default String uri() { String v = get(prefix() + ".uri"); diff --git a/implementations/micrometer-registry-new-relic/src/main/java/io/micrometer/newrelic/NewRelicConfig.java b/implementations/micrometer-registry-new-relic/src/main/java/io/micrometer/newrelic/NewRelicConfig.java index fe92cb8de9..709fa79910 100644 --- a/implementations/micrometer-registry-new-relic/src/main/java/io/micrometer/newrelic/NewRelicConfig.java +++ b/implementations/micrometer-registry-new-relic/src/main/java/io/micrometer/newrelic/NewRelicConfig.java @@ -18,6 +18,11 @@ import io.micrometer.core.instrument.config.MissingRequiredConfigurationException; import io.micrometer.core.instrument.step.StepRegistryConfig; +/** + * Configuration for {@link NewRelicMeterRegistry}. + * + * @author Jon Schneider + */ public interface NewRelicConfig extends StepRegistryConfig { /** * Accept configuration defaults @@ -44,7 +49,7 @@ default String accountId() { } /** - * Returns the URI for the New Relic insights API. The default is + * @return The URI for the New Relic insights API. The default is * {@code https://insights-collector.newrelic.com}. If you need to pass through * a proxy, you can change this value. */ diff --git a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusConfig.java b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusConfig.java index 8049e67abc..e2bc648eeb 100644 --- a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusConfig.java +++ b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusConfig.java @@ -19,6 +19,11 @@ import java.time.Duration; +/** + * Configuration for {@link PrometheusMeterRegistry}. + * + * @author Jon Schneider + */ public interface PrometheusConfig extends MeterRegistryConfig { /** * Accept configuration defaults @@ -31,7 +36,7 @@ default String prefix() { } /** - * {@code true} if meter descriptions should be sent to Prometheus. + * @return {@code true} if meter descriptions should be sent to Prometheus. * Turn this off to minimize the amount of data sent on each scrape. */ default boolean descriptions() { @@ -40,7 +45,7 @@ default boolean descriptions() { } /** - * Returns the step size to use in computing windowed statistics like max. The default is 1 minute. + * @return The step size to use in computing windowed statistics like max. The default is 1 minute. * To get the most out of these statistics, align the step interval to be close to your scrape interval. */ default Duration step() { diff --git a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusDistributionSummary.java b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusDistributionSummary.java index edb64d1121..c42d2a9906 100644 --- a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusDistributionSummary.java +++ b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusDistributionSummary.java @@ -82,6 +82,8 @@ public int hashCode() { /** * For Prometheus we cannot use the histogram counts from HistogramSnapshot, as it is based on a * rolling histogram. Prometheus requires a histogram that accumulates values over the lifetime of the app. + * + * @return Cumulative histogram buckets. */ public CountAtBucket[] histogramCounts() { return percentilesHistogram.takeSnapshot(0, 0, 0, true).histogramCounts(); diff --git a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusMeterRegistry.java b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusMeterRegistry.java index 70d965ccd8..4bfc8edf7e 100644 --- a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusMeterRegistry.java +++ b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusMeterRegistry.java @@ -67,7 +67,7 @@ public PrometheusMeterRegistry(PrometheusConfig config, CollectorRegistry regist } /** - * Content that should be included in the response body for an endpoint designate for + * @return Content that should be included in the response body for an endpoint designate for * Prometheus to scrape from. */ public String scrape() { @@ -263,9 +263,9 @@ protected FunctionTimer newFunctionTimer(Meter.Id id, T obj, ToLongFunction< } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { MicrometerCollector collector = collectorByName(id, Collector.Type.COUNTER); - FunctionCounter fc = new CumulativeFunctionCounter<>(id, obj, valueFunction); + FunctionCounter fc = new CumulativeFunctionCounter<>(id, obj, countFunction); List tagValues = tagValues(id); collector.add((conventionName, tagKeys) -> Stream.of( diff --git a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusTimer.java b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusTimer.java index baf59acf5f..d7119f437e 100644 --- a/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusTimer.java +++ b/implementations/micrometer-registry-prometheus/src/main/java/io/micrometer/prometheus/PrometheusTimer.java @@ -17,8 +17,8 @@ import io.micrometer.core.instrument.AbstractTimer; import io.micrometer.core.instrument.Clock; -import io.micrometer.core.instrument.distribution.CountAtBucket; import io.micrometer.core.instrument.Timer; +import io.micrometer.core.instrument.distribution.CountAtBucket; import io.micrometer.core.instrument.distribution.DistributionStatisticConfig; import io.micrometer.core.instrument.distribution.TimeWindowLatencyHistogram; import io.micrometer.core.instrument.distribution.pause.PauseDetector; @@ -74,6 +74,8 @@ public double max(TimeUnit unit) { /** * For Prometheus we cannot use the histogram counts from HistogramSnapshot, as it is based on a * rolling histogram. Prometheus requires a histogram that accumulates values over the lifetime of the app. + * + * @return Cumulative histogram buckets. */ public CountAtBucket[] histogramCounts() { return percentilesHistogram.takeSnapshot(0, 0, 0, true).histogramCounts(); diff --git a/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxConfig.java b/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxConfig.java index 9742c85dfe..573a1bec6a 100644 --- a/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxConfig.java +++ b/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxConfig.java @@ -22,6 +22,11 @@ import java.net.UnknownHostException; import java.time.Duration; +/** + * Configuration for {@link SignalFxMeterRegistry}. + * + * @author Jon Schneider + */ public interface SignalFxConfig extends StepRegistryConfig { SignalFxConfig DEFAULT = k -> null; @@ -32,13 +37,13 @@ default String prefix() { default String accessToken() { String v = get(prefix() + ".accessToken"); - if(v == null) + if (v == null) throw new MissingRequiredConfigurationException("accessToken must be set to report metrics to SignalFX"); return v; } /** - * The URI to ship metrics to. If you need to publish metrics to an internal proxy en route to + * @return The URI to ship metrics to. If you need to publish metrics to an internal proxy en route to * SignalFx, you can define the location of the proxy with this. */ default String uri() { @@ -47,7 +52,7 @@ default String uri() { } /** - * Uniquely identifies the app instance that is publishing metrics to SignalFx. Defaults to the local host name. + * @return Unique identifier for the app instance that is publishing metrics to SignalFx. Defaults to the local host name. */ default String source() { String v = get(prefix() + ".source"); diff --git a/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxNamingConvention.java b/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxNamingConvention.java index 3133103a45..30e1d40b55 100644 --- a/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxNamingConvention.java +++ b/implementations/micrometer-registry-signalfx/src/main/java/io/micrometer/signalfx/SignalFxNamingConvention.java @@ -21,6 +21,7 @@ /** * See https://developers.signalfx.com/reference#section-criteria-for-metric-and-dimension-names-and-values for criteria. + * * @author Jon Schneider */ public class SignalFxNamingConvention implements NamingConvention { @@ -34,32 +35,35 @@ public SignalFxNamingConvention(NamingConvention rootConvention) { this.rootConvention = rootConvention; } - /** - * Metric (the metric name) can be any non-empty UTF-8 string, with a maximum length <= 256 characters - */ + // Metric (the metric name) can be any non-empty UTF-8 string, with a maximum length <= 256 characters @Override public String name(String name, Meter.Type type, @Nullable String baseUnit) { String formattedName = rootConvention.name(name, type, baseUnit); return formattedName.length() > 256 ? formattedName.substring(0, 256) : formattedName; } - /** - * 1. Has a maximum length of 128 characters - * 2. May not start with _ or sf_ - * 3. Must start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores _ and hyphens - . This requirement is expressed in the following regular expression: - * ^[a-zA-Z][a-zA-Z0-9_-]*$ - * FIXME - */ + // 1. Has a maximum length of 128 characters + // 2. May not start with _ or sf_ + // 3. Must start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores _ and hyphens - . This requirement is expressed in the following regular expression: + // ^[a-zA-Z][a-zA-Z0-9_-]*$ @Override public String tagKey(String key) { - return rootConvention.tagKey(key); + String conventionKey = rootConvention.tagKey(key); + + conventionKey = conventionKey.replaceAll("^_", "").replaceAll("^sf_", ""); // 2 + + if (!conventionKey.matches("^[a-zA-Z].*")) { // 3 + conventionKey = "a" + conventionKey; + } + + if (conventionKey.length() > 128) { + conventionKey = conventionKey.substring(0, 128); // 1 + } + + return conventionKey; } - /** - * Dimension value can be any non-empty UTF-8 string, with a maximum length <= 256 characters. - * @param value - * @return - */ + // Dimension value can be any non-empty UTF-8 string, with a maximum length <= 256 characters. @Override public String tagValue(String value) { String formattedValue = rootConvention.tagValue(value); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/package-info.java b/implementations/micrometer-registry-signalfx/src/test/java/io/micrometer/signalfx/SignalFxNamingConventionTest.java similarity index 56% rename from micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/package-info.java rename to implementations/micrometer-registry-signalfx/src/test/java/io/micrometer/signalfx/SignalFxNamingConventionTest.java index 232a3c3a48..fae54987ee 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/package-info.java +++ b/implementations/micrometer-registry-signalfx/src/test/java/io/micrometer/signalfx/SignalFxNamingConventionTest.java @@ -13,9 +13,21 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -@NonNullApi -@NonNullFields -package io.micrometer.core.instrument.binder.reactor; +package io.micrometer.signalfx; -import io.micrometer.core.lang.NonNullApi; -import io.micrometer.core.lang.NonNullFields; +import org.junit.jupiter.api.Test; + +import static org.assertj.core.api.Assertions.assertThat; + +class SignalFxNamingConventionTest { + private SignalFxNamingConvention convention = new SignalFxNamingConvention(); + + @Test + void tagKey() { + assertThat(convention.tagKey("_boo")).isEqualTo("boo"); + assertThat(convention.tagKey("sf_boo")).isEqualTo("boo"); + + assertThat(convention.tagKey("123")).isEqualTo("a123"); + } + +} \ No newline at end of file diff --git a/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdConfig.java b/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdConfig.java index 22b1e92ffd..dd967dcfa6 100644 --- a/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdConfig.java +++ b/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdConfig.java @@ -20,6 +20,8 @@ import java.time.Duration; /** + * Configuration for {@link StatsdMeterRegistry}. + * * @author Jon Schneider */ public interface StatsdConfig extends MeterRegistryConfig { @@ -34,7 +36,7 @@ default String prefix() { } /** - * Choose which variant of the StatsD line protocol to use. + * @return Choose which variant of the StatsD line protocol to use. */ default StatsdFlavor flavor() { String v = get(prefix() + ".flavor"); @@ -42,11 +44,11 @@ default StatsdFlavor flavor() { // Datadog is the default because it is more frequently requested than // vanilla StatsD (Etsy), and Telegraf supports Datadog's format with a configuration // option. - if(v == null) + if (v == null) return StatsdFlavor.DATADOG; for (StatsdFlavor flavor : StatsdFlavor.values()) { - if(flavor.toString().equalsIgnoreCase(v)) + if (flavor.toString().equalsIgnoreCase(v)) return flavor; } @@ -54,7 +56,7 @@ default StatsdFlavor flavor() { } /** - * Returns true if publishing is enabled. Default is {@code true}. + * @return {@code true} if publishing is enabled. Default is {@code true}. */ default boolean enabled() { String v = get(prefix() + ".enabled"); @@ -62,7 +64,7 @@ default boolean enabled() { } /** - * The host name of the StatsD agent. + * @return The host name of the StatsD agent. */ default String host() { String v = get(prefix() + ".host"); @@ -70,7 +72,7 @@ default String host() { } /** - * The UDP port of the StatsD agent. + * @return The UDP port of the StatsD agent. */ default int port() { String v = get(prefix() + ".port"); @@ -79,11 +81,11 @@ default int port() { /** * Keep the total length of the payload within your network's MTU. There is no single good value to use, but here are some guidelines for common network scenarios: - * 1. Fast Ethernet (1432) - This is most likely for Intranets. - * 2. Gigabit Ethernet (8932) - Jumbo frames can make use of this feature much more efficient. - * 3. Commodity Internet (512) - If you are routing over the internet a value in this range will be reasonable. You might be able to go higher, but you are at the mercy of all the hops in your route. + * 1. Fast Ethernet (1432) - This is most likely for Intranets. + * 2. Gigabit Ethernet (8932) - Jumbo frames can make use of this feature much more efficient. + * 3. Commodity Internet (512) - If you are routing over the internet a value in this range will be reasonable. You might be able to go higher, but you are at the mercy of all the hops in your route. * - * FIXME implement packet-limiting the StatsD publisher + * @return The max length of the payload. */ default int maxPacketLength() { String v = get(prefix() + ".maxPacketLength"); @@ -96,6 +98,8 @@ default int maxPacketLength() { /** * Determines how often gauges will be polled. When a gauge is polled, its value is recalculated. If the value has changed, * it is sent to the StatsD server. + * + * @return The polling frequency. */ default Duration pollingFrequency() { String v = get(prefix() + ".pollingFrequency"); @@ -104,6 +108,8 @@ default Duration pollingFrequency() { /** * Governs the maximum size of the queue of items waiting to be sent to a StatsD agent over UDP. + * + * @return Maximum queue size. */ default int queueSize() { String v = get(prefix() + ".queueSize"); @@ -111,7 +117,7 @@ default int queueSize() { } /** - * Returns the step size to use in computing windowed statistics like max. The default is 1 minute. + * @return The step size to use in computing windowed statistics like max. The default is 1 minute. * To get the most out of these statistics, align the step interval to be close to your scrape interval. */ default Duration step() { @@ -120,7 +126,7 @@ default Duration step() { } /** - * Returns true if unchanged meters should be published to the StatsD server. Default is {@code true}. + * @return {@code true} if unchanged meters should be published to the StatsD server. Default is {@code true}. */ default boolean publishUnchangedMeters() { String v = get(prefix() + ".publishUnchangedMeters"); diff --git a/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdMeterRegistry.java b/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdMeterRegistry.java index 90b7a37959..76ee5e2428 100644 --- a/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdMeterRegistry.java +++ b/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/StatsdMeterRegistry.java @@ -213,8 +213,8 @@ protected DistributionSummary newDistributionSummary(Meter.Id id, DistributionSt } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { - StatsdFunctionCounter fc = new StatsdFunctionCounter<>(id, obj, valueFunction, lineBuilder(id), publisher); + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { + StatsdFunctionCounter fc = new StatsdFunctionCounter<>(id, obj, countFunction, lineBuilder(id), publisher); pollableMeters.add(fc); return fc; } diff --git a/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/internal/MemoizingFunction.java b/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/internal/MemoizingFunction.java index 79ae9ac73e..90227c6cdf 100644 --- a/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/internal/MemoizingFunction.java +++ b/implementations/micrometer-registry-statsd/src/main/java/io/micrometer/statsd/internal/MemoizingFunction.java @@ -19,7 +19,9 @@ /** * Modified from Guava's MemoizingFunction - * @param + * + * @param The domain type. + * @param The range type. */ public class MemoizingFunction implements Function { diff --git a/implementations/micrometer-registry-wavefront/src/main/java/io/micrometer/wavefront/WavefrontConfig.java b/implementations/micrometer-registry-wavefront/src/main/java/io/micrometer/wavefront/WavefrontConfig.java index ffc9e3a4be..a5c00f60e3 100644 --- a/implementations/micrometer-registry-wavefront/src/main/java/io/micrometer/wavefront/WavefrontConfig.java +++ b/implementations/micrometer-registry-wavefront/src/main/java/io/micrometer/wavefront/WavefrontConfig.java @@ -23,6 +23,12 @@ import java.net.UnknownHostException; import java.time.Duration; +/** + * Configuration for {@link WavefrontMeterRegistry}. + * + * @author Howard Yoo + * @author Jon Schneider + */ public interface WavefrontConfig extends StepRegistryConfig { /** * Publishes to a wavefront sidecar running out of process. @@ -68,22 +74,21 @@ default String prefix() { } /** - * The URI to publish metrics to. The URI could represent a Wavefront sidecar or the + * @return The URI to publish metrics to. The URI could represent a Wavefront sidecar or the * Wavefront API host. This host could also represent an internal proxy set up in your environment * that forwards metrics data to the Wavefront API host. - * - * If publishing metrics to a Wavefront proxy (as described in https://docs.wavefront.com/proxies_installing.html), + *

If publishing metrics to a Wavefront proxy (as described in https://docs.wavefront.com/proxies_installing.html), * the host must be in the proxy://HOST:PORT format. */ default String uri() { String v = get(prefix() + ".uri"); - if(v == null) + if (v == null) throw new MissingRequiredConfigurationException("A uri is required to publish metrics to Wavefront"); return v; } /** - * Uniquely identifies the app instance that is publishing metrics to Wavefront. Defaults to the local host name. + * @return Unique identifier for the app instance that is publishing metrics to Wavefront. Defaults to the local host name. */ default String source() { String v = get(prefix() + ".source"); @@ -99,6 +104,8 @@ default String source() { /** * Required when publishing directly to the Wavefront API host, otherwise does nothing. + * + * @return The Wavefront API token. */ @Nullable default String apiToken() { @@ -110,6 +117,8 @@ default String apiToken() { * Wavefront metrics are grouped hierarchically by name in the UI. Setting a global prefix separates * metrics originating from this app's whitebox instrumentation from those originating from other Wavefront * integrations. + * + * @return A prefix to add to every metric. */ @Nullable default String globalPrefix() { diff --git a/micrometer-core/src/main/java/io/micrometer/core/aop/TimedAspect.java b/micrometer-core/src/main/java/io/micrometer/core/aop/TimedAspect.java index 8b160d4335..adbcebe2c7 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/aop/TimedAspect.java +++ b/micrometer-core/src/main/java/io/micrometer/core/aop/TimedAspect.java @@ -56,9 +56,6 @@ public TimedAspect(MeterRegistry registry, Function measure() { return Arrays.asList( - new Measurement(() -> (double) count(), Statistic.COUNT), - new Measurement(this::totalAmount, Statistic.TOTAL) + new Measurement(() -> (double) count(), Statistic.COUNT), + new Measurement(this::totalAmount, Statistic.TOTAL) ); } @@ -102,6 +121,7 @@ private Builder(String name) { /** * @param tags Must be an even number of arguments representing key/value pairs of tags. + * @return The distribution summmary builder with added tags. */ public Builder tags(String... tags) { return tags(Tags.of(tags)); @@ -151,6 +171,7 @@ public Builder baseUnit(@Nullable String unit) { * to publish a histogram that can be used to generate aggregable percentile approximations. * * @param percentiles Percentiles to compute and publish. The 95th percentile should be expressed as {@code 0.95}. + * @return This builder. */ public Builder publishPercentiles(@Nullable double... percentiles) { this.distributionConfigBuilder.percentiles(percentiles); @@ -173,7 +194,7 @@ public Builder publishPercentileHistogram() { * systems that have query facilities to do so (e.g. Prometheus' {@code histogram_quantile}, * Atlas' {@code :percentiles}). * - * @param enabled Value determining whether histgoram + * @param enabled Determines whether percentile histograms should be published. * @return This builder. */ public Builder publishPercentileHistogram(@Nullable Boolean enabled) { diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionCounter.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionCounter.java index ffb0eb4b0d..3a59d13b37 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionCounter.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionCounter.java @@ -33,7 +33,7 @@ static Builder builder(String name, @Nullable T obj, ToDoubleFunction } /** - * The cumulative count since this counter was created. + * @return The cumulative count since this counter was created. */ double count(); @@ -69,6 +69,7 @@ private Builder(String name, @Nullable T obj, ToDoubleFunction f) { /** * @param tags Must be an even number of arguments representing key/value pairs of tags. + * @return The function counter builder with added tags. */ public Builder tags(String... tags) { return tags(Tags.of(tags)); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionTimer.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionTimer.java index fb00159d86..27f4d7a60d 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionTimer.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionTimer.java @@ -24,6 +24,12 @@ import java.util.function.ToDoubleFunction; import java.util.function.ToLongFunction; +/** + * A timer that tracks two monotonically increasing functions: one representing the count of events and one + * representing the total time spent in every event. + * + * @author Jon Schneider + */ public interface FunctionTimer extends Meter { static Builder builder(String name, T obj, ToLongFunction countFunction, ToDoubleFunction totalTimeFunction, @@ -32,26 +38,34 @@ static Builder builder(String name, T obj, ToLongFunction countFunctio } /** - * The total number of occurrences of the timed event. + * @return The total number of occurrences of the timed event. */ double count(); /** - * The total time of all occurrences of the timed event. + * @param unit The base unit of time to scale the total to. + * @return The total time of all occurrences of the timed event. */ double totalTime(TimeUnit unit); + /** + * @param unit The base unit of time to scale the mean to. + * @return The distribution average for all recorded events. + */ default double mean(TimeUnit unit) { return count() == 0 ? 0 : totalTime(unit) / count(); } + /** + * @return The base time unit of the timer to which all published metrics will be scaled + */ TimeUnit baseTimeUnit(); @Override default Iterable measure() { return Arrays.asList( - new Measurement(this::count, Statistic.COUNT), - new Measurement(() -> totalTime(baseTimeUnit()), Statistic.TOTAL_TIME) + new Measurement(this::count, Statistic.COUNT), + new Measurement(() -> totalTime(baseTimeUnit()), Statistic.TOTAL_TIME) ); } @@ -86,6 +100,7 @@ private Builder(String name, @Nullable T obj, /** * @param tags Must be an even number of arguments representing key/value pairs of tags. + * @return The function timer builder with added tags. */ public Builder tags(String... tags) { return tags(Tags.of(tags)); @@ -129,7 +144,7 @@ public Builder description(@Nullable String description) { */ public FunctionTimer register(MeterRegistry registry) { return registry.more().timer(new Meter.Id(name, tags, null, description, Type.TIMER), obj, countFunction, totalTimeFunction, - totalTimeFunctionUnits); + totalTimeFunctionUnits); } } } diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/Gauge.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/Gauge.java index 91eafe31b6..f454d88ba3 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/Gauge.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/Gauge.java @@ -22,14 +22,22 @@ import java.util.List; import java.util.function.ToDoubleFunction; +/** + * A gauge tracks a value that may go up or down. The value that is published for gauges is + * an instantaneous sample of the gauge at publishing time. + * + * @author Jon Schneider + */ public interface Gauge extends Meter { static Builder builder(String name, @Nullable T obj, ToDoubleFunction f) { return new Builder<>(name, obj, f); } /** - * Returns the current value. The act of observing the value by calling this method triggers sampling + * The act of observing the value by calling this method triggers sampling * of the underlying number or user-defined function that defines the value for the gauge. + * + * @return The current value. */ double value(); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/LongTaskTimer.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/LongTaskTimer.java index 44fe9b92f1..79b4cdf27e 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/LongTaskTimer.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/LongTaskTimer.java @@ -26,6 +26,12 @@ import java.util.function.Consumer; import java.util.function.Supplier; +/** + * A long task timer is used to track the total duration of all in-flight long-running tasks and the number of + * such tasks. + * + * @author Jon Schneider + */ public interface LongTaskTimer extends Meter { static Builder builder(String name) { return new Builder(name); @@ -35,6 +41,7 @@ static Builder builder(String name) { * Create a timer builder from a {@link Timed} annotation. * * @param timed The annotation instance to base a new timer on. + * @return This builder. */ static Builder builder(Timed timed) { if (!timed.longTask()) { @@ -46,15 +53,17 @@ static Builder builder(Timed timed) { } return new Builder(timed.value()) - .tags(timed.extraTags()) - .description(timed.description().isEmpty() ? null : timed.description()); + .tags(timed.extraTags()) + .description(timed.description().isEmpty() ? null : timed.description()); } /** * Executes the callable `f` and records the time taken. * - * @param f Function to execute and measure the execution time. + * @param f Function to execute and measure the execution time. + * @param The return type of the {@link Callable}. * @return The return value of `f`. + * @throws Exception Any exception bubbling up from the callable. */ default T recordCallable(Callable f) throws Exception { Sample sample = start(); @@ -68,7 +77,8 @@ default T recordCallable(Callable f) throws Exception { /** * Executes the callable `f` and records the time taken. * - * @param f Function to execute and measure the execution time. + * @param f Function to execute and measure the execution time. + * @param The return type of the {@link Supplier}. * @return The return value of `f`. */ default T record(Supplier f) { @@ -125,29 +135,30 @@ default void record(Runnable f) { long stop(long task); /** - * Returns the current duration for an active task. + * The current duration for an active task. * * @param task Id for the task to stop. This should be the value returned from {@link #start()}. - * @param unit The time unit to scale the returned value to. + * @param unit The time unit to scale the duration to. * @return Duration for the task in nanoseconds. A -1 value will be returned for an unknown task. */ double duration(long task, TimeUnit unit); /** - * Returns the cumulative duration of all current tasks in nanoseconds. + * @param unit The time unit to scale the duration to. + * @return The cumulative duration of all current tasks in nanoseconds. */ double duration(TimeUnit unit); /** - * Returns the current number of tasks being executed. + * @return The current number of tasks being executed. */ int activeTasks(); @Override default Iterable measure() { return Arrays.asList( - new Measurement(() -> (double) activeTasks(), Statistic.ACTIVE_TASKS), - new Measurement(() -> duration(TimeUnit.NANOSECONDS), Statistic.DURATION) + new Measurement(() -> (double) activeTasks(), Statistic.ACTIVE_TASKS), + new Measurement(() -> duration(TimeUnit.NANOSECONDS), Statistic.DURATION) ); } @@ -190,6 +201,7 @@ private Builder(String name) { /** * @param tags Must be an even number of arguments representing key/value pairs of tags. + * @return The long task timer builder with added tags. */ public Builder tags(String... tags) { return tags(Tags.of(tags)); @@ -205,7 +217,7 @@ public Builder tags(Iterable tags) { } /** - * @param key The tag key. + * @param key The tag key. * @param value The tag value. * @return The long task timer builder with a single added tag. */ diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/Measurement.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/Measurement.java index f446f8e7ec..b275b2830a 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/Measurement.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/Measurement.java @@ -33,7 +33,7 @@ public Measurement(Supplier valueFunction, Statistic statistic) { } /** - * Value for the measurement. + * @return Value for the measurement. */ public double getValue() { return f.get(); @@ -46,8 +46,8 @@ public Statistic getStatistic() { @Override public String toString() { return "Measurement{" + - "statistic='" + statistic + '\'' + - ", value=" + getValue() + - '}'; + "statistic='" + statistic + '\'' + + ", value=" + getValue() + + '}'; } } diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/Meter.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/Meter.java index 95fc9e16ab..2ed217db2a 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/Meter.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/Meter.java @@ -24,7 +24,9 @@ import static java.util.stream.StreamSupport.stream; /** - * A counter, gauge, timer, or distribution summary that results collects one or more metrics. + * A named and dimensioned producer of one or more measurements. + * + * @author Jon Schneider */ public interface Meter extends AutoCloseable { static Builder builder(String name, Type type, Iterable measurements) { @@ -87,6 +89,16 @@ public Id(String name, Iterable tags, @Nullable String baseUnit, @Nullable this.type = type; } + /** + * Generate a new id with a different name. + * + * @param newName The new name. + * @return A new id with the provided name. The source id remains unchanged. + */ + public Id withName(String newName) { + return new Id(newName, tags, baseUnit, description, type); + } + /** * Generate a new id with an additional tag. If the key of the provided tag already exists, this overwrites * the tag value. diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/MeterRegistry.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/MeterRegistry.java index 2a877b7701..4dbf66cc65 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/MeterRegistry.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/MeterRegistry.java @@ -58,8 +58,8 @@ public abstract class MeterRegistry implements AutoCloseable { private volatile Map meterMap = Collections.emptyMap(); private final AtomicBoolean closed = new AtomicBoolean(false); private PauseDetector pauseDetector = new ClockDriftPauseDetector( - Duration.ofMillis(100), - Duration.ofMillis(100) + Duration.ofMillis(100), + Duration.ofMillis(100) ); /** @@ -106,7 +106,9 @@ protected MeterRegistry(Clock clock) { /** * Build a new timer to be added to the registry. This is guaranteed to only be called if the timer doesn't already exist. * - * @param id The id that uniquely identifies the timer. + * @param id The id that uniquely identifies the timer. + * @param distributionStatisticConfig Configuration for published distribution statistics. + * @param pauseDetector The pause detector to use for coordinated omission compensation. * @return A new timer. */ protected abstract Timer newTimer(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig, PauseDetector pauseDetector); @@ -114,7 +116,9 @@ protected MeterRegistry(Clock clock) { /** * Build a new distribution summary to be added to the registry. This is guaranteed to only be called if the distribution summary doesn't already exist. * - * @param id The id that uniquely identifies the distribution summary. + * @param id The id that uniquely identifies the distribution summary. + * @param distributionStatisticConfig Configuration for published distribution statistics. + * @param scale Multiply every recorded sample by this factor. * @return A new distribution summary. */ protected abstract DistributionSummary newDistributionSummary(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig, double scale); @@ -122,7 +126,9 @@ protected MeterRegistry(Clock clock) { /** * Build a new custom meter to be added to the registry. This is guaranteed to only be called if the custom meter doesn't already exist. * - * @param id The id that uniquely identifies the custom meter. + * @param id The id that uniquely identifies the custom meter. + * @param type What kind of meter this is. + * @param measurements A set of measurements describing how to sample this meter. * @return A new custom meter. */ protected abstract Meter newMeter(Meter.Id id, Meter.Type type, Iterable measurements); @@ -130,7 +136,11 @@ protected MeterRegistry(Clock clock) { /** * Build a new time gauge to be added to the registry. This is guaranteed to only be called if the time gauge doesn't already exist. * - * @param id The id that uniquely identifies the time gauge. + * @param id The id that uniquely identifies the time gauge. + * @param obj The state object from which the value function derives a measurement. + * @param valueFunctionUnit The base unit of time returned by the value function. + * @param valueFunction A function returning a time value that can go up or down. + * @param The type of the object upon which the value function derives a measurement. * @return A new time gauge. */ protected TimeGauge newTimeGauge(Meter.Id id, T obj, TimeUnit valueFunctionUnit, ToDoubleFunction valueFunction) { @@ -158,7 +168,12 @@ public TimeUnit baseTimeUnit() { /** * Build a new function timer to be added to the registry. This is guaranteed to only be called if the function timer doesn't already exist. * - * @param id The id that uniquely identifies the function timer. + * @param id The id that uniquely identifies the function timer. + * @param obj The state object from which the count and total functions derive measurements. + * @param countFunction A monotonically increasing count function. + * @param totalTimeFunction A monotonically increasing total time function. + * @param totalTimeFunctionUnits The base unit of time of the totals returned by the total time function. + * @param The type of the object upon which the value functions derives their measurements. * @return A new function timer. */ protected abstract FunctionTimer newFunctionTimer(Meter.Id id, T obj, ToLongFunction countFunction, ToDoubleFunction totalTimeFunction, TimeUnit totalTimeFunctionUnits); @@ -166,10 +181,13 @@ public TimeUnit baseTimeUnit() { /** * Build a new function counter to be added to the registry. This is guaranteed to only be called if the function counter doesn't already exist. * - * @param id The id that uniquely identifies the function counter. + * @param id The id that uniquely identifies the function counter. + * @param obj The state object from which the count function derives a measurement. + * @param countFunction A monotonically increasing count function. + * @param The type of the object upon which the value function derives a measurement. * @return A new function counter. */ - protected abstract FunctionCounter newFunctionCounter(Id id, T obj, ToDoubleFunction valueFunction); + protected abstract FunctionCounter newFunctionCounter(Id id, T obj, ToDoubleFunction countFunction); protected List getConventionTags(Meter.Id id) { return id.getConventionTags(config().namingConvention()); @@ -185,14 +203,15 @@ protected String getConventionName(Meter.Id id) { protected abstract TimeUnit getBaseTimeUnit(); /** - * Every custom registry implementation should define a default histogram expiry: - *

+ * Every custom registry implementation should define a default histogram expiry at a minimum: * 

-     * histogramConfig.builder()
+     * DistributionStatisticConfig.builder()
      *    .expiry(defaultStep)
      *    .build()
      *    .merge(DistributionStatisticConfig.DEFAULT);
      *
+ * + * @return The default distribution statistics config. */ protected abstract DistributionStatisticConfig defaultHistogramConfig(); @@ -226,7 +245,7 @@ Gauge gauge(Meter.Id id, @Nullable T obj, ToDoubleFunction valueFunction) /** * Only used by {@link Timer#builder(String)}. * - * @param id The identifier for this timer. + * @param id The identifier for this timer. * @param distributionStatisticConfig Configuration that governs how distribution statistics are computed. * @return A new or existing timer. */ @@ -240,13 +259,13 @@ Timer timer(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig /** * Only used by {@link DistributionSummary#builder(String)}. * - * @param id The identifier for this distribution summary. + * @param id The identifier for this distribution summary. * @param distributionStatisticConfig Configuration that governs how distribution statistics are computed. * @return A new or existing distribution summary. */ DistributionSummary summary(Meter.Id id, DistributionStatisticConfig distributionStatisticConfig, double scale) { return registerMeterIfNecessary(DistributionSummary.class, id, distributionStatisticConfig, (id2, filteredConfig) -> - newDistributionSummary(id2, filteredConfig.merge(defaultHistogramConfig()), scale), NoopDistributionSummary::new); + newDistributionSummary(id2, filteredConfig.merge(defaultHistogramConfig()), scale), NoopDistributionSummary::new); } /** @@ -531,7 +550,7 @@ private Meter getOrCreateMeter(@Nullable DistributionStatisticConfig config, Meter m = meterMap.get(mappedId); if (m == null) { - if(isClosed()) { + if (isClosed()) { return noopBuilder.apply(mappedId); } @@ -723,8 +742,10 @@ public FunctionCounter counter(String name, Iterable tags, T obj, ToDou /** * Tracks a number, maintaining a weak reference on it. * - * @param name Name of the gauge being registered. - * @param tags Sequence of dimensions for breaking down the name. + * @param name Name of the gauge being registered. + * @param tags Sequence of dimensions for breaking down the name. + * @param number A monotonically increasing number to track. + * @param The type of the state object from which the counter value is extracted. * @return A new or existing function counter. */ public FunctionCounter counter(String name, Iterable tags, T number) { @@ -742,7 +763,7 @@ public FunctionCounter counter(String name, Iterable tag */ FunctionCounter counter(Meter.Id id, T obj, ToDoubleFunction countFunction) { return registerMeterIfNecessary(FunctionCounter.class, id, id2 -> newFunctionCounter(id2, obj, countFunction), - NoopFunctionCounter::new); + NoopFunctionCounter::new); } /** @@ -754,6 +775,7 @@ FunctionCounter counter(Meter.Id id, T obj, ToDoubleFunction countFunctio * @param countFunction Function that produces a monotonically increasing counter value from the state object. * @param totalTimeFunction Function that produces a monotonically increasing total time value from the state object. * @param totalTimeFunctionUnit The base unit of time produced by the total time function. + * @param The type of the state object from which the function values are extracted. * @return A new or existing function timer. */ public FunctionTimer timer(String name, Iterable tags, T obj, @@ -761,7 +783,7 @@ public FunctionTimer timer(String name, Iterable tags, T obj, ToDoubleFunction totalTimeFunction, TimeUnit totalTimeFunctionUnit) { return FunctionTimer.builder(name, obj, countFunction, totalTimeFunction, totalTimeFunctionUnit) - .tags(tags).register(MeterRegistry.this); + .tags(tags).register(MeterRegistry.this); } /** @@ -772,6 +794,7 @@ public FunctionTimer timer(String name, Iterable tags, T obj, * @param countFunction Function that produces a monotonically increasing counter value from the state object. * @param totalTimeFunction Function that produces a monotonically increasing total time value from the state object. * @param totalTimeFunctionUnit The base unit of time produced by the total time function. + * @param The type of the state object from which the function values are extracted.F * @return A new or existing function timer. */ FunctionTimer timer(Meter.Id id, T obj, @@ -792,6 +815,7 @@ FunctionTimer timer(Meter.Id id, T obj, * @param obj State object used to compute a value. * @param timeFunctionUnit The base unit of time produced by the total time function. * @param timeFunction Function that produces a time value from the state object. This value may increase and decrease over time. + * @param The type of the state object from which the gauge value is extracted. * @return A new or existing time gauge. */ public TimeGauge timeGauge(String name, Iterable tags, T obj, @@ -806,6 +830,7 @@ public TimeGauge timeGauge(String name, Iterable tags, T obj, * @param obj State object used to compute a value. * @param timeFunctionUnit The base unit of time produced by the total time function. * @param timeFunction Function that produces a time value from the state object. This value may increase and decrease over time. + * @param The type of the state object from which the gauge value is extracted. * @return A new or existing time gauge. */ TimeGauge timeGauge(Meter.Id id, T obj, TimeUnit timeFunctionUnit, ToDoubleFunction timeFunction) { @@ -819,7 +844,7 @@ TimeGauge timeGauge(Meter.Id id, T obj, TimeUnit timeFunctionUnit, ToDoubleF */ @Override public void close() { - if(closed.compareAndSet(false, true)) { + if (closed.compareAndSet(false, true)) { synchronized (meterMapLock) { for (Meter meter : meterMap.values()) { meter.close(); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/Metrics.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/Metrics.java index a71a7e746c..40bcc4213a 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/Metrics.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/Metrics.java @@ -144,6 +144,7 @@ public static More more() { * @param tags Sequence of dimensions for breaking down the name. * @param obj Object used to compute a value. * @param valueFunction Function that is applied on the value for the number. + * @param The type of the state object from which the gauge value is extracted. * @return The number that was passed in so the registration can be done as part of an assignment * statement. */ @@ -158,6 +159,7 @@ public static T gauge(String name, Iterable tags, T obj, ToDoubleFuncti * @param name Name of the gauge being registered. * @param tags Sequence of dimensions for breaking down the name. * @param number Thread-safe implementation of {@link Number} used to access the value. + * @param The type of the state object from which the gauge value is extracted. * @return The number that was passed in so the registration can be done as part of an assignment * statement. */ @@ -171,6 +173,7 @@ public static T gauge(String name, Iterable tags, T numb * * @param name Name of the gauge being registered. * @param number Thread-safe implementation of {@link Number} used to access the value. + * @param The type of the state object from which the gauge value is extracted. * @return The number that was passed in so the registration can be done as part of an assignment * statement. */ @@ -185,6 +188,7 @@ public static T gauge(String name, T number) { * @param name Name of the gauge being registered. * @param obj Object used to compute a value. * @param valueFunction Function that is applied on the value for the number. + * @param The type of the state object from which the gauge value is extracted.F * @return The number that was passed in so the registration can be done as part of an assignment * statement. */ @@ -203,6 +207,7 @@ public static T gauge(String name, T obj, ToDoubleFunction valueFunction) * @param name Name of the gauge being registered. * @param tags Sequence of dimensions for breaking down the name. * @param collection Thread-safe implementation of {@link Collection} used to access the value. + * @param The type of the state object from which the gauge value is extracted. * @return The number that was passed in so the registration can be done as part of an assignment * statement. */ @@ -221,6 +226,7 @@ public static > T gaugeCollectionSize(String name, Itera * @param name Name of the gauge being registered. * @param tags Sequence of dimensions for breaking down the name. * @param map Thread-safe implementation of {@link Map} used to access the value. + * @param The type of the state object from which the gauge value is extracted. * @return The number that was passed in so the registration can be done as part of an assignment * statement. */ @@ -273,8 +279,10 @@ public FunctionCounter counter(String name, Iterable tags, T obj, ToDou /** * Tracks a number, maintaining a weak reference on it. * - * @param name Name of the gauge being registered. - * @param tags Sequence of dimensions for breaking down the name. + * @param name Name of the gauge being registered. + * @param tags Sequence of dimensions for breaking down the name. + * @param number A monotonically increasing number to track. + * @param The type of the state object from which the counter value is extracted. * @return A new or existing function counter. */ public FunctionCounter counter(String name, Iterable tags, T number) { @@ -289,6 +297,7 @@ public FunctionCounter counter(String name, Iterable tag * @param obj State object used to compute a value. * @param timeFunctionUnit The base unit of time produced by the total time function. * @param timeFunction Function that produces a time value from the state object. This value may increase and decrease over time. + * @param The type of the state object from which the gauge value is extracted. * @return A new or existing time gauge. */ public TimeGauge timeGauge(String name, Iterable tags, T obj, TimeUnit timeFunctionUnit, ToDoubleFunction timeFunction) { @@ -304,6 +313,7 @@ public TimeGauge timeGauge(String name, Iterable tags, T obj, TimeUnit * @param countFunction Function that produces a monotonically increasing counter value from the state object. * @param totalTimeFunction Function that produces a monotonically increasing total time value from the state object. * @param totalTimeFunctionUnit The base unit of time produced by the total time function. + * @param The type of the state object from which the function values are extracted. * @return A new or existing function timer. */ public FunctionTimer timer(String name, Iterable tags, T obj, diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/TimeGauge.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/TimeGauge.java index 784918ae67..58954a94fa 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/TimeGauge.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/TimeGauge.java @@ -24,6 +24,8 @@ import java.util.function.ToDoubleFunction; /** + * A specialized gauge that tracks a time value, to be scaled to the base unit of time expected by each registry implementation. + * * @author Jon Schneider */ public interface TimeGauge extends Gauge { @@ -31,8 +33,18 @@ static Builder builder(String name, T obj, TimeUnit fUnits, ToDoubleFunct return new Builder<>(name, obj, fUnits, f); } + /** + * @return The base time unit of the timer to which all published metrics will be scaled + */ TimeUnit baseTimeUnit(); + /** + * The act of observing the value by calling this method triggers sampling + * of the underlying number or user-defined function that defines the value for the gauge. + * + * @param unit The base unit of time to scale the value to. + * @return The current value, scaled to the appropriate base unit. + */ default double value(TimeUnit unit) { return TimeUtils.convert(value(), baseTimeUnit(), unit); } @@ -59,7 +71,7 @@ private Builder(String name, T obj, TimeUnit fUnits, ToDoubleFunction f) { /** * @param tags Must be an even number of arguments representing key/value pairs of tags. - * @return + * @return This builder. */ public Builder tags(String... tags) { return tags(Tags.of(tags)); @@ -75,7 +87,7 @@ public Builder tags(Iterable tags) { } /** - * @param key The tag key. + * @param key The tag key. * @param value The tag value. * @return The time gauge builder with a single added tag. */ @@ -103,7 +115,7 @@ public Builder description(@Nullable String description) { */ public TimeGauge register(MeterRegistry registry) { return registry.more().timeGauge(new Meter.Id(name, tags, null, description, Type.GAUGE), - obj, fUnits, f); + obj, fUnits, f); } } } diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/Timer.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/Timer.java index def3d07fad..cdb24abbb6 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/Timer.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/Timer.java @@ -16,6 +16,7 @@ package io.micrometer.core.instrument; import io.micrometer.core.annotation.Timed; +import io.micrometer.core.instrument.distribution.CountAtBucket; import io.micrometer.core.instrument.distribution.DistributionStatisticConfig; import io.micrometer.core.instrument.distribution.HistogramSnapshot; import io.micrometer.core.instrument.distribution.pause.PauseDetector; @@ -52,6 +53,7 @@ static Builder builder(String name) { * * @param timed The annotation instance to base a new timer on. * @param defaultName A default name to use in the event that the value attribute is empty. + * @return This builder. */ static Builder builder(Timed timed, String defaultName) { if (timed.longTask() && timed.value().isEmpty()) { @@ -61,10 +63,10 @@ static Builder builder(Timed timed, String defaultName) { } return new Builder(timed.value().isEmpty() ? defaultName : timed.value()) - .tags(timed.extraTags()) - .description(timed.description().isEmpty() ? null : timed.description()) - .publishPercentileHistogram(timed.histogram()) - .publishPercentiles(timed.percentiles().length > 0 ? timed.percentiles() : null); + .tags(timed.extraTags()) + .description(timed.description().isEmpty() ? null : timed.description()) + .publishPercentileHistogram(timed.histogram()) + .publishPercentiles(timed.percentiles().length > 0 ? timed.percentiles() : null); } /** @@ -88,7 +90,8 @@ default void record(Duration duration) { /** * Executes the Supplier `f` and records the time taken. * - * @param f Function to execute and measure the execution time. + * @param f Function to execute and measure the execution time. + * @param The return type of the {@link Supplier}. * @return The return value of `f`. */ T record(Supplier f); @@ -96,8 +99,10 @@ default void record(Duration duration) { /** * Executes the callable `f` and records the time taken. * - * @param f Function to execute and measure the execution time. + * @param f Function to execute and measure the execution time. + * @param The return type of the {@link Callable}. * @return The return value of `f`. + * @throws Exception Any exception bubbling up from the callable. */ T recordCallable(Callable f) throws Exception; @@ -121,52 +126,83 @@ default Runnable wrap(Runnable f) { /** * Wrap a {@link Callable} so that it is timed when invoked. * - * @param f The Callable to time when it is invoked. - * @return The wrapped Callable. + * @param f The Callable to time when it is invoked. + * @param The return type of the callable. + * @return The wrapped callable. */ default Callable wrap(Callable f) { return () -> recordCallable(f); } /** - * The number of times that stop has been called on this timer. + * @return The number of times that stop has been called on this timer. */ long count(); /** - * The total time of recorded events. + * @param unit The base unit of time to scale the total to. + * @return The total time of recorded events. */ double totalTime(TimeUnit unit); + /** + * @param unit The base unit of time to scale the mean to. + * @return The distribution average for all recorded events. + */ default double mean(TimeUnit unit) { return count() == 0 ? 0 : totalTime(unit) / count(); } /** - * The maximum time of a single event. + * @param unit The base unit of time to scale the max to. + * @return The maximum time of a single event. */ double max(TimeUnit unit); /** - * The latency at a specific percentile. This value is non-aggregable across dimensions. + * @param percentile A percentile in the domain [0, 1]. For example, 0.5 represents the 50th percentile of the + * distribution. + * @param unit The base unit of time to scale the percentile value to. + * @return The latency at a specific percentile. This value is non-aggregable across dimensions. */ double percentile(double percentile, TimeUnit unit); + /** + * Provides cumulative histogram counts. + * + * @param valueNanos The histogram bucket to retrieve a count for. + * @return The count of all events less than or equal to the bucket. + */ double histogramCountAtValue(long valueNanos); + /** + * Summary statistics should be published off of a single snapshot instance so that, for example, there isn't + * disagreement between the distribution's count and total because more events continue to stream in. + * + * @param supportsAggregablePercentiles Whether percentile histogram buckets should be included in the list of {@link CountAtBucket}. + * @return A snapshot of all distribution statistics at a point in time. + */ HistogramSnapshot takeSnapshot(boolean supportsAggregablePercentiles); @Override default Iterable measure() { return Arrays.asList( - new Measurement(() -> (double) count(), Statistic.COUNT), - new Measurement(() -> totalTime(baseTimeUnit()), Statistic.TOTAL_TIME), - new Measurement(() -> max(baseTimeUnit()), Statistic.MAX) + new Measurement(() -> (double) count(), Statistic.COUNT), + new Measurement(() -> totalTime(baseTimeUnit()), Statistic.TOTAL_TIME), + new Measurement(() -> max(baseTimeUnit()), Statistic.MAX) ); } + /** + * @return The base time unit of the timer to which all published metrics will be scaled + */ TimeUnit baseTimeUnit(); + /** + * Maintains state on the clock's start position for a latency sample. Complete the timing + * by calling {@link Sample#stop(Timer)}. Note how the {@link Timer} isn't provided until the + * sample is stopped, allowing you to determine the timer's tags at the last minute. + */ class Sample { private final long startTime; private final Clock clock; @@ -179,6 +215,7 @@ class Sample { /** * Records the duration of the operation * + * @param timer The timer to record the sample to. * @return The total duration of the sample in nanoseconds */ public long stop(Timer timer) { @@ -211,6 +248,7 @@ private Builder(String name) { /** * @param tags Must be an even number of arguments representing key/value pairs of tags. + * @return This builder. */ public Builder tags(String... tags) { return tags(Tags.of(tags)); @@ -228,7 +266,7 @@ public Builder tags(Iterable tags) { /** * @param key The tag key. * @param value The tag value. - * @return The timer builder with a single added tag. + * @return This builder. */ public Builder tag(String key, String value) { tags.add(Tag.of(key, value)); @@ -242,6 +280,7 @@ public Builder tag(String key, String value) { * to publish a histogram that can be used to generate aggregable percentile approximations. * * @param percentiles Percentiles to compute and publish. The 95th percentile should be expressed as {@code 0.95}. + * @return This builder. */ public Builder publishPercentiles(@Nullable double... percentiles) { this.distributionConfigBuilder.percentiles(percentiles); @@ -252,6 +291,8 @@ public Builder publishPercentiles(@Nullable double... percentiles) { * Adds histogram buckets used to generate aggregable percentile approximations in monitoring * systems that have query facilities to do so (e.g. Prometheus' {@code histogram_quantile}, * Atlas' {@code :percentiles}). + * + * @return This builder. */ public Builder publishPercentileHistogram() { return publishPercentileHistogram(true); @@ -261,6 +302,9 @@ public Builder publishPercentileHistogram() { * Adds histogram buckets used to generate aggregable percentile approximations in monitoring * systems that have query facilities to do so (e.g. Prometheus' {@code histogram_quantile}, * Atlas' {@code :percentiles}). + * + * @param enabled Determines whether percentile histograms should be published. + * @return This builder. */ public Builder publishPercentileHistogram(@Nullable Boolean enabled) { this.distributionConfigBuilder.percentilesHistogram(enabled); @@ -273,6 +317,7 @@ public Builder publishPercentileHistogram(@Nullable Boolean enabled) { * other buckets used to generate aggregable percentile approximations. * * @param sla Publish SLA boundaries in the set of histogram buckets shipped to the monitoring system. + * @return This builder. */ public Builder sla(@Nullable Duration... sla) { if (sla != null) { @@ -355,7 +400,7 @@ public Builder pauseDetector(@Nullable PauseDetector pauseDetector) { /** * @param description Description text of the eventual timer. - * @return The timer builder with added description. + * @return This builder. */ public Builder description(@Nullable String description) { this.description = description; @@ -373,7 +418,7 @@ public Builder description(@Nullable String description) { public Timer register(MeterRegistry registry) { // the base unit for a timer will be determined by the monitoring system implementation return registry.timer(new Meter.Id(name, tags, null, description, Type.TIMER), distributionConfigBuilder.build(), - pauseDetector == null ? registry.config().pauseDetector() : pauseDetector); + pauseDetector == null ? registry.config().pauseDetector() : pauseDetector); } } } diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CacheMeterBinder.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CacheMeterBinder.java index d0f74b5ee1..91f15dc067 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CacheMeterBinder.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CacheMeterBinder.java @@ -73,7 +73,7 @@ public final void bindTo(MeterRegistry registry) { .description("The number of entries added to the cache") .register(registry); - if(evictionCount() != null) { + if (evictionCount() != null) { FunctionCounter.builder("cache.evictions", cache.get(), c -> { Long evictions = evictionCount(); @@ -126,6 +126,8 @@ public final void bindTo(MeterRegistry registry) { * Bind detailed metrics that are particular to the cache implementation, e.g. load duration for * Caffeine caches, heap and disk size for EhCache caches. These metrics are above and beyond the * basic set of metrics that is common to all caches. + * + * @param registry The registry to bind metrics to. */ protected abstract void bindImplementationSpecificMetrics(MeterRegistry registry); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetrics.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetrics.java index 500d9bd5c4..6dba6fe474 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetrics.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/CaffeineCacheMetrics.java @@ -64,6 +64,7 @@ public CaffeineCacheMetrics(Cache cache, String cacheName, Iterable t * @param cache The cache to instrument. * @param cacheName Will be used to tag metrics with "cache". * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param The cache type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. */ public static C monitor(MeterRegistry registry, C cache, String cacheName, String... tags) { @@ -78,6 +79,7 @@ public static C monitor(MeterRegistry registry, C cache, Strin * @param cache The cache to instrument. * @param cacheName Will be used to tag metrics with "cache". * @param tags Tags to apply to all recorded metrics. + * @param The cache type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see CacheStats */ @@ -94,6 +96,7 @@ public static C monitor(MeterRegistry registry, C cache, Strin * @param cache The cache to instrument. * @param cacheName Will be used to tag metrics with "cache". * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param The cache type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. */ public static C monitor(MeterRegistry registry, C cache, String cacheName, String... tags) { @@ -108,6 +111,7 @@ public static C monitor(MeterRegistry registry, C * @param cache The cache to instrument. * @param cacheName Will be used to tag metrics with "cache". * @param tags Tags to apply to all recorded metrics. + * @param The cache type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see CacheStats */ diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetrics.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetrics.java index cb9343b88a..2796b74ca7 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetrics.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/GuavaCacheMetrics.java @@ -40,6 +40,7 @@ public class GuavaCacheMetrics extends CacheMeterBinder { * @param cache The cache to instrument. * @param cacheName Will be used to tag metrics with "cache". * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param The cache type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see com.google.common.cache.CacheStats */ @@ -55,6 +56,7 @@ public static C monitor(MeterRegistry registry, C cache, Strin * @param cache The cache to instrument. * @param cacheName The name prefix of the metrics. * @param tags Tags to apply to all recorded metrics. + * @param The cache type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see com.google.common.cache.CacheStats */ diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetrics.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetrics.java index ba0e89b959..dcc5b29e15 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetrics.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/HazelcastCacheMetrics.java @@ -37,9 +37,12 @@ public class HazelcastCacheMetrics extends CacheMeterBinder { /** * Record metrics on a Hazelcast cache. * - * @param registry The registry to bind metrics to. - * @param cache The cache to instrument. - * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param registry The registry to bind metrics to. + * @param cache The cache to instrument. + * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param The cache type. + * @param The cache key type. + * @param The cache value type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see com.google.common.cache.CacheStats */ @@ -50,9 +53,12 @@ public static > C monitor(MeterRegistry registry, C c /** * Record metrics on a Hazelcast cache. * - * @param registry The registry to bind metrics to. - * @param cache The cache to instrument. - * @param tags Tags to apply to all recorded metrics. + * @param registry The registry to bind metrics to. + * @param cache The cache to instrument. + * @param tags Tags to apply to all recorded metrics. + * @param The cache type. + * @param The cache key type. + * @param The cache value type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see com.google.common.cache.CacheStats */ diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/JCacheMetrics.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/JCacheMetrics.java index e1c744bb1e..01351e3a1f 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/JCacheMetrics.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/cache/JCacheMetrics.java @@ -30,7 +30,7 @@ /** * Collect metrics on JSR-107 JCache caches, including detailed metrics on manual puts and removals. * See https://github.com/jsr107/demo/blob/master/src/test/java/javax/cache/core/StatisticsExample.java - * + *

* Note that JSR-107 does not provide any insight into the size or estimated size of the cache, so * the size metric of a JCache cache will always report 0. * @@ -44,9 +44,12 @@ public class JCacheMetrics extends CacheMeterBinder { /** * Record metrics on a JCache cache. * - * @param registry The registry to bind metrics to. - * @param cache The cache to instrument. - * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param registry The registry to bind metrics to. + * @param cache The cache to instrument. + * @param tags Tags to apply to all recorded metrics. Must be an even number of arguments representing key/value pairs of tags. + * @param The cache type. + * @param The cache key type. + * @param The cache value type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see com.google.common.cache.CacheStats */ @@ -57,9 +60,12 @@ public static > C monitor(MeterRegistry registry, C /** * Record metrics on a JCache cache. * - * @param registry The registry to bind metrics to. - * @param cache The cache to instrument. - * @param tags Tags to apply to all recorded metrics. + * @param registry The registry to bind metrics to. + * @param cache The cache to instrument. + * @param tags Tags to apply to all recorded metrics. + * @param The cache type. + * @param The cache key type. + * @param The cache value type. * @return The instrumented cache, unchanged. The original cache is not wrapped or proxied in any way. * @see com.google.common.cache.CacheStats */ diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetrics.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetrics.java deleted file mode 100644 index d029939565..0000000000 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetrics.java +++ /dev/null @@ -1,56 +0,0 @@ -/** - * Copyright 2017 Pivotal Software, Inc. - *

- * 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.micrometer.core.instrument.binder.reactor; - -import io.micrometer.core.instrument.Tag; -import io.micrometer.core.instrument.Tags; -import org.reactivestreams.Publisher; -import reactor.core.Fuseable; -import reactor.core.Scannable; -import reactor.core.publisher.Operators; - -import java.util.function.Function; -import java.util.function.Predicate; - -import static java.util.stream.Collectors.toList; - -/** - * @author Jon Schneider - */ -public class ReactorMetrics { - private static final Predicate POINTCUT_FILTER = - s -> !(s instanceof Fuseable.ScalarCallable); - - private ReactorMetrics() { - } - - /** - * @param an arbitrary type that is left unchanged by the metrics operator - * @return a new metrics-recording operator pointcut - */ - public static Function, ? extends Publisher> timed(Iterable tags) { - return Operators.lift(POINTCUT_FILTER, ((scannable, sub) -> { - //do not time fused flows - if (scannable instanceof Fuseable && sub instanceof Fuseable.QueueSubscription) { - return sub; - } - return new ReactorMetricsSubscriber<>( - scannable.name(), - Tags.concat(tags, scannable.tags().map(t -> Tag.of(t.getT1(), t.getT2())).collect(toList())) - ); - })); - } -} \ No newline at end of file diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetricsSubscriber.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetricsSubscriber.java deleted file mode 100644 index 137592a09d..0000000000 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/reactor/ReactorMetricsSubscriber.java +++ /dev/null @@ -1,62 +0,0 @@ -/** - * Copyright 2017 Pivotal Software, Inc. - *

- * 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.micrometer.core.instrument.binder.reactor; - -import io.micrometer.core.instrument.Tag; -import org.reactivestreams.Subscription; -import reactor.core.CoreSubscriber; - -import java.util.concurrent.atomic.AtomicBoolean; - -public class ReactorMetricsSubscriber extends AtomicBoolean implements Subscription, CoreSubscriber { - private final String name; - private final Iterable tags; - - public ReactorMetricsSubscriber(String name, Iterable tags) { - this.name = name; - this.tags = tags; - } - - @Override - public void onNext(T t) { - - } - - @Override - public void onError(Throwable t) { - - } - - @Override - public void onComplete() { - - } - - @Override - public void request(long n) { - - } - - @Override - public void cancel() { - - } - - @Override - public void onSubscribe(Subscription s) { - - } -} diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/composite/CompositeMeterRegistry.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/composite/CompositeMeterRegistry.java index c1de3d8bd8..d5a5464724 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/composite/CompositeMeterRegistry.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/composite/CompositeMeterRegistry.java @@ -90,8 +90,8 @@ protected FunctionTimer newFunctionTimer(Meter.Id id, T obj, ToLongFunction< } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { - return new CompositeFunctionCounter<>(id, obj, valueFunction); + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { + return new CompositeFunctionCounter<>(id, obj, countFunction); } @Override diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/config/MeterFilter.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/config/MeterFilter.java index 384d6429c1..298660b2c4 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/config/MeterFilter.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/config/MeterFilter.java @@ -116,6 +116,7 @@ public Meter.Id map(Meter.Id id) { * @param tagKey The tag key for which replacements should be made * @param replacement The value to replace with * @param exceptions All a matching tag with this value to retain its original value + * @return A filter that replaces tag values. * @author Clint Checketts */ static MeterFilter replaceTagValues(String tagKey, Function replacement, String... exceptions) { @@ -143,6 +144,7 @@ public Meter.Id map(Meter.Id id) { * Can be used to build a whitelist of metrics matching certain criteria. Opposite of {@link #deny(Predicate)}. * * @param iff When a meter id matches, allow its inclusion, otherwise deny. + * @return A meter filter that whitelists metrics matching a predicate. */ static MeterFilter denyUnless(Predicate iff) { return new MeterFilter() { @@ -213,6 +215,7 @@ static MeterFilter deny() { * it can effectively cap your risk of an accidentally high-cardiality metric costing too much. * * @param maximumTimeSeries The total number of unique name/tag permutations allowed before filtering kicks in. + * @return A filter that globally limits the number of unique name and tag combinations. */ static MeterFilter maximumAllowableMetrics(int maximumTimeSeries) { return new MeterFilter() { @@ -374,6 +377,7 @@ default MeterFilterReply accept(Meter.Id id) { } /** + * @param id Id to transform. * @return Transformations to any part of the id. */ default Meter.Id map(Meter.Id id) { diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/cumulative/CumulativeTimer.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/cumulative/CumulativeTimer.java index edb8879a2e..a46497f01d 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/cumulative/CumulativeTimer.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/cumulative/CumulativeTimer.java @@ -33,9 +33,6 @@ public class CumulativeTimer extends AbstractTimer { private final AtomicLong total; private final TimeDecayingMax max; - /** - * Create a new instance. - */ public CumulativeTimer(Id id, Clock clock, DistributionStatisticConfig distributionStatisticConfig, PauseDetector pauseDetector, TimeUnit baseTimeUnit) { super(id, clock, distributionStatisticConfig, pauseDetector, baseTimeUnit); this.count = new AtomicLong(); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/distribution/PercentileHistogramBuckets.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/distribution/PercentileHistogramBuckets.java index 34f3785eb7..3d86a7afd9 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/distribution/PercentileHistogramBuckets.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/distribution/PercentileHistogramBuckets.java @@ -70,9 +70,13 @@ public class PercentileHistogramBuckets { * Pick values from a static set of percentile buckets that yields a decent error bound on most real world * timers and distribution summaries because monitoring systems like Prometheus require us to report the * same buckets at every interval, regardless of where actual samples have been observed. + * + * @param distributionStatisticConfig A configuration the governs how many buckets to produce based on its minimum + * and maximum expected values.. + * @return The set of histogram buckets for use in computing aggregable percentiles. */ public static NavigableSet buckets(DistributionStatisticConfig distributionStatisticConfig) { return PERCENTILE_BUCKETS.subSet(distributionStatisticConfig.getMinimumExpectedValue(), true, - distributionStatisticConfig.getMaximumExpectedValue(), true); + distributionStatisticConfig.getMaximumExpectedValue(), true); } } diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardConfig.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardConfig.java index 25f9571d08..e263ecea0e 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardConfig.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardConfig.java @@ -19,9 +19,14 @@ import java.time.Duration; +/** + * Base configuration for {@link DropwizardMeterRegistry}. + * + * @author Jon Schneider + */ public interface DropwizardConfig extends MeterRegistryConfig { /** - * Returns the step size (reporting frequency, max decaying) to use. The default is 1 minute. + * @return The step size (reporting frequency, max decaying) to use. The default is 1 minute. */ default Duration step() { String v = get(prefix() + ".step"); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardMeterRegistry.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardMeterRegistry.java index b931046a91..c5479f7776 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardMeterRegistry.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/dropwizard/DropwizardMeterRegistry.java @@ -130,8 +130,8 @@ protected FunctionTimer newFunctionTimer(Meter.Id id, T obj, ToLongFunction< } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { - DropwizardFunctionCounter fc = new DropwizardFunctionCounter<>(id, clock, obj, valueFunction); + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { + DropwizardFunctionCounter fc = new DropwizardFunctionCounter<>(id, clock, obj, countFunction); registry.register(hierarchicalName(id), fc.getDropwizardMeter()); return fc; } diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleConfig.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleConfig.java index 0f48d35d76..b9d9e0e32b 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleConfig.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleConfig.java @@ -19,6 +19,11 @@ import java.time.Duration; +/** + * Configuration for {@link SimpleMeterRegistry}. + * + * @author Jon Schneider + */ public interface SimpleConfig extends MeterRegistryConfig { SimpleConfig DEFAULT = k -> null; @@ -28,13 +33,17 @@ default String prefix() { } /** - * Returns the step size (reporting frequency) to use. The default is 10 seconds. + * @return The step size (reporting frequency) to use. */ default Duration step() { String v = get(prefix() + ".step"); return v == null ? Duration.ofMinutes(1) : Duration.parse(v); } + /** + * @return A mode that determines whether the registry reports cumulative values over all time or + * a rate normalized form representing changes in the last {@link #step()}. + */ default CountingMode mode() { String v = get(prefix() + ".mode"); if (v == null) diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleMeterRegistry.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleMeterRegistry.java index 2b680759c4..6819fe622a 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleMeterRegistry.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/simple/SimpleMeterRegistry.java @@ -148,8 +148,8 @@ protected FunctionTimer newFunctionTimer(Meter.Id id, T obj, ToLongFunction< } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { - return new CumulativeFunctionCounter<>(id, obj, valueFunction); + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { + return new CumulativeFunctionCounter<>(id, obj, countFunction); } @Override diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepCounter.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepCounter.java index fbaba1ddbc..e6600a3df3 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepCounter.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepCounter.java @@ -27,9 +27,6 @@ public class StepCounter extends AbstractMeter implements Counter { private final StepDouble value; - /** - * Create a new instance. - */ public StepCounter(Id id, Clock clock, long stepMillis) { super(id); this.value = new StepDouble(clock, stepMillis); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepDouble.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepDouble.java index 4a5faac73a..520eb46292 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepDouble.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepDouble.java @@ -56,7 +56,7 @@ public DoubleAdder getCurrent() { } /** - * Get the value for the last completed interval. + * @return The value for the last completed interval. */ public double poll() { rollCount(clock.wallTime()); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepLong.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepLong.java index fc01c755f2..fc77cfabd3 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepLong.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepLong.java @@ -50,7 +50,7 @@ public LongAdder getCurrent() { } /** - * Get the value for the last completed interval. + * @return The value for the last completed interval. */ public double poll() { rollCount(clock.wallTime()); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepMeterRegistry.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepMeterRegistry.java index abecda775d..1fdc504383 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepMeterRegistry.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepMeterRegistry.java @@ -138,8 +138,8 @@ protected FunctionTimer newFunctionTimer(Meter.Id id, T obj, ToLongFunction< } @Override - protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction valueFunction) { - return new StepFunctionCounter<>(id, clock, config.step().toMillis(), obj, valueFunction); + protected FunctionCounter newFunctionCounter(Meter.Id id, T obj, ToDoubleFunction countFunction) { + return new StepFunctionCounter<>(id, clock, config.step().toMillis(), obj, countFunction); } @Override diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepRegistryConfig.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepRegistryConfig.java index 0da5454e10..afc011f503 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepRegistryConfig.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepRegistryConfig.java @@ -27,7 +27,7 @@ */ public interface StepRegistryConfig extends MeterRegistryConfig { /** - * Returns the step size (reporting frequency) to use. The default is 10 seconds. + * @return The step size (reporting frequency) to use. The default is 10 seconds. */ default Duration step() { String v = get(prefix() + ".step"); @@ -35,7 +35,7 @@ default Duration step() { } /** - * Returns true if publishing is enabled. Default is {@code true}. + * @return {@code true} if publishing is enabled. Default is {@code true}. */ default boolean enabled() { String v = get(prefix() + ".enabled"); @@ -43,7 +43,7 @@ default boolean enabled() { } /** - * Returns the number of threads to use with the scheduler. The default is + * @return The number of threads to use with the scheduler. The default is * 2 threads. */ default int numThreads() { @@ -52,7 +52,7 @@ default int numThreads() { } /** - * Returns the connection timeout for requests to the backend. The default is + * @return The connection timeout for requests to the backend. The default is * 1 second. */ default Duration connectTimeout() { @@ -61,7 +61,7 @@ default Duration connectTimeout() { } /** - * Returns the read timeout for requests to the backend. The default is + * @return The read timeout for requests to the backend. The default is * 10 seconds. */ default Duration readTimeout() { @@ -70,7 +70,7 @@ default Duration readTimeout() { } /** - * Returns the number of measurements per request to use for the backend. If more + * @return The number of measurements per request to use for the backend. If more * measurements are found, then multiple requests will be made. The default is * 10,000. */ diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepTimer.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepTimer.java index 565ee2b5e7..86d448f5e4 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepTimer.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/step/StepTimer.java @@ -32,9 +32,6 @@ public class StepTimer extends AbstractTimer { private final StepLong total; private final TimeDecayingMax max; - /** - * Create a new instance. - */ @SuppressWarnings("ConstantConditions") public StepTimer(Id id, Clock clock, DistributionStatisticConfig distributionStatisticConfig, PauseDetector pauseDetector, TimeUnit baseTimeUnit) { super(id, clock, distributionStatisticConfig, pauseDetector, baseTimeUnit); diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/util/MathUtils.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/util/MathUtils.java index b3efd9b6fb..d16c5dbf2e 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/util/MathUtils.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/util/MathUtils.java @@ -25,9 +25,7 @@ public final class MathUtils { private MathUtils() { } - /** - * Simplified {@link com.google.common.math.IntMath#divide(int, int, java.math.RoundingMode)}. - */ + // Simplified {@link com.google.common.math.IntMath#divide(int, int, java.math.RoundingMode)}. public static int divideWithCeilingRoundingMode(int p, int q) { if (q == 0) { throw new ArithmeticException("/ by zero"); // for GWT diff --git a/micrometer-core/src/main/java/io/micrometer/core/instrument/util/TimeDecayingMax.java b/micrometer-core/src/main/java/io/micrometer/core/instrument/util/TimeDecayingMax.java index f24d4bbde0..1b9dc50019 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/instrument/util/TimeDecayingMax.java +++ b/micrometer-core/src/main/java/io/micrometer/core/instrument/util/TimeDecayingMax.java @@ -30,7 +30,7 @@ public class TimeDecayingMax { @SuppressWarnings("rawtypes") private static final AtomicIntegerFieldUpdater rotatingUpdater = - AtomicIntegerFieldUpdater.newUpdater(TimeDecayingMax.class, "rotating"); + AtomicIntegerFieldUpdater.newUpdater(TimeDecayingMax.class, "rotating"); private final Clock clock; private final long durationBetweenRotatesMillis; @@ -58,6 +58,12 @@ public TimeDecayingMax(Clock clock, long rotateFrequencyMillis, int bufferLength } } + /** + * For use by timer implementations. + * + * @param sample The value to record. + * @param timeUnit The unit of time of the incoming sample. + */ public void record(double sample, TimeUnit timeUnit) { rotate(); final long sampleNanos = (long) TimeUtils.convert(sample, timeUnit, TimeUnit.NANOSECONDS); @@ -66,6 +72,10 @@ public void record(double sample, TimeUnit timeUnit) { } } + /** + * @param timeUnit The base unit of time to scale the max to. + * @return A max scaled to the base unit of time. For use by timer implementations. + */ public double poll(TimeUnit timeUnit) { rotate(); synchronized (this) { @@ -74,7 +84,7 @@ public double poll(TimeUnit timeUnit) { } /** - * Return an unscaled max. For use by distribution summary implementations. + * @return An unscaled max. For use by distribution summary implementations. */ public double poll() { rotate(); @@ -85,6 +95,8 @@ public double poll() { /** * For use by distribution summary implementations. + * + * @param sample The value to record. */ public void record(double sample) { rotate(); diff --git a/micrometer-core/src/main/java/io/micrometer/core/lang/NonNull.java b/micrometer-core/src/main/java/io/micrometer/core/lang/NonNull.java index 8b32cded88..0433c0064e 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/lang/NonNull.java +++ b/micrometer-core/src/main/java/io/micrometer/core/lang/NonNull.java @@ -23,10 +23,8 @@ * A common annotation to declare that annotated elements cannot be {@code null}. * Leverages JSR 305 meta-annotations to indicate nullability in Java to common tools with * JSR 305 support and used by Kotlin to infer nullability of the API. - *

*

Should be used at parameter, return value, and field level. Method overrides should * repeat parent {@code @NonNull} annotations unless they behave differently. - *

*

Use {@code @NonNullApi} (scope = parameters + return values) and/or {@code @NonNullFields} * (scope = fields) to set the default behavior to non-nullable in order to avoid annotating * your whole codebase with {@code @NonNull}. diff --git a/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullApi.java b/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullApi.java index ed07c7aa0c..99d00850a8 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullApi.java +++ b/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullApi.java @@ -22,10 +22,8 @@ /** * A common annotation to declare that parameters and return values * are to be considered as non-nullable by default for a given package. - *

*

Leverages JSR-305 meta-annotations to indicate nullability in Java to common * tools with JSR-305 support and used by Kotlin to infer nullability of the API. - *

*

Should be used at package level in association with {@link Nullable} * annotations at parameter and return value level. * diff --git a/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullFields.java b/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullFields.java index 1e4e6d40be..7fd7ae5dbb 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullFields.java +++ b/micrometer-core/src/main/java/io/micrometer/core/lang/NonNullFields.java @@ -22,10 +22,8 @@ /** * A common annotation to declare that fields are to be considered as * non-nullable by default for a given package. - *

*

Leverages JSR-305 meta-annotations to indicate nullability in Java to common * tools with JSR-305 support and used by Kotlin to infer nullability of the API. - *

*

Should be used at package level in association with {@link Nullable} * annotations at field level. * diff --git a/micrometer-core/src/main/java/io/micrometer/core/lang/Nullable.java b/micrometer-core/src/main/java/io/micrometer/core/lang/Nullable.java index b7f6df3ad5..9fa58dcfa7 100644 --- a/micrometer-core/src/main/java/io/micrometer/core/lang/Nullable.java +++ b/micrometer-core/src/main/java/io/micrometer/core/lang/Nullable.java @@ -24,10 +24,8 @@ * A common annotation to declare that annotated elements can be {@code null} under * some circumstance. Leverages JSR 305 meta-annotations to indicate nullability in Java * to common tools with JSR 305 support and used by Kotlin to infer nullability of the API. - *

*

Should be used at parameter, return value, and field level. Methods override should * repeat parent {@code @Nullable} annotations unless they behave differently. - *

*

Can be used in association with {@code NonNullApi} or {@code @NonNullFields} to * override the default non-nullable semantic to nullable. * diff --git a/micrometer-jersey2/src/main/java/io/micrometer/jersey2/server/AnnotationFinder.java b/micrometer-jersey2/src/main/java/io/micrometer/jersey2/server/AnnotationFinder.java index 259bedf5d0..8d845df2d6 100644 --- a/micrometer-jersey2/src/main/java/io/micrometer/jersey2/server/AnnotationFinder.java +++ b/micrometer-jersey2/src/main/java/io/micrometer/jersey2/server/AnnotationFinder.java @@ -19,16 +19,17 @@ import java.lang.reflect.AnnotatedElement; public interface AnnotationFinder { - AnnotationFinder DEFAULT = new AnnotationFinder() {}; + AnnotationFinder DEFAULT = new AnnotationFinder() { + }; /** * The default implementation performs a simple search for a declared annotation matching the search type. * Spring provides a more sophisticated annotation search utility that matches on meta-annotations as well. * * @param annotatedElement The element to search. - * @param annotationType The annotation type class. - * @param Annotation type to search for. - * @return + * @param annotationType The annotation type class. + * @param Annotation type to search for. + * @return A matching annotation. */ @SuppressWarnings("unchecked") default A findAnnotation(AnnotatedElement annotatedElement, Class annotationType) { diff --git a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/MetricsAutoConfiguration.java b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/MetricsAutoConfiguration.java index 8c4de95848..6acdabf3b9 100644 --- a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/MetricsAutoConfiguration.java +++ b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/MetricsAutoConfiguration.java @@ -85,9 +85,7 @@ public MeterRegistryCustomizer propertyBasedFilter(MetricsPropert return r -> r.config().meterFilter(new PropertiesMeterFilter(props)); } - /** - * If AOP is not enabled, scheduled interception will not work. - */ + // If AOP is not enabled, scheduled interception will not work. @Bean @ConditionalOnClass(name = "org.aspectj.lang.ProceedingJoinPoint") @ConditionalOnProperty(value = "spring.aop.enabled", havingValue = "true", matchIfMissing = true) diff --git a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/export/simple/SimpleMetricsExportAutoConfiguration.java b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/export/simple/SimpleMetricsExportAutoConfiguration.java index 60e81532f9..40da2947a4 100644 --- a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/export/simple/SimpleMetricsExportAutoConfiguration.java +++ b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/export/simple/SimpleMetricsExportAutoConfiguration.java @@ -53,11 +53,6 @@ public SimpleConfig simpleRegistryConfig(SimpleProperties props) { return new SimplePropertiesConfigAdapter(props); } - /** - * Since {@link SimpleMeterRegistry} is an in-memory metrics store that doesn't publish anywhere, - * it is only configured when a real monitoring system implementation is not present. In this case, - * it backs the metrics displayed in the metrics actuator endpoint. - */ @Bean @ConditionalOnMissingBean(MeterRegistry.class) public SimpleMeterRegistry simpleMeterRegistry(SimpleConfig config, Clock clock) { diff --git a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/web/servlet/ServletMetricsConfiguration.java b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/web/servlet/ServletMetricsConfiguration.java index 14c4acff57..5cf0656481 100644 --- a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/web/servlet/ServletMetricsConfiguration.java +++ b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/autoconfigure/web/servlet/ServletMetricsConfiguration.java @@ -47,13 +47,14 @@ public DefaultWebMvcTagsProvider servletTagsProvider() { return new DefaultWebMvcTagsProvider(); } + @SuppressWarnings("deprecation") @Bean public WebMvcMetricsFilter webMetricsFilter(MeterRegistry registry, MetricsProperties properties, WebMvcTagsProvider tagsProvider, WebApplicationContext ctx) { return new WebMvcMetricsFilter(registry, tagsProvider, - properties.getWeb().getServer().getRequestsMetricName(), - properties.getWeb().getServer().isAutoTimeRequests(), - new HandlerMappingIntrospector(ctx)); + properties.getWeb().getServer().getRequestsMetricName(), + properties.getWeb().getServer().isAutoTimeRequests(), + new HandlerMappingIntrospector(ctx)); } } diff --git a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/web/servlet/WebMvcTags.java b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/web/servlet/WebMvcTags.java index e165521c36..8eebf73120 100644 --- a/micrometer-spring-legacy/src/main/java/io/micrometer/spring/web/servlet/WebMvcTags.java +++ b/micrometer-spring-legacy/src/main/java/io/micrometer/spring/web/servlet/WebMvcTags.java @@ -47,8 +47,8 @@ private WebMvcTags() { */ public static Tag method(@Nullable HttpServletRequest request) { return request == null ? - Tag.of("method", "UNKNOWN") : - Tag.of("method", request.getMethod()); + Tag.of("method", "UNKNOWN") : + Tag.of("method", request.getMethod()); } /** @@ -67,7 +67,8 @@ public static Tag status(@Nullable HttpServletResponse response) { * available, falling back to the request's {@link HttpServletRequest#getPathInfo() * path info} if necessary. * - * @param request the request + * @param request the request + * @param response the response * @return the uri tag derived from the request */ public static Tag uri(@Nullable HttpServletRequest request, @Nullable HttpServletResponse response) { @@ -88,7 +89,7 @@ public static Tag uri(@Nullable HttpServletRequest request, @Nullable HttpServle } String uri = (String) request - .getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE); + .getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE); if (uri == null) { uri = request.getPathInfo(); } @@ -109,7 +110,7 @@ public static Tag uri(@Nullable HttpServletRequest request, @Nullable HttpServle */ public static Tag exception(@Nullable Throwable exception) { return exception == null ? - Tag.of("exception", "None") : - Tag.of("exception", exception.getClass().getSimpleName()); + Tag.of("exception", "None") : + Tag.of("exception", exception.getClass().getSimpleName()); } } diff --git a/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/FunctionTimerSample.java b/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/FunctionTimerSample.java index 9f201a584f..a980ac790f 100644 --- a/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/FunctionTimerSample.java +++ b/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/FunctionTimerSample.java @@ -31,9 +31,7 @@ import java.util.concurrent.atomic.AtomicLong; public class FunctionTimerSample { - /** - * For Atlas: http://localhost:7101/api/v1/graph?q=name,ftimer,:eq,:dist-avg,name,timer,:eq,:dist-avg,1,:axis&s=e-5m&l=0 - */ + // For Atlas: http://localhost:7101/api/v1/graph?q=name,ftimer,:eq,:dist-avg,name,timer,:eq,:dist-avg,1,:axis&s=e-5m&l=0 public static void main(String[] args) { MeterRegistry registry = SampleConfig.myMonitoringSystem(); diff --git a/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleConfig.java b/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleConfig.java index 913c5c3364..e0c7178611 100644 --- a/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleConfig.java +++ b/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleConfig.java @@ -22,13 +22,6 @@ public class SampleConfig { public static MeterRegistry myMonitoringSystem() { // Pick a monitoring system here to use in your samples. - return SampleRegistries.wavefrontDirect("a6f74e29-7577-4b72-bef8-578f6053e908"); -// return SampleRegistries.graphite(); -// return SampleRegistries.signalFx("XNWd8jM0YiDPrroW3Ph0dw"); -// return SampleRegistries.jmx(); -// return SampleRegistries.jmx(); -// return SampleRegistries.prometheus(); -// return SampleRegistries.datadog("26ec541df8f1181b0bdc1bf51fde7cb2", "3288f53fc89a5cac3fb83e725f051f09fd6aba2e"); -// return SampleRegistries.newRelic("1799539", "1jyWDmrk5kswb-RBuLrhYkKQbBrn9_1Q"); + return SampleRegistries.prometheus(); } } diff --git a/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleRegistries.java b/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleRegistries.java index 8bf085bb25..c7a9f3f513 100644 --- a/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleRegistries.java +++ b/samples/micrometer-samples-core/src/main/java/io/micrometer/core/samples/utils/SampleRegistries.java @@ -56,7 +56,8 @@ public static MeterRegistry pickOne() { /** * To use pushgateway instead: * new PushGateway("localhost:9091").pushAdd(registry.getPrometheusRegistry(), "samples"); - * @return + * + * @return A prometheus registry. */ public static PrometheusMeterRegistry prometheus() { PrometheusMeterRegistry prometheusRegistry = new PrometheusMeterRegistry(new PrometheusConfig() {