io.prometheus.metrics.model.registry.Collector Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jmx_prometheus_httpserver Show documentation

See https://github.com/prometheus/jmx_exporter/blob/master/README.md

There is a newer version: 1.0.1

Show newest version

package io.prometheus.metrics.model.registry;

import io.prometheus.metrics.model.snapshots.MetricSnapshot;

import java.util.function.Predicate;

import static io.prometheus.metrics.model.snapshots.PrometheusNaming.prometheusName;

/**
 * To be registered with the Prometheus collector registry.
 * See Overall Structure on
 * https://prometheus.io/docs/instrumenting/writing_clientlibs/.
 */
@FunctionalInterface
public interface Collector {

    /**
     * Called when the Prometheus server scrapes metrics.
     */
    MetricSnapshot collect();

    /**
     * Provides Collector with the details of the request issued by Prometheus to allow multi-target pattern implementation
     * Override to implement request dependent logic to provide MetricSnapshot
     */
	default MetricSnapshot collect(PrometheusScrapeRequest scrapeRequest) {
		return collect();
	}
    
    /**
     * Like {@link #collect()}, but returns {@code null} if {@code includedNames.test(name)} is {@code false}.
     * 
     * Override this if there is a more efficient way than first collecting the snapshot and then discarding it.
     */
    default MetricSnapshot collect(Predicate includedNames) {
        MetricSnapshot result = collect();
        if (includedNames.test(result.getMetadata().getPrometheusName())) {
            return result;
        } else {
            return null;
        }
    }
    
    /**
     * Like {@link #collect(Predicate)}, but with support for multi-target pattern.
     * 

     * Override this if there is a more efficient way than first collecting the snapshot and then discarding it.
     */
    default MetricSnapshot collect(Predicate includedNames, PrometheusScrapeRequest scrapeRequest) {
        MetricSnapshot result = collect(scrapeRequest);
        if (includedNames.test(result.getMetadata().getPrometheusName())) {
            return result;
        } else {
            return null;
        }
    }
    

    /**
     * This is called in two places:
     * 

     * During registration to check if a metric with that name already exists.
     * During scrape to check if this collector can be skipped because a name filter is present and the metric name is excluded.
     * 
     * Returning {@code null} means checks are omitted (registration the metric always succeeds),
     * and the collector is always scraped (the result is dropped after scraping if a name filter is present and
     * the metric name is excluded).
     * 
     * If your metric has a name that does not change at runtime it is a good idea to overwrite this and return the name.
     * 
     * All metrics in {@code prometheus-metrics-core} override this.
     */
    default String getPrometheusName() {
        return null;
    }
}