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.common.ToDoubleFunction; 20 import io.opencensus.internal.Utils; 21 import java.lang.ref.WeakReference; 22 import java.util.List; 23 import javax.annotation.concurrent.ThreadSafe; 24 25 /*>>> 26 import org.checkerframework.checker.nullness.qual.Nullable; 27 */ 28 29 /** 30 * Derived Double Gauge metric, to report instantaneous measurement of a double value. Gauges can go 31 * both up and down. The gauges values can be negative. 32 * 33 * <p>Example: Create a Gauge with an object and a callback function. 34 * 35 * <pre>{@code 36 * class YourClass { 37 * 38 * private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry(); 39 * 40 * List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc")); 41 * List<LabelValue> labelValues = Arrays.asList(LabelValue.create("Inbound")); 42 * 43 * DerivedDoubleGauge gauge = metricRegistry.addDerivedDoubleGauge( 44 * "queue_size", "Pending jobs in a queue", "1", labelKeys); 45 * 46 * QueueManager queueManager = new QueueManager(); 47 * gauge.createTimeSeries(labelValues, queueManager, 48 * new ToDoubleFunction<QueueManager>() { 49 * {@literal @}Override 50 * public double applyAsDouble(QueueManager queue) { 51 * return queue.size(); 52 * } 53 * }); 54 * 55 * void doWork() { 56 * // Your code here. 57 * } 58 * } 59 * 60 * }</pre> 61 * 62 * @since 0.17 63 */ 64 @ThreadSafe 65 public abstract class DerivedDoubleGauge { 66 /** 67 * Creates a {@code TimeSeries}. The value of a single point in the TimeSeries is observed from a 68 * callback function. This function is invoked whenever metrics are collected, meaning the 69 * reported value is up-to-date. It keeps a {@link WeakReference} to the object and it is the 70 * user's responsibility to manage the lifetime of the object. 71 * 72 * @param labelValues the list of label values. 73 * @param obj the state object from which the function derives a measurement. 74 * @param function the function to be called. 75 * @param <T> the type of the object upon which the function derives a measurement. 76 * @throws NullPointerException if {@code labelValues} is null OR any element of {@code 77 * labelValues} is null OR {@code function} is null. 78 * @throws IllegalArgumentException if different time series with the same labels already exists 79 * OR if number of {@code labelValues}s are not equal to the label keys. 80 * @since 0.17 81 */ createTimeSeries( List<LabelValue> labelValues, T obj, ToDoubleFunction< T> function)82 public abstract <T> void createTimeSeries( 83 List<LabelValue> labelValues, 84 /*@Nullable*/ T obj, 85 ToDoubleFunction</*@Nullable*/ T> function); 86 87 /** 88 * Removes the {@code TimeSeries} from the gauge metric, if it is present. 89 * 90 * @param labelValues the list of label values. 91 * @throws NullPointerException if {@code labelValues} is null. 92 * @since 0.17 93 */ removeTimeSeries(List<LabelValue> labelValues)94 public abstract void removeTimeSeries(List<LabelValue> labelValues); 95 96 /** 97 * Removes all {@code TimeSeries} from the gauge metric. 98 * 99 * @since 0.17 100 */ clear()101 public abstract void clear(); 102 103 /** 104 * Returns the no-op implementation of the {@code DerivedDoubleGauge}. 105 * 106 * @return the no-op implementation of the {@code DerivedDoubleGauge}. 107 * @since 0.17 108 */ newNoopDerivedDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)109 static DerivedDoubleGauge newNoopDerivedDoubleGauge( 110 String name, String description, String unit, List<LabelKey> labelKeys) { 111 return NoopDerivedDoubleGauge.create(name, description, unit, labelKeys); 112 } 113 114 /** No-op implementations of DerivedDoubleGauge class. */ 115 private static final class NoopDerivedDoubleGauge extends DerivedDoubleGauge { 116 private final int labelKeysSize; 117 create( String name, String description, String unit, List<LabelKey> labelKeys)118 static NoopDerivedDoubleGauge create( 119 String name, String description, String unit, List<LabelKey> labelKeys) { 120 return new NoopDerivedDoubleGauge(name, description, unit, labelKeys); 121 } 122 123 /** Creates a new {@code NoopDerivedDoubleGauge}. */ NoopDerivedDoubleGauge(String name, String description, String unit, List<LabelKey> labelKeys)124 NoopDerivedDoubleGauge(String name, String description, String unit, List<LabelKey> labelKeys) { 125 Utils.checkNotNull(name, "name"); 126 Utils.checkNotNull(description, "description"); 127 Utils.checkNotNull(unit, "unit"); 128 Utils.checkListElementNotNull( 129 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 130 labelKeysSize = labelKeys.size(); 131 } 132 133 @Override createTimeSeries( List<LabelValue> labelValues, T obj, ToDoubleFunction< T> function)134 public <T> void createTimeSeries( 135 List<LabelValue> labelValues, 136 /*@Nullable*/ T obj, 137 ToDoubleFunction</*@Nullable*/ T> function) { 138 Utils.checkListElementNotNull( 139 Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null."); 140 Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels."); 141 Utils.checkNotNull(function, "function"); 142 } 143 144 @Override removeTimeSeries(List<LabelValue> labelValues)145 public void removeTimeSeries(List<LabelValue> labelValues) { 146 Utils.checkNotNull(labelValues, "labelValues"); 147 } 148 149 @Override clear()150 public void clear() {} 151 } 152 } 153