io.prometheus.client

Class SimpleCollector<Child>

java.lang.Object

io.prometheus.client.Collector

io.prometheus.client.SimpleCollector<Child>

Direct Known Subclasses:

Counter, Enumeration, Gauge, Histogram, Info, Summary

public abstract class SimpleCollector<Child>
extends Collector

Common functionality for Gauge, Counter, Summary and Histogram.

This class handles common initialization and label logic for the standard metrics. You should never subclass this class.

Initialization

After calling build() on a subclass, name, help, labelNames, namespace and subsystem can be called to configure the Collector. These return this to allow calls to be chained. Once configured, call create (which is also called by register).

The fullname of the metric is namespace_subsystem_name, but only name is required.

Labels

labelNames specifies which (if any) labels the metrics will have, and labels(java.lang.String...) returns the Child of the metric that represents that particular set of labels. Gauge, Counter and Summary all offer convenience methods to avoid needing to call labels(java.lang.String...) for metrics with no labels.

remove(java.lang.String...) and clear() can be used to remove children.

Warning #1: Metrics that don't always export something are difficult to monitor, if you know in advance what labels will be in use you should initialise them be calling labels(java.lang.String...). This is done for you for metrics with no labels.

Warning #2: While labels are very powerful, avoid overly granular metric labels. The combinatorial explosion of breaking out a metric in many dimensions can produce huge numbers of timeseries, which will then take longer and more resources to process.

As a rule of thumb aim to keep the cardinality of metrics below ten, and limit where the cardinality exceeds that value. For example rather than breaking out latency by customer and endpoint in one metric, you might have two metrics with one breaking out by each. If the cardinality is in the hundreds, you may wish to consider removing the breakout by one of the dimensions altogether.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SimpleCollector.Builder<B extends SimpleCollector.Builder<B,C>,C extends SimpleCollector> Builders let you configure and then create collectors.

Nested classes/interfaces inherited from class io.prometheus.client.Collector

Collector.Describable, Collector.MetricFamilySamples, Collector.Type

Field Summary

Fields

Modifier and Type	Field and Description
protected ConcurrentMap<List<String>,Child>	children
protected String	fullname
protected String	help
protected List<String>	labelNames
protected Child	noLabelsChild
protected String	unit

Fields inherited from class io.prometheus.client.Collector

MILLISECONDS_PER_SECOND, NANOSECONDS_PER_SECOND

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SimpleCollector(SimpleCollector.Builder b)

Method Summary

Modifier and Type	Method and Description
void	clear() Remove all children.
protected List<Collector.MetricFamilySamples>	familySamplesList(Collector.Type type, List<Collector.MetricFamilySamples.Sample> samples)
protected void	initializeNoLabelsChild() Initialize the child with no labels.
Child	labels(String... labelValues) Return the Child with the given labels, creating it if needed.
protected abstract Child	newChild() Return a new child, workaround for Java generics limitations.
void	remove(String... labelValues) Remove the Child with the given labels.
<T extends Collector> T	setChild(Child child, String... labelValues) Replace the Child with the given labels.

Methods inherited from class io.prometheus.client.Collector

checkMetricLabelName, checkMetricName, collect, doubleToGoString, register, register, sanitizeMetricName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

fullname

protected final String fullname

help

protected final String help

unit

protected final String unit

labelNames

protected final List<String> labelNames

children

protected final ConcurrentMap<List<String>,Child> children

noLabelsChild

protected Child noLabelsChild

Constructor Detail

SimpleCollector

protected SimpleCollector(SimpleCollector.Builder b)

Method Detail

labels

public Child labels(String... labelValues)

Return the Child with the given labels, creating it if needed.

Must be passed the same number of labels are were passed to labelNames.

remove

public void remove(String... labelValues)

Remove the Child with the given labels.

Any references to the Child are invalidated.

clear

public void clear()

Remove all children.

Any references to any children are invalidated.

initializeNoLabelsChild

protected void initializeNoLabelsChild()

Initialize the child with no labels.

setChild

public <T extends Collector> T setChild(Child child,
                                        String... labelValues)

Replace the Child with the given labels.

This is intended for advanced uses, in particular proxying metrics from another monitoring system. This allows for callbacks for returning values for Counter and Gauge without having to implement a full Collector.

An example with Gauge:

 
   Gauge.build().name("current_time").help("Current unixtime.").create()
       .setChild(new Gauge.Child() {
         public double get() {
           return System.currentTimeMillis() / MILLISECONDS_PER_SECOND;
         }
       }).register();
 
 

Any references any previous Child with these labelValues are invalidated. A metric should be either all callbacks, or none.

newChild

protected abstract Child newChild()

Return a new child, workaround for Java generics limitations.

familySamplesList

protected List<Collector.MetricFamilySamples> familySamplesList(Collector.Type type,
                                                                List<Collector.MetricFamilySamples.Sample> samples)