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
|
/*
* 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.ToLongFunction;
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 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: 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"));
*
* DerivedLongGauge gauge = metricRegistry.addDerivedLongGauge(
* "queue_size", "Pending jobs in a queue", "1", labelKeys);
*
* QueueManager queueManager = new QueueManager();
* gauge.createTimeSeries(labelValues, queueManager,
* new ToLongFunction<QueueManager>() {
* {@literal @}Override
* public long applyAsLong(QueueManager queue) {
* return queue.size();
* }
* });
*
* void doWork() {
* // Your code here.
* }
* }
*
* }</pre>
*
* @since 0.17
*/
@ThreadSafe
public abstract class DerivedLongGauge {
/**
* 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, ToLongFunction</*@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 DerivedLongGauge}.
*
* @return the no-op implementation of the {@code DerivedLongGauge}.
* @since 0.17
*/
static DerivedLongGauge newNoopDerivedLongGauge(
String name, String description, String unit, List<LabelKey> labelKeys) {
return NoopDerivedLongGauge.create(name, description, unit, labelKeys);
}
/** No-op implementations of DerivedLongGauge class. */
private static final class NoopDerivedLongGauge extends DerivedLongGauge {
private final int labelKeysSize;
static NoopDerivedLongGauge create(
String name, String description, String unit, List<LabelKey> labelKeys) {
return new NoopDerivedLongGauge(name, description, unit, labelKeys);
}
/** Creates a new {@code NoopDerivedLongGauge}. */
NoopDerivedLongGauge(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,
ToLongFunction</*@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() {}
}
}
|
