1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
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() {}
}
}
|
