001package io.prometheus.metrics.model.registry;
002
003import io.prometheus.metrics.model.snapshots.MetricSnapshot;
004
005import java.util.function.Predicate;
006
007import static io.prometheus.metrics.model.snapshots.PrometheusNaming.prometheusName;
008
009/**
010 * To be registered with the Prometheus collector registry.
011 * See <i>Overall Structure</i> on
012 * <a href="https://prometheus.io/docs/instrumenting/writing_clientlibs/">https://prometheus.io/docs/instrumenting/writing_clientlibs/</a>.
013 */
014@FunctionalInterface
015public interface Collector {
016
017    /**
018     * Called when the Prometheus server scrapes metrics.
019     */
020    MetricSnapshot collect();
021
022    /**
023     * Like {@link #collect()}, but returns {@code null} if {@code includedNames.test(name)} is {@code false}.
024     * <p>
025     * Override this if there is a more efficient way than first collecting the snapshot and then discarding it.
026     */
027    default MetricSnapshot collect(Predicate<String> includedNames) {
028        MetricSnapshot result = collect();
029        if (includedNames.test(result.getMetadata().getPrometheusName())) {
030            return result;
031        } else {
032            return null;
033        }
034    }
035
036    /**
037     * Override this and return {@code null} if a collector does not have a constant name,
038     * or if you don't want this library to call {@link #collect()} during registration of this collector.
039     */
040    default String getPrometheusName() {
041        return collect().getMetadata().getPrometheusName();
042    }
043}