1 /* 2 * Copyright 2018, OpenCensus Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.opencensus.metrics; 18 19 import io.opencensus.internal.Utils; 20 import java.util.List; 21 import javax.annotation.concurrent.ThreadSafe; 22 23 /** 24 * Double Gauge metric, to report instantaneous measurement of a double value. Gauges can go both up 25 * and down. The gauges values can be negative. 26 * 27 * <p>Example 1: Create a Gauge with default labels. 28 * 29 * <pre>{@code 30 * class YourClass { 31 * 32 * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry(); 33 * 34 * List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc")); 35 * 36 * DoubleGauge gauge = metricRegistry.addDoubleGauge("queue_size", 37 * "Pending jobs", "1", labelKeys); 38 * 39 * // It is recommended to keep a reference of a point for manual operations. 40 * DoublePoint defaultPoint = gauge.getDefaultTimeSeries(); 41 * 42 * void doWork() { 43 * // Your code here. 44 * defaultPoint.add(10); 45 * } 46 * 47 * } 48 * }</pre> 49 * 50 * <p>Example 2: You can also use labels(keys and values) to track different types of metric. 51 * 52 * <pre>{@code 53 * class YourClass { 54 * 55 * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry(); 56 * 57 * List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc")); 58 * List<LabelValue> labelValues = Arrays.asList(LabelValue.create("Inbound")); 59 * 60 * DoubleGauge gauge = metricRegistry.addDoubleGauge("queue_size", 61 * "Pending jobs", "1", labelKeys); 62 * 63 * // It is recommended to keep a reference of a point for manual operations. 64 * DoublePoint inboundPoint = gauge.getOrCreateTimeSeries(labelValues); 65 * 66 * void doSomeWork() { 67 * // Your code here. 68 * inboundPoint.set(15); 69 * } 70 * 71 * } 72 * }</pre> 73 * 74 * @since 0.17 75 */ 76 @ThreadSafe 77 public abstract class DoubleGauge { 78 79 /** 80 * Creates a {@code TimeSeries} and returns a {@code DoublePoint} if the specified {@code 81 * labelValues} is not already associated with this gauge, else returns an existing {@code 82 * DoublePoint}. 83 * 84 * <p>It is recommended to keep a reference to the DoublePoint instead of always calling this 85 * method for manual operations. 86 * 87 * @param labelValues the list of label values. The number of label values must be the same to 88 * that of the label keys passed to {@link MetricRegistry#addDoubleGauge}. 89 * @return a {@code DoublePoint} the value of single gauge. 90 * @throws NullPointerException if {@code labelValues} is null OR any element of {@code 91 * labelValues} is null. 92 * @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label 93 * keys. 94 * @since 0.17 95 */ 96 public abstract DoublePoint getOrCreateTimeSeries(List<LabelValue> labelValues); 97 98 /** 99 * Returns a {@code DoublePoint} for a gauge with all labels not set, or default labels. 100 * 101 * @return a {@code DoublePoint} for a gauge with all labels not set, or default labels. 102 * @since 0.17 103 */ 104 public abstract DoublePoint getDefaultTimeSeries(); 105 106 /** 107 * Removes the {@code TimeSeries} from the gauge metric, if it is present. i.e. references to 108 * previous {@code DoublePoint} objects are invalid (not part of the metric). 109 * 110 * @param labelValues the list of label values. 111 * @throws NullPointerException if {@code labelValues} is null or any element of {@code 112 * labelValues} is null. 113 * @since 0.17 114 */ 115 public abstract void removeTimeSeries(List<LabelValue> labelValues); 116 117 /** 118 * Removes all {@code TimeSeries} from the gauge metric. i.e. references to all previous {@code 119 * DoublePoint} objects are invalid (not part of the metric). 120 * 121 * @since 0.17 122 */ 123 public abstract void clear(); 124 125 /** 126 * Returns the no-op implementation of the {@code DoubleGauge}. 127 * 128 * @return the no-op implementation of the {@code DoubleGauge}. 129 * @since 0.17 130 */ 131 static DoubleGauge newNoopDoubleGauge( 132 String name, String description, String unit, List<LabelKey> labelKeys) { 133 return NoopDoubleGauge.create(name, description, unit, labelKeys); 134 } 135 136 /** 137 * The value of a single point in the Gauge.TimeSeries. 138 * 139 * @since 0.17 140 */ 141 public abstract static class DoublePoint { 142 143 /** 144 * Adds the given value to the current value. The values can be negative. 145 * 146 * @param amt the value to add 147 * @since 0.17 148 */ 149 public abstract void add(double amt); 150 151 /** 152 * Sets the given value. 153 * 154 * @param val the new value. 155 * @since 0.17 156 */ 157 public abstract void set(double val); 158 } 159 160 /** No-op implementations of DoubleGauge class. */ 161 private static final class NoopDoubleGauge extends DoubleGauge { 162 private final int labelKeysSize; 163 164 static NoopDoubleGauge create( 165 String name, String description, String unit, List<LabelKey> labelKeys) { 166 return new NoopDoubleGauge(name, description, unit, labelKeys); 167 } 168 169 /** Creates a new {@code NoopDoublePoint}. */ 170 NoopDoubleGauge(String name, String description, String unit, List<LabelKey> labelKeys) { 171 Utils.checkNotNull(name, "name"); 172 Utils.checkNotNull(description, "description"); 173 Utils.checkNotNull(unit, "unit"); 174 Utils.checkListElementNotNull( 175 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 176 labelKeysSize = labelKeys.size(); 177 } 178 179 @Override 180 public NoopDoublePoint getOrCreateTimeSeries(List<LabelValue> labelValues) { 181 Utils.checkListElementNotNull( 182 Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null."); 183 Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels."); 184 return NoopDoublePoint.INSTANCE; 185 } 186 187 @Override 188 public NoopDoublePoint getDefaultTimeSeries() { 189 return NoopDoublePoint.INSTANCE; 190 } 191 192 @Override 193 public void removeTimeSeries(List<LabelValue> labelValues) { 194 Utils.checkNotNull(labelValues, "labelValues"); 195 } 196 197 @Override 198 public void clear() {} 199 200 /** No-op implementations of DoublePoint class. */ 201 private static final class NoopDoublePoint extends DoublePoint { 202 private static final NoopDoublePoint INSTANCE = new NoopDoublePoint(); 203 204 private NoopDoublePoint() {} 205 206 @Override 207 public void add(double amt) {} 208 209 @Override 210 public void set(double val) {} 211 } 212 } 213 } 214
