diff options
author | Mayur Kale <mayurkale@google.com> | 2018-10-13 22:28:41 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-10-13 22:28:41 -0700 |
commit | 53b1b60633cc3704bdaf0bd84efb3d2503578b20 (patch) | |
tree | 6a4be39742b8abcb3f666897acb593c528368c82 /api/src/main/java | |
parent | 7c6a1e66dd8ff52aaf99fb086df656db149b58d5 (diff) | |
download | opencensus-java-53b1b60633cc3704bdaf0bd84efb3d2503578b20.tar.gz |
Gauge API : Add LongGauge Support (Part1) (#1489)
* Gauge API : Add LongGauge Support (Part1)
* Fix review comments
* Fix review comments, removed LongGauge from registry
* Add TODO and remove unnecessary check on removeTimeSeries
Diffstat (limited to 'api/src/main/java')
-rw-r--r-- | api/src/main/java/io/opencensus/metrics/LongGauge.java | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/api/src/main/java/io/opencensus/metrics/LongGauge.java b/api/src/main/java/io/opencensus/metrics/LongGauge.java new file mode 100644 index 00000000..2294f0cf --- /dev/null +++ b/api/src/main/java/io/opencensus/metrics/LongGauge.java @@ -0,0 +1,211 @@ +/* + * 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.internal.Utils; +import java.util.List; +import javax.annotation.concurrent.ThreadSafe; + +/** + * 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 1: Create a Gauge with default labels. + * + * <pre>{@code + * class YourClass { + * + * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry(); + * + * List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc")); + * // TODO(mayurkale): Plugs-in the LongGauge into the registry. + * LongGauge gauge = metricRegistry.addLongGauge("queue_size", "Pending jobs", "1", labelKeys); + * + * // It is recommended to keep a reference of a point for manual operations. + * LongPoint defaultPoint = gauge.getDefaultTimeSeries(); + * + * void doWork() { + * // Your code here. + * defaultPoint.add(10); + * } + * + * } + * }</pre> + * + * <p>Example 2: You can also use labels(keys and values) to track different types of metric. + * + * <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 LongGauge into the registry. + * LongGauge gauge = metricRegistry.addLongGauge("queue_size", "Pending jobs", "1", labelKeys); + * + * // It is recommended to keep a reference of a point for manual operations. + * LongPoint inboundPoint = gauge.getOrCreateTimeSeries(labelValues); + * + * void doSomeWork() { + * // Your code here. + * inboundPoint.set(15); + * } + * + * } + * }</pre> + * + * @since 0.17 + */ +@ThreadSafe +public abstract class LongGauge { + + /** + * Creates a {@code TimeSeries} and returns a {@code LongPoint} if the specified {@code + * labelValues} is not already associated with this gauge, else returns a existing {@code + * LongPoint}. + * + * <p>It is recommended to keep a reference to the LongPoint instead of always calling this method + * for manual operations. + * + * @param labelValues the list of label values. The number of label values must be the same to + * that of the label keys passed to {@link MetricRegistry#addLongGauge}. + * @return a {@code LongPoint} the value of single gauge. + * @throws NullPointerException if {@code labelValues} is null OR any element of {@code + * labelValues} is null. + * @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label + * keys passed to {@link MetricRegistry#addLongGauge}. + * @since 0.17 + */ + public abstract LongPoint getOrCreateTimeSeries(List<LabelValue> labelValues); + + /** + * Returns a {@code LongPoint} for a gauge with all labels not set, or default labels. + * + * @return a {@code LongPoint} the value of default gauge. + * @since 0.17 + */ + public abstract LongPoint getDefaultTimeSeries(); + + /** + * Removes the {@code TimeSeries} from the gauge metric, if it is present. i.e. references to + * previous {@code LongPoint} objects are invalid (not part of the metric). + * + * @param labelValues the list of label values. + * @throws NullPointerException if {@code labelValues} is null or any element of {@code + * labelValues} is null. + * @since 0.17 + */ + public abstract void removeTimeSeries(List<LabelValue> labelValues); + + /** + * References to all previous {@code LongPoint} objects are invalid (not part of the metric). + * + * @since 0.17 + */ + public abstract void clear(); + + /** + * Returns the no-op implementation of the {@code LongGauge}. + * + * @return the no-op implementation of the {@code LongGauge}. + * @since 0.17 + */ + static LongGauge newNoopLongGauge( + String name, String description, String unit, List<LabelKey> labelKeys) { + return NoopLongGauge.create(name, description, unit, labelKeys); + } + + /** + * The value of a single point in the Gauge.TimeSeries. + * + * @since 0.17 + */ + public abstract static class LongPoint { + + /** + * Adds the given value to the current value. The values can be negative. + * + * @param amt the value to add + * @since 0.17 + */ + public abstract void add(long amt); + + /** + * Sets the given value. + * + * @param val the new value. + * @since 0.17 + */ + public abstract void set(long val); + } + + /** No-op implementations of LongGauge class. */ + private static final class NoopLongGauge extends LongGauge { + private final int labelKeysSize; + + static NoopLongGauge create( + String name, String description, String unit, List<LabelKey> labelKeys) { + return new NoopLongGauge(name, description, unit, labelKeys); + } + + /** Creates a new {@code NoopLongPoint}. */ + NoopLongGauge(String name, String description, String unit, List<LabelKey> labelKeys) { + Utils.checkNotNull(name, "name"); + Utils.checkNotNull(description, "description"); + Utils.checkNotNull(unit, "unit"); + Utils.checkNotNull(labelKeys, "labelKeys should not be null."); + Utils.checkListElementNotNull(labelKeys, "labelKeys element should not be null."); + labelKeysSize = labelKeys.size(); + } + + @Override + public NoopLongPoint getOrCreateTimeSeries(List<LabelValue> labelValues) { + Utils.checkNotNull(labelValues, "labelValues should not be null."); + Utils.checkListElementNotNull(labelValues, "labelValues element should not be null."); + Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels."); + return NoopLongPoint.INSTANCE; + } + + @Override + public NoopLongPoint getDefaultTimeSeries() { + return NoopLongPoint.INSTANCE; + } + + @Override + public void removeTimeSeries(List<LabelValue> labelValues) { + Utils.checkNotNull(labelValues, "labelValues should not be null."); + } + + @Override + public void clear() {} + + /** No-op implementations of LongPoint class. */ + private static final class NoopLongPoint extends LongPoint { + private static final NoopLongPoint INSTANCE = new NoopLongPoint(); + + private NoopLongPoint() {} + + @Override + public void add(long amt) {} + + @Override + public void set(long val) {} + } + } +} |