diff options
author | Mayur Kale <mayurkale@google.com> | 2018-10-18 16:36:55 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-10-18 16:36:55 -0700 |
commit | af1358b7e29d15257cff835c25ee3b38382c3c9b (patch) | |
tree | f18a5cb3c379f9b13a3254b2ad6bb0847322e8fa /api/src/main/java/io/opencensus | |
parent | b98e4b90687833108cb497d0bc61311ff662db7c (diff) | |
download | opencensus-java-af1358b7e29d15257cff835c25ee3b38382c3c9b.tar.gz |
Gauge API : Add support for DerivedDoubleGauge (#1504)
* Add support for DerivedDoubleGauge
* Fix review comments
* Fix reviews
Diffstat (limited to 'api/src/main/java/io/opencensus')
3 files changed, 162 insertions, 5 deletions
diff --git a/api/src/main/java/io/opencensus/common/ToDoubleFunction.java b/api/src/main/java/io/opencensus/common/ToDoubleFunction.java index eac85793..6ace2f7c 100644 --- a/api/src/main/java/io/opencensus/common/ToDoubleFunction.java +++ b/api/src/main/java/io/opencensus/common/ToDoubleFunction.java @@ -16,6 +16,10 @@ package io.opencensus.common; +/*>>> +import org.checkerframework.checker.nullness.qual.Nullable; +*/ + /** * Represents a function that produces a double-valued result. See {@link * io.opencensus.metrics.MetricRegistry} for an example of its use. @@ -25,7 +29,7 @@ package io.opencensus.common; * * @since 0.16 */ -public interface ToDoubleFunction<T> { +public interface ToDoubleFunction</*@Nullable*/ T> { /** * Applies this function to the given argument. @@ -33,5 +37,5 @@ public interface ToDoubleFunction<T> { * @param value the function argument. * @return the function result. */ - double applyAsDouble(T value); + double applyAsDouble(/*@Nullable*/ T value); } diff --git a/api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java b/api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java new file mode 100644 index 00000000..10119eef --- /dev/null +++ b/api/src/main/java/io/opencensus/metrics/DerivedDoubleGauge.java @@ -0,0 +1,153 @@ +/* + * Copyright 2018, OpenCensus Authors + * + * 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 + * + * http://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.opencensus.metrics; + +import io.opencensus.common.ToDoubleFunction; +import io.opencensus.internal.Utils; +import java.lang.ref.WeakReference; +import java.util.List; +import javax.annotation.concurrent.ThreadSafe; + +/*>>> +import org.checkerframework.checker.nullness.qual.Nullable; +*/ + +/** + * Derived Double Gauge metric, to report instantaneous measurement of a double value. Gauges can go + * both up and down. The gauges values can be negative. + * + * <p>Example: Create a Gauge with an object and a callback function. + * + * <pre>{@code + * class YourClass { + * + * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry(); + * + * List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc")); + * List<LabelValue> labelValues = Arrays.asList(LabelValue.create("Inbound")); + * + * // TODO(mayurkale): Plugs-in the DerivedDoubleGauge into the registry. + * DerivedDoubleGauge gauge = metricRegistry.addDerivedDoubleGauge( + * "queue_size", "Pending jobs in a queue", "1", labelKeys); + * + * QueueManager queueManager = new QueueManager(); + * gauge.createTimeSeries(labelValues, queueManager, + * new ToDoubleFunction<QueueManager>() { + * {@literal @}Override + * public double applyAsDouble(QueueManager queue) { + * return queue.size(); + * } + * }); + * + * void doWork() { + * // Your code here. + * } + * } + * + * }</pre> + * + * @since 0.17 + */ +@ThreadSafe +public abstract class DerivedDoubleGauge { + /** + * Creates a {@code TimeSeries}. The value of a single point in the TimeSeries is observed from a + * callback function. This function is invoked whenever metrics are collected, meaning the + * reported value is up-to-date. It keeps a {@link WeakReference} to the object and it is the + * user's responsibility to manage the lifetime of the object. + * + * @param labelValues the list of label values. + * @param obj the state object from which the function derives a measurement. + * @param function the function to be called. + * @param <T> the type of the object upon which the function derives a measurement. + * @throws NullPointerException if {@code labelValues} is null OR any element of {@code + * labelValues} is null OR {@code function} is null. + * @throws IllegalArgumentException if different time series with the same labels already exists + * OR if number of {@code labelValues}s are not equal to the label keys. + * @since 0.17 + */ + public abstract <T> void createTimeSeries( + List<LabelValue> labelValues, + /*@Nullable*/ T obj, + ToDoubleFunction</*@Nullable*/ T> function); + + /** + * Removes the {@code TimeSeries} from the gauge metric, if it is present. + * + * @param labelValues the list of label values. + * @throws NullPointerException if {@code labelValues} is null. + * @since 0.17 + */ + public abstract void removeTimeSeries(List<LabelValue> labelValues); + + /** + * Removes all {@code TimeSeries} from the gauge metric. + * + * @since 0.17 + */ + public abstract void clear(); + + /** + * Returns the no-op implementation of the {@code DerivedDoubleGauge}. + * + * @return the no-op implementation of the {@code DerivedDoubleGauge}. + * @since 0.17 + */ + static DerivedDoubleGauge newNoopDerivedDoubleGauge( + String name, String description, String unit, List<LabelKey> labelKeys) { + return NoopDerivedDoubleGauge.create(name, description, unit, labelKeys); + } + + /** No-op implementations of DerivedDoubleGauge class. */ + private static final class NoopDerivedDoubleGauge extends DerivedDoubleGauge { + private final int labelKeysSize; + + static NoopDerivedDoubleGauge create( + String name, String description, String unit, List<LabelKey> labelKeys) { + return new NoopDerivedDoubleGauge(name, description, unit, labelKeys); + } + + /** Creates a new {@code NoopDerivedDoubleGauge}. */ + NoopDerivedDoubleGauge(String name, String description, String unit, List<LabelKey> labelKeys) { + Utils.checkNotNull(name, "name"); + Utils.checkNotNull(description, "description"); + Utils.checkNotNull(unit, "unit"); + Utils.checkListElementNotNull( + Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); + labelKeysSize = labelKeys.size(); + } + + @Override + public <T> void createTimeSeries( + List<LabelValue> labelValues, + /*@Nullable*/ T obj, + ToDoubleFunction</*@Nullable*/ T> function) { + Utils.checkListElementNotNull( + Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null."); + Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels."); + Utils.checkNotNull(function, "function"); + } + + @Override + public void removeTimeSeries(List<LabelValue> labelValues) { + Utils.checkNotNull(labelValues, "labelValues"); + } + + @Override + public void clear() {} + } +} diff --git a/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java b/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java index 8fdd800d..43943fa6 100644 --- a/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java +++ b/api/src/main/java/io/opencensus/metrics/DerivedLongGauge.java @@ -30,7 +30,7 @@ import org.checkerframework.checker.nullness.qual.Nullable; * Derived Long Gauge metric, to report instantaneous measurement of an int64 value. Gauges can go * both up and down. The gauges values can be negative. * - * <p>Example: Create a Gauge with object and function. + * <p>Example: Create a Gauge with an object and a callback function. * * <pre>{@code * class YourClass { @@ -131,8 +131,8 @@ public abstract class DerivedLongGauge { @Override public <T> void createTimeSeries( - List<LabelValue> labelValues, /*@Nullable*/ - T obj, + List<LabelValue> labelValues, + /*@Nullable*/ T obj, ToLongFunction</*@Nullable*/ T> function) { Utils.checkListElementNotNull( Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null."); |