Interface Collector

All Known Implementing Classes:
Counter, CounterWithCallback, Gauge, GaugeWithCallback, Histogram, Info, Metric, MetricWithFixedMetadata, StatefulMetric, StateSet, Summary, SummaryWithCallback
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface Collector
To be registered with the Prometheus collector registry. See Overall Structure on https://prometheus.io/docs/instrumenting/writing_clientlibs/.

  • Method Details

    • collect

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

    • collect

      default MetricSnapshot collect(PrometheusScrapeRequest scrapeRequest)
      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

    • collect

      @Nullable default MetricSnapshot collect(Predicate<String> includedNames)
      Like collect(), but returns null if includedNames.test(name) is false.

      Override this if there is a more efficient way than first collecting the snapshot and then discarding it.

    • collect

      @Nullable default MetricSnapshot collect(Predicate<String> includedNames, PrometheusScrapeRequest scrapeRequest)
      Like 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.

    • getPrometheusName

      @Nullable default String getPrometheusName()
      This is called in two places:
      1. During registration to check if a metric with that name already exists.
      2. During scrape to check if this collector can be skipped because a name filter is present and the metric name is excluded.

      Returning 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 prometheus-metrics-core override this.

    • getMetricType

      @Nullable default MetricType getMetricType()
      Returns the metric type for registration-time validation.

      This is used to prevent different metric types (e.g., Counter and Gauge) from sharing the same name. Returning null means type validation is skipped for this collector.

      Validation is performed only at registration time. If this method returns null, no type validation is performed for this collector, and duplicate or conflicting metrics may result in invalid exposition output.

      Returns:
      the metric type, or null to skip validation

    • getLabelNames

      @Nullable default Set<String> getLabelNames()
      Returns the complete set of label names for this metric.

      This includes both dynamic label names (specified in labelNames()) and constant label names (specified in constLabels()). Label names are normalized using Prometheus naming conventions.

      This is used for registration-time validation to prevent duplicate label schemas for the same metric name. Two collectors with the same name and type can coexist if they have different label name sets.

      Returning null is treated as an empty label set: the registry normalizes it to Collections.emptySet() and performs full label-schema validation and duplicate detection. Two collectors with the same name, type, and null (or empty) label names are considered duplicate and registration of the second will fail.

      Returns:
      the set of all label names, or null (treated as empty) for a metric with no labels

    • getMetadata

      @Nullable default MetricMetadata getMetadata()
      Returns the metric metadata (name, help, unit) for registration-time validation.

      When non-null, the registry uses this to validate that metrics with the same name have consistent help and unit. Returning null means help/unit validation is skipped for this collector.

      Returns:
      the metric metadata, or null to skip help/unit validation