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.ToLongFunction; 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 Long Gauge metric, to report instantaneous measurement of an int64 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 * DerivedLongGauge gauge = metricRegistry.addDerivedLongGauge( 44 * "queue_size", "Pending jobs in a queue", "1", labelKeys); 45 * 46 * QueueManager queueManager = new QueueManager(); 47 * gauge.createTimeSeries(labelValues, queueManager, 48 * new ToLongFunction<QueueManager>() { 49 * {@literal @}Override 50 * public long applyAsLong(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 DerivedLongGauge { 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, ToLongFunction< T> function)82 public abstract <T> void createTimeSeries( 83 List<LabelValue> labelValues, /*@Nullable*/ T obj, ToLongFunction</*@Nullable*/ T> function); 84 85 /** 86 * Removes the {@code TimeSeries} from the gauge metric, if it is present. 87 * 88 * @param labelValues the list of label values. 89 * @throws NullPointerException if {@code labelValues} is null. 90 * @since 0.17 91 */ removeTimeSeries(List<LabelValue> labelValues)92 public abstract void removeTimeSeries(List<LabelValue> labelValues); 93 94 /** 95 * Removes all {@code TimeSeries} from the gauge metric. 96 * 97 * @since 0.17 98 */ clear()99 public abstract void clear(); 100 101 /** 102 * Returns the no-op implementation of the {@code DerivedLongGauge}. 103 * 104 * @return the no-op implementation of the {@code DerivedLongGauge}. 105 * @since 0.17 106 */ newNoopDerivedLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)107 static DerivedLongGauge newNoopDerivedLongGauge( 108 String name, String description, String unit, List<LabelKey> labelKeys) { 109 return NoopDerivedLongGauge.create(name, description, unit, labelKeys); 110 } 111 112 /** No-op implementations of DerivedLongGauge class. */ 113 private static final class NoopDerivedLongGauge extends DerivedLongGauge { 114 private final int labelKeysSize; 115 create( String name, String description, String unit, List<LabelKey> labelKeys)116 static NoopDerivedLongGauge create( 117 String name, String description, String unit, List<LabelKey> labelKeys) { 118 return new NoopDerivedLongGauge(name, description, unit, labelKeys); 119 } 120 121 /** Creates a new {@code NoopDerivedLongGauge}. */ NoopDerivedLongGauge(String name, String description, String unit, List<LabelKey> labelKeys)122 NoopDerivedLongGauge(String name, String description, String unit, List<LabelKey> labelKeys) { 123 Utils.checkNotNull(name, "name"); 124 Utils.checkNotNull(description, "description"); 125 Utils.checkNotNull(unit, "unit"); 126 Utils.checkListElementNotNull( 127 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 128 labelKeysSize = labelKeys.size(); 129 } 130 131 @Override createTimeSeries( List<LabelValue> labelValues, T obj, ToLongFunction< T> function)132 public <T> void createTimeSeries( 133 List<LabelValue> labelValues, 134 /*@Nullable*/ T obj, 135 ToLongFunction</*@Nullable*/ T> function) { 136 Utils.checkListElementNotNull( 137 Utils.checkNotNull(labelValues, "labelValues"), "labelValue element should not be null."); 138 Utils.checkArgument(labelKeysSize == labelValues.size(), "Incorrect number of labels."); 139 Utils.checkNotNull(function, "function"); 140 } 141 142 @Override removeTimeSeries(List<LabelValue> labelValues)143 public void removeTimeSeries(List<LabelValue> labelValues) { 144 Utils.checkNotNull(labelValues, "labelValues"); 145 } 146 147 @Override clear()148 public void clear() {} 149 } 150 } 151