Skip to content
This repository was archived by the owner on Dec 23, 2023. It is now read-only.

Commit 8a86284

Browse files
songy23songy23
authored
Metrics: Add Cumulative APIs. (#1848)
1 parent d62a2e7 commit 8a86284

File tree

12 files changed

+1262
-6
lines changed

12 files changed

+1262
-6
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
- Support constant labels in Gauge APIs.
44
- Add an option to allow users to override the default "opencensus_task" metric label in Stackdriver Stats Exporter.
55
- Allow setting custom namespace in Prometheus exporter.
6+
- Add Cumulative (`DoubleCumulative`, `LongCumulative`, `DerivedDoubleCumulative`, `DerivedLongCumulative`) APIs.
67

78
## 0.20.0 - 2019-03-28
89
- Add OpenCensus Java OC-Agent Trace Exporter.

‎api/src/main/java/io/opencensus/metrics/DerivedDoubleCumulative.java‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
/*
2+
* Copyright 2019, 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 Cumulative metric, to report cumulative measurement of a double value. Cumulative
31+
* values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
32+
*
33+
* <p>Example: Create a Cumulative 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+
* DerivedDoubleCumulative cumulative = metricRegistry.addDerivedDoubleCumulative(
44+
* "processed_jobs", "Processed jobs in a queue", "1", labelKeys);
45+
*
46+
* QueueManager queueManager = new QueueManager();
47+
* cumulative.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.21
63+
*/
64+
@ThreadSafe
65+
public abstract class DerivedDoubleCumulative {
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.21
81+
*/
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 cumulative 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.21
93+
*/
94+
public abstract void removeTimeSeries(List<LabelValue> labelValues);
95+
96+
/**
97+
* Removes all {@code TimeSeries} from the cumulative metric.
98+
*
99+
* @since 0.21
100+
*/
101+
public abstract void clear();
102+
103+
/**
104+
* Returns the no-op implementation of the {@code DerivedDoubleCumulative}.
105+
*
106+
* @return the no-op implementation of the {@code DerivedDoubleCumulative}.
107+
* @since 0.21
108+
*/
109+
static DerivedDoubleCumulative newNoopDerivedDoubleCumulative(
110+
String name, String description, String unit, List<LabelKey> labelKeys) {
111+
return NoopDerivedDoubleCumulative.create(name, description, unit, labelKeys);
112+
}
113+
114+
/** No-op implementations of DerivedDoubleCumulative class. */
115+
private static final class NoopDerivedDoubleCumulative extends DerivedDoubleCumulative {
116+
private final int labelKeysSize;
117+
118+
static NoopDerivedDoubleCumulative create(
119+
String name, String description, String unit, List<LabelKey> labelKeys) {
120+
return new NoopDerivedDoubleCumulative(name, description, unit, labelKeys);
121+
}
122+
123+
/** Creates a new {@code NoopDerivedDoubleCumulative}. */
124+
NoopDerivedDoubleCumulative(
125+
String name, String description, String unit, List<LabelKey> labelKeys) {
126+
Utils.checkNotNull(name, "name");
127+
Utils.checkNotNull(description, "description");
128+
Utils.checkNotNull(unit, "unit");
129+
Utils.checkListElementNotNull(Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey");
130+
labelKeysSize = labelKeys.size();
131+
}
132+
133+
@Override
134+
public <T> void createTimeSeries(
135+
List<LabelValue> labelValues,
136+
/*@Nullable*/ T obj,
137+
ToDoubleFunction</*@Nullable*/ T> function) {
138+
Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
139+
Utils.checkArgument(
140+
labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
141+
Utils.checkNotNull(function, "function");
142+
}
143+
144+
@Override
145+
public void removeTimeSeries(List<LabelValue> labelValues) {
146+
Utils.checkNotNull(labelValues, "labelValues");
147+
}
148+
149+
@Override
150+
public void clear() {}
151+
}
152+
}

‎api/src/main/java/io/opencensus/metrics/DerivedLongCumulative.java‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
/*
2+
* Copyright 2019, 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 Cumulative metric, to report cumulative measurement of an int64 value. Cumulative
31+
* values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
32+
*
33+
* <p>Example: Create a Cumulative 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+
* DerivedLongCumulative cumulative = metricRegistry.addDerivedLongCumulative(
44+
* "processed_jobs", "Total processed jobs in a queue", "1", labelKeys);
45+
*
46+
* QueueManager queueManager = new QueueManager();
47+
* cumulative.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.21
63+
*/
64+
@ThreadSafe
65+
public abstract class DerivedLongCumulative {
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.21
81+
*/
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 cumulative 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.21
91+
*/
92+
public abstract void removeTimeSeries(List<LabelValue> labelValues);
93+
94+
/**
95+
* Removes all {@code TimeSeries} from the cumulative metric.
96+
*
97+
* @since 0.21
98+
*/
99+
public abstract void clear();
100+
101+
/**
102+
* Returns the no-op implementation of the {@code DerivedLongCumulative}.
103+
*
104+
* @return the no-op implementation of the {@code DerivedLongCumulative}.
105+
* @since 0.21
106+
*/
107+
static DerivedLongCumulative newNoopDerivedLongCumulative(
108+
String name, String description, String unit, List<LabelKey> labelKeys) {
109+
return NoopDerivedLongCumulative.create(name, description, unit, labelKeys);
110+
}
111+
112+
/** No-op implementations of DerivedLongCumulative class. */
113+
private static final class NoopDerivedLongCumulative extends DerivedLongCumulative {
114+
private final int labelKeysSize;
115+
116+
static NoopDerivedLongCumulative create(
117+
String name, String description, String unit, List<LabelKey> labelKeys) {
118+
return new NoopDerivedLongCumulative(name, description, unit, labelKeys);
119+
}
120+
121+
/** Creates a new {@code NoopDerivedLongCumulative}. */
122+
NoopDerivedLongCumulative(
123+
String name, String description, String unit, List<LabelKey> labelKeys) {
124+
Utils.checkNotNull(name, "name");
125+
Utils.checkNotNull(description, "description");
126+
Utils.checkNotNull(unit, "unit");
127+
Utils.checkListElementNotNull(Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey");
128+
labelKeysSize = labelKeys.size();
129+
}
130+
131+
@Override
132+
public <T> void createTimeSeries(
133+
List<LabelValue> labelValues,
134+
/*@Nullable*/ T obj,
135+
ToLongFunction</*@Nullable*/ T> function) {
136+
Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
137+
Utils.checkArgument(
138+
labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
139+
Utils.checkNotNull(function, "function");
140+
}
141+
142+
@Override
143+
public void removeTimeSeries(List<LabelValue> labelValues) {
144+
Utils.checkNotNull(labelValues, "labelValues");
145+
}
146+
147+
@Override
148+
public void clear() {}
149+
}
150+
}

0 commit comments

Comments
 (0)