001package io.prometheus.metrics.core.datapoints;
002
003import io.prometheus.metrics.model.snapshots.Labels;
004
005/**
006 * Represents a single gauge data point, i.e. a single line for a gauge metric in Prometheus text format.
007 * <p>
008 * See JavaDoc of {@link CounterDataPoint} on how using data points directly can improve performance.
009 */
010public interface GaugeDataPoint extends DataPoint, TimerApi {
011
012    /**
013     * Add one.
014     */
015    default void inc() {
016        inc(1.0);
017    }
018
019    /**
020     * Add {@code amount}.
021     */
022    void inc(double amount);
023
024    /**
025     * Add one, and create a custom exemplar with the given labels.
026     */
027    default void incWithExemplar(Labels labels) {
028        incWithExemplar(1.0, labels);
029    }
030
031    /**
032     * Add {@code amount}, and create a custom exemplar with the given labels.
033     */
034    void incWithExemplar(double amount, Labels labels);
035
036    /**
037     * Subtract one.
038     */
039    default void dec() {
040        inc(-1.0);
041    }
042
043    /**
044     * Subtract {@code amount}.
045     */
046    default void dec(double amount) {
047        inc(-amount);
048    }
049
050    /**
051     * Subtract one, and create a custom exemplar with the given labels.
052     */
053    default void decWithExemplar(Labels labels) {
054        incWithExemplar(-1.0, labels);
055    }
056
057    /**
058     * Subtract {@code amount}, and create a custom exemplar with the given labels.
059     */
060    default void decWithExemplar(double amount, Labels labels) {
061        incWithExemplar(-amount, labels);
062    }
063
064    /**
065     * Set the gauge to {@code value}.
066     */
067    void set(double value);
068
069    /**
070     * Get the current value.
071     */
072    double get();
073
074    /**
075     * Set the gauge to {@code value}, and create a custom exemplar with the given labels.
076     */
077    void setWithExemplar(double value, Labels labels);
078
079    /**
080     * {@inheritDoc}
081     */
082    default Timer startTimer() {
083        return new Timer(this::set);
084    }
085}