Improve javadoc

Signed-off-by: Fabio Di Fabio <[email protected]>

metrics/core/src/main/java/org/hyperledger/besu/metrics/noop/NoOpMetricsSystem.java

@@ -123,7 +123,7 @@ public LabelledMetric<OperationTimer> createLabelledTimer(
    */
   public static LabelledMetric<OperationTimer> getOperationTimerLabelledMetric(
       final int labelCount) {
-      return new LabelCountingNoOpMetric<>(labelCount, NO_OP_OPERATION_TIMER);
+    return new LabelCountingNoOpMetric<>(labelCount, NO_OP_OPERATION_TIMER);
   }
 
   @Override
@@ -162,7 +162,7 @@ public LabelledSuppliedMetric createLabelledSuppliedGauge(
    * @return the labelled gauge
    */
   public static LabelledSuppliedMetric getLabelledSuppliedMetric(final int labelCount) {
-      return new LabelledSuppliedNoOpMetric(labelCount);
+    return new LabelledSuppliedNoOpMetric(labelCount);
   }
 
   /**
@@ -172,7 +172,7 @@ public static LabelledSuppliedMetric getLabelledSuppliedMetric(final int labelCo
    * @return the labelled gauge
    */
   public static LabelledSuppliedSummary getLabelledSuppliedSummary(final int labelCount) {
-      return new LabelledSuppliedNoOpMetric(labelCount);
+    return new LabelledSuppliedNoOpMetric(labelCount);
   }
 
   @Override

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/AbstractPrometheusSummary.java

@@ -27,16 +27,22 @@
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
 import io.prometheus.metrics.model.snapshots.SummarySnapshot;
 
+/**
+ * Abstract base class for Prometheus summary collectors. A summary provides a total count of
+ * observations and a sum of all observed values, it calculates configurable quantiles over a
+ * sliding time window.
+ */
 abstract class AbstractPrometheusSummary extends CategorizedPrometheusCollector {
-  /** The collector */
+  /** The Prometheus collector */
   protected final Collector collector;
 
   /**
-   * Create a new collector assigned to the given category and with the given name, and computed the
-   * prefixed name.
+   * Constructs a new AbstractPrometheusSummary.
    *
    * @param category The {@link MetricCategory} this collector is assigned to
    * @param name The name of this collector
+   * @param help The help description for this collector
+   * @param labelNames The label names for this collector
    */
   protected AbstractPrometheusSummary(
       final MetricCategory category,
@@ -48,33 +54,58 @@ protected AbstractPrometheusSummary(
   }
 
   /**
-   * Create the actual collector
+   * Creates the actual Prometheus collector.
    *
-   * @param help the help
-   * @param labelNames the label names
-   * @return the created collector
+   * @param help The help description for this collector
+   * @param labelNames The label names for this collector
+   * @return The created Prometheus collector
    */
   protected abstract Collector createCollector(final String help, final String... labelNames);
 
+  /**
+   * Gets the identifier for this collector.
+   *
+   * @return The Prometheus name of the collector
+   */
   @Override
   public String getIdentifier() {
     return collector.getPrometheusName();
   }
 
+  /**
+   * Registers this collector with the given Prometheus registry.
+   *
+   * @param registry The Prometheus registry to register this collector with
+   */
   @Override
   public void register(final PrometheusRegistry registry) {
     registry.register(collector);
   }
 
+  /**
+   * Unregisters this collector from the given Prometheus registry.
+   *
+   * @param registry The Prometheus registry to unregister this collector from
+   */
   @Override
   public void unregister(final PrometheusRegistry registry) {
     registry.unregister(collector);
   }
 
+  /**
+   * Collects the summary snapshot from the Prometheus collector.
+   *
+   * @return The collected summary snapshot
+   */
   private SummarySnapshot collect() {
     return (SummarySnapshot) collector.collect();
   }
 
+  /**
+   * Streams the observations from the collected summary snapshot.
+   *
+   * @return A stream of observations
+   */
   @Override
   public Stream<Observation> streamObservations() {
     return collect().getDataPoints().stream()

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/AbstractPrometheusSuppliedValueCollector.java

@@ -28,6 +28,12 @@
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
 import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
 
+/**
+ * Abstract base class for Prometheus supplied value collectors. A supplied value collector is one
+ * which actual value is kept outside the metric system, for example in an external library or to
+ * calculate the value only on demand when a metric scrape occurs. This class provides common
+ * functionality for Prometheus supplied value collectors.
+ */
 abstract class AbstractPrometheusSuppliedValueCollector extends CategorizedPrometheusCollector
     implements LabelledSuppliedMetric {
   /** The collector */
@@ -45,24 +51,16 @@ protected AbstractPrometheusSuppliedValueCollector(
     this.collector = createCollector(help, labelNames);
   }
 
-  /**
-   * Create the actual collector
-   *
-   * @param help the help
-   * @param labelNames the label names
-   * @return the created collector
-   */
   protected abstract Collector createCollector(final String help, final String... labelNames);
 
   @Override
-  public synchronized void labels(final DoubleSupplier valueSupplier, final String... labelValues) {
+  public void labels(final DoubleSupplier valueSupplier, final String... labelValues) {
     final var valueList = List.of(labelValues);
-    if (labelledCallbackData.containsKey(valueList)) {
+    if (labelledCallbackData.putIfAbsent(valueList, new CallbackData(valueSupplier, labelValues))
+        != null) {
       throw new IllegalArgumentException(
           String.format("A collector has already been created for label values %s", valueList));
     }
-
-    labelledCallbackData.put(valueList, new CallbackData(valueSupplier, labelValues));
   }
 
   @Override

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/MetricsHttpService.java

@@ -15,6 +15,7 @@
 package org.hyperledger.besu.metrics.prometheus;
 
 import static com.google.common.base.Preconditions.checkArgument;
+import static java.net.HttpURLConnection.HTTP_NOT_FOUND;
 
 import org.hyperledger.besu.metrics.MetricsService;
 
@@ -157,7 +158,7 @@ private static class RestrictedDefaultHandler extends DefaultHandler {
     public void handle(final HttpExchange exchange) throws IOException {
       if (!exchange.getRequestURI().getPath().equals("/")) {
         try {
-          exchange.sendResponseHeaders(404, -1);
+          exchange.sendResponseHeaders(HTTP_NOT_FOUND, -1);
         } finally {
           exchange.close();
         }

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusCounter.java

@@ -26,6 +26,11 @@
 import io.prometheus.metrics.core.datapoints.CounterDataPoint;
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
 
+/**
+ * A Prometheus counter implementation for Besu metrics. This class provides a Prometheus counter
+ * where the actual value is kept internally by the collector and methods are provided to increase
+ * the value when needed.
+ */
 class PrometheusCounter extends CategorizedPrometheusCollector implements LabelledMetric<Counter> {
   private final io.prometheus.metrics.core.metrics.Counter counter;
 
@@ -63,6 +68,11 @@ public void unregister(final PrometheusRegistry registry) {
     registry.unregister(counter);
   }
 
+  /**
+   * Streams the observations from the collected counter data points.
+   *
+   * @return A stream of observations
+   */
   @Override
   public Stream<Observation> streamObservations() {
     return counter.collect().getDataPoints().stream()
@@ -72,13 +82,20 @@ public Stream<Observation> streamObservations() {
                     category, name, sample.getValue(), getLabelValues(sample.getLabels())));
   }
 
+  /** A private record class representing an unlabelled counter. */
   private record UnlabelledCounter(CounterDataPoint counter) implements Counter {
 
+    /** Increments the counter by one. */
     @Override
     public void inc() {
       counter.inc();
     }
 
+    /**
+     * Increments the counter by the specified amount.
+     *
+     * @param amount The amount to increment the counter by
+     */
     @Override
     public void inc(final long amount) {
       counter.inc((double) amount);

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusGuavaCache.java

@@ -34,6 +34,14 @@
 import io.prometheus.metrics.model.snapshots.MetricSnapshot;
 import io.vertx.core.impl.ConcurrentHashSet;
 
+/**
+ * A Prometheus Guava cache collector implementation for Besu metrics. This class provides a way to
+ * expose metrics from Guava caches, it behaves differently from other collectors, since instead of
+ * having one collector per cache, Prometheus provides only one collector for all caches, so we need
+ * a Context that wraps the Prometheus single collector and handles its registration, while here we
+ * keep the abstraction of one Prometheus collector for one Guava cache, and we also verify that
+ * there is no collector name clash.
+ */
 class PrometheusGuavaCache extends CategorizedPrometheusCollector {
   /** Use to reduce the possibility of a name clash with other collectors */
   private static final String NAME_PREFIX = "__guavaCacheMetricsCollector__";
@@ -74,6 +82,12 @@ public Stream<Observation> streamObservations() {
     return context.streamObservations(category, name);
   }
 
+  /**
+   * Since Prometheus provides only one collector for all Guava caches, we only need to register
+   * that collector once when the first Besu Guava cache collector is created, and unregister it
+   * when the last is unregistered, so we have this context to keep track of that and also manage
+   * the observations stream.
+   */
   static class Context {
     private static final Map<String, ToDoubleFunction<DataPointSnapshot>>
         COLLECTOR_VALUE_EXTRACTORS =

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusSimpleTimer.java

@@ -27,6 +27,10 @@
 import io.prometheus.metrics.core.metrics.Histogram;
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
 
+/**
+ * An implementation of Besu simple timer backed by a Prometheus histogram. The histogram samples
+ * durations and counts them in configurable buckets. It also provides a sum of all observed values.
+ */
 class PrometheusSimpleTimer extends CategorizedPrometheusCollector
     implements LabelledMetric<OperationTimer> {
 

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusSuppliedCounter.java

@@ -26,17 +26,13 @@
 import io.prometheus.metrics.model.snapshots.CounterSnapshot;
 import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
 
-/** The Prometheus supplied counter. */
-public class PrometheusSuppliedCounter extends AbstractPrometheusSuppliedValueCollector {
+/**
+ * A Prometheus supplied counter collector. A supplied counter collector is one which actual value
+ * is kept outside the metric system, for example in an external library or to calculate the value
+ * only on demand when a metric scrape occurs.
+ */
+class PrometheusSuppliedCounter extends AbstractPrometheusSuppliedValueCollector {
 
-  /**
-   * Instantiates a new labelled Prometheus supplied counter.
-   *
-   * @param category the {@link MetricCategory} this supplied counter is assigned to
-   * @param name the metric name
-   * @param help the help
-   * @param labelNames the label names
-   */
   public PrometheusSuppliedCounter(
       final MetricCategory category,
       final String name,

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusSuppliedGauge.java

@@ -27,19 +27,15 @@
 import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
 import io.prometheus.metrics.model.snapshots.GaugeSnapshot;
 
-/** The Prometheus gauge. */
+/**
+ * A Prometheus supplied gauge collector. A supplied gauge collector is one which actual value is
+ * kept outside the metric system, for example in an external library or to calculate the value only
+ * on demand when a metric scrape occurs.
+ */
 @SuppressWarnings("removal")
-public class PrometheusSuppliedGauge extends AbstractPrometheusSuppliedValueCollector
+class PrometheusSuppliedGauge extends AbstractPrometheusSuppliedValueCollector
     implements LabelledGauge {
 
-  /**
-   * Instantiates a new labelled Prometheus gauge.
-   *
-   * @param category the {@link MetricCategory} this gauge is assigned to
-   * @param name the metric name
-   * @param help the help
-   * @param labelNames the label names
-   */
   public PrometheusSuppliedGauge(
       final MetricCategory category,
       final String name,

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusSuppliedSummary.java

@@ -28,6 +28,11 @@
 import io.prometheus.metrics.model.snapshots.Quantile;
 import io.prometheus.metrics.model.snapshots.Quantiles;
 
+/**
+ * A Prometheus supplied summary collector. A supplied summary collector is one which actual value
+ * is kept outside the metric system, for example in an external library or to calculate the value
+ * only on demand when a metric scrape occurs.
+ */
 class PrometheusSuppliedSummary extends AbstractPrometheusSummary
     implements LabelledSuppliedSummary {
   /** Map label values with the collector callback data */

metrics/core/src/main/java/org/hyperledger/besu/metrics/prometheus/PrometheusTimer.java

@@ -24,6 +24,11 @@
 import io.prometheus.metrics.core.metrics.Summary;
 import io.prometheus.metrics.model.registry.Collector;
 
+/**
+ * An implementation of Besu timer backed by a Prometheus summary. The summary provides a total
+ * count of durations and a sum of all observed durations, it calculates configurable quantiles over
+ * a sliding time window.
+ */
 class PrometheusTimer extends AbstractPrometheusSummary implements LabelledMetric<OperationTimer> {
   private final Map<Double, Double> quantiles;