io.micrometer.core.instrument.Gauge Maven / Gradle / Ivy
/*
* Copyright 2017 VMware, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.micrometer.core.instrument;
import io.micrometer.core.annotation.Incubating;
import io.micrometer.core.instrument.distribution.HistogramGauges;
import io.micrometer.core.lang.Nullable;
import java.util.Collections;
import java.util.function.Supplier;
import java.util.function.ToDoubleFunction;
/**
* A gauge tracks a value that may go up or down. The value that is published for gauges
* is an instantaneous sample of the gauge at publishing time.
*
* @author Jon Schneider
*/
public interface Gauge extends Meter {
/**
* @param name The gauge's name.
* @param obj An object with some state or function which the gauge's instantaneous
* value is determined from.
* @param f A function that yields a double value for the gauge, based on the state of
* {@code obj}.
* @param The type of object to gauge.
* @return A new gauge builder.
*/
static Builder builder(String name, @Nullable T obj, ToDoubleFunction f) {
return new Builder<>(name, obj, f);
}
/**
* A convenience method for building a gauge from a supplying function, holding a
* strong reference to this function.
* @param name The gauge's name.
* @param f A function that yields a double value for the gauge.
* @return A new gauge builder.
* @since 1.1.0
*/
@Incubating(since = "1.1.0")
static Builder> builder(String name, Supplier f) {
return new Builder<>(name, f, f2 -> {
Number val = f2.get();
return val == null ? Double.NaN : val.doubleValue();
}).strongReference(true);
}
/**
* The act of observing the value by calling this method triggers sampling of the
* underlying number or user-defined function that defines the value for the gauge.
* @return The current value.
*/
double value();
@Override
default Iterable measure() {
return Collections.singletonList(new Measurement(this::value, Statistic.VALUE));
}
/**
* Fluent builder for gauges.
*
* @param The type of the state object from which the gauge value is extracted.
*/
class Builder {
private final String name;
private final ToDoubleFunction f;
private Tags tags = Tags.empty();
private boolean strongReference = false;
@Nullable
private Meter.Id syntheticAssociation = null;
@Nullable
private final T obj;
@Nullable
private String description;
@Nullable
private String baseUnit;
private Builder(String name, @Nullable T obj, ToDoubleFunction f) {
this.name = name;
this.obj = obj;
this.f = f;
}
/**
* @param tags Must be an even number of arguments representing key/value pairs of
* tags.
* @return The gauge builder with added tags.
*/
public Builder tags(String... tags) {
return tags(Tags.of(tags));
}
/**
* @param tags Tags to add to the eventual gauge.
* @return The gauge builder with added tags.
*/
public Builder tags(Iterable tags) {
this.tags = this.tags.and(tags);
return this;
}
/**
* @param key The tag key.
* @param value The tag value.
* @return The gauge builder with a single added tag.
*/
public Builder tag(String key, String value) {
this.tags = tags.and(key, value);
return this;
}
/**
* @param description Description text of the eventual gauge.
* @return The gauge builder with added description.
*/
public Builder description(@Nullable String description) {
this.description = description;
return this;
}
/**
* @param unit Base unit of the eventual gauge.
* @return The gauge builder with added base unit.
*/
public Builder baseUnit(@Nullable String unit) {
this.baseUnit = unit;
return this;
}
/**
* For internal use. Marks a gauge as a derivative of another metric. For example,
* percentiles and histogram gauges generated by {@link HistogramGauges} are
* derivatives of a {@link Timer} or {@link DistributionSummary}.
*
* This method may be removed in future minor or major releases if we find a way
* to mark derivatives in a private way that does not have other API compatibility
* consequences.
* @param syntheticAssociation The meter id of a meter for which this metric is a
* synthetic derivative.
* @return The gauge builder with an added synthetic association.
*/
@Incubating(since = "1.1.0")
public Builder synthetic(Meter.Id syntheticAssociation) {
this.syntheticAssociation = syntheticAssociation;
return this;
}
/**
* Indicates that the gauge should maintain a strong reference on the object upon
* which its instantaneous value is determined.
* @param strong Whether or not to maintain a strong reference on the gauged
* object.
* @return The gauge builder with altered strong reference semantics.
* @since 1.1.0
*/
@Incubating(since = "1.1.0")
public Builder strongReference(boolean strong) {
this.strongReference = strong;
return this;
}
/**
* Add the gauge to a single registry, or return an existing gauge in that
* registry. The returned gauge will be unique for each registry, but each
* registry is guaranteed to only create one gauge for the same combination of
* name and tags.
* @param registry A registry to add the gauge to, if it doesn't already exist.
* @return A new or existing gauge.
*/
public Gauge register(MeterRegistry registry) {
return registry.gauge(new Meter.Id(name, tags, baseUnit, description, Type.GAUGE, syntheticAssociation),
obj, strongReference ? new StrongReferenceGaugeFunction<>(obj, f) : f);
}
}
}