open-telemetry
/
opentelemetry-java
mirror of https://github.com/open-telemetry/opentelemetry-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Metrics: Add cumulative API. (#168)

This commit is contained in:
Yang Song 2019-04-19 17:45:14 -07:00 committed by GitHub
parent f6e44119b7
commit ff86f96dc1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 366 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
api/src/main/java/openconsensus/metrics/DerivedDoubleCumulative.java Normal file
View File

@ -0,0 +1,95 @@
/*
* Copyright 2019, OpenConsensus 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 openconsensus.metrics;
import java.lang.ref.WeakReference;
import java.util.List;
import javax.annotation.concurrent.ThreadSafe;
import openconsensus.common.ToDoubleFunction;
/**
* Derived Double Cumulative metric, to report cumulative measurement of a double value. Cumulative
* values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
*
* <p>Example: Create a Cumulative 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"));
*
* DerivedDoubleCumulative cumulative = metricRegistry.addDerivedDoubleCumulative(
* "processed_jobs", "Processed jobs in a queue", "1", labelKeys);
*
* QueueManager queueManager = new QueueManager();
* cumulative.createTimeSeries(labelValues, queueManager,
* new ToDoubleFunction<QueueManager>() {
* {@literal @}Override
* public double applyAsDouble(QueueManager queue) {
* return queue.size();
* }
* });
*
* void doWork() {
* // Your code here.
* }
* }
*
* }</pre>
*
* @since 0.1.0
*/
@ThreadSafe
public abstract class DerivedDoubleCumulative {
/**
* 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.1.0
*/
public abstract <T> void createTimeSeries(
List<LabelValue> labelValues, T obj, ToDoubleFunction<T> function);
/**
* Removes the {@code TimeSeries} from the cumulative metric, if it is present.
*
* @param labelValues the list of label values.
* @throws NullPointerException if {@code labelValues} is null.
* @since 0.1.0
*/
public abstract void removeTimeSeries(List<LabelValue> labelValues);
/**
* Removes all {@code TimeSeries} from the cumulative metric.
*
* @since 0.1.0
*/
public abstract void clear();
}

139
api/src/main/java/openconsensus/metrics/DoubleCumulative.java Normal file
View File

@ -0,0 +1,139 @@
/*
* Copyright 2019, OpenConsensus 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 openconsensus.metrics;
import java.util.List;
import javax.annotation.concurrent.ThreadSafe;
/**
* Double Cumulative metric, to report instantaneous measurement of a double value. Cumulative
* values can go up or stay the same, but can never go down. Cumulative values cannot be negative.
*
* <p>Example 1: Create a Cumulative with default labels.
*
* <pre>{@code
* class YourClass {
*
* private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry();
*
* List<LabelKey> labelKeys = Arrays.asList(LabelKey.create("Name", "desc"));
*
* DoubleCumulative cumulative = metricRegistry.addDoubleCumulative("processed_jobs",
* "Processed jobs", "1", labelKeys);
*
* // It is recommended to keep a reference of a point for manual operations.
* DoublePoint defaultPoint = cumulative.getDefaultTimeSeries();
*
* void doWork() {
* // Your code here.
* defaultPoint.add(10);
* }
*
* }
* }</pre>
*
* <p>Example 2: You can also use labels (keys and values) to track different types of metric.
*
* <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"));
*
* DoubleCumulative cumulative = metricRegistry.addDoubleCumulative("processed_jobs",
* "Processed jobs", "1", labelKeys);
*
* // It is recommended to keep a reference of a point for manual operations.
* DoublePoint inboundPoint = cumulative.getOrCreateTimeSeries(labelValues);
*
* void doSomeWork() {
* // Your code here.
* inboundPoint.set(15);
* }
*
* }
* }</pre>
*
* @since 0.1.0
*/
@ThreadSafe
public abstract class DoubleCumulative {
/**
* Creates a {@code TimeSeries} and returns a {@code DoublePoint} if the specified {@code
* labelValues} is not already associated with this cumulative, else returns an existing {@code
* DoublePoint}.
*
* <p>It is recommended to keep a reference to the DoublePoint instead of always calling this
* method for manual operations.
*
* @param labelValues the list of label values. The number of label values must be the same to
* that of the label keys passed to {@link MetricRegistry#addDoubleCumulative}.
* @return a {@code DoublePoint} the value of single cumulative.
* @throws NullPointerException if {@code labelValues} is null OR any element of {@code
* labelValues} is null.
* @throws IllegalArgumentException if number of {@code labelValues}s are not equal to the label
* keys.
* @since 0.1.0
*/
public abstract DoublePoint getOrCreateTimeSeries(List<LabelValue> labelValues);
/**
* Returns a {@code DoublePoint} for a cumulative with all labels not set, or default labels.
*
* @return a {@code DoublePoint} for a cumulative with all labels not set, or default labels.
* @since 0.1.0
*/
public abstract DoublePoint getDefaultTimeSeries();
/**
* Removes the {@code TimeSeries} from the cumulative metric, if it is present. i.e. references to
* previous {@code DoublePoint} objects are invalid (not part of the metric).
*
* @param labelValues the list of label values.
* @throws NullPointerException if {@code labelValues} is null or any element of {@code
* labelValues} is null.
* @since 0.1.0
*/
public abstract void removeTimeSeries(List<LabelValue> labelValues);
/**
* Removes all {@code TimeSeries} from the cumulative metric. i.e. references to all previous
* {@code DoublePoint} objects are invalid (not part of the metric).
*
* @since 0.1.0
*/
public abstract void clear();
/**
* The value of a single point in the Cumulative.TimeSeries.
*
* @since 0.1.0
*/
public abstract static class DoublePoint {
/**
* Adds the given value to the current value. The values cannot be negative.
*
* @param delta the value to add
* @since 0.1.0
*/
public abstract void add(double delta);
}
}

27
api/src/main/java/openconsensus/metrics/MetricRegistry.java
View File

@ -77,4 +77,31 @@ public abstract class MetricRegistry {
* @since 0.1.0
*/
public abstract DerivedDoubleGauge addDerivedDoubleGauge(String name, MetricOptions options);
/**
* Builds a new double cumulative to be added to the registry. This is a more convenient form when
* you want to manually increase values as per your service requirements.
*
* @param name the name of the metric.
* @param options the options for the metric.
* @return a {@code DoubleCumulative}.
* @throws NullPointerException if {@code name} is null.
* @throws IllegalArgumentException if different metric with the same name already registered.
* @since 0.1.0
*/
public abstract DoubleCumulative addDoubleCumulative(String name, MetricOptions options);
/**
* Builds a new derived double cumulative to be added to the registry. This is a more convenient
* form when you want to define a cumulative by executing a {@link ToDoubleFunction} on an object.
*
* @param name the name of the metric.
* @param options the options for the metric.
* @return a {@code DerivedDoubleCumulative}.
* @throws NullPointerException if {@code name} is null.
* @throws IllegalArgumentException if different metric with the same name already registered.
* @since 0.1.0
*/
public abstract DerivedDoubleCumulative addDerivedDoubleCumulative(
String name, MetricOptions options);
}

105
api/src/main/java/openconsensus/metrics/NoopMetrics.java
View File

@ -75,6 +75,24 @@ public final class NoopMetrics {
options.getUnit(),
options.getLabelKeys());
}
@Override
public DoubleCumulative addDoubleCumulative(String name, MetricOptions options) {
return NoopDoubleCumulative.create(
Utils.checkNotNull(name, "name"),
options.getDescription(),
options.getUnit(),
options.getLabelKeys());
}
@Override
public DerivedDoubleCumulative addDerivedDoubleCumulative(String name, MetricOptions options) {
return NoopDerivedDoubleCumulative.create(
Utils.checkNotNull(name, "name"),
options.getDescription(),
options.getUnit(),
options.getLabelKeys());
}
}
/** No-op implementations of LongGauge class. */
@ -246,4 +264,91 @@ public final class NoopMetrics {
@Override
public void clear() {}
}
/** No-op implementations of DoubleCumulative class. */
private static final class NoopDoubleCumulative extends DoubleCumulative {
private final int labelKeysSize;
static NoopDoubleCumulative create(
String name, String description, String unit, List<LabelKey> labelKeys) {
return new NoopDoubleCumulative(name, description, unit, labelKeys);
}
/** Creates a new {@code NoopDoublePoint}. */
NoopDoubleCumulative(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");
labelKeysSize = labelKeys.size();
}
@Override
public NoopDoublePoint getOrCreateTimeSeries(List<LabelValue> labelValues) {
Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
Utils.checkArgument(
labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
return NoopDoublePoint.INSTANCE;
}
@Override
public NoopDoublePoint getDefaultTimeSeries() {
return NoopDoublePoint.INSTANCE;
}
@Override
public void removeTimeSeries(List<LabelValue> labelValues) {
Utils.checkNotNull(labelValues, "labelValues");
}
@Override
public void clear() {}
/** No-op implementations of DoublePoint class. */
private static final class NoopDoublePoint extends DoublePoint {
private static final NoopDoublePoint INSTANCE = new NoopDoublePoint();
private NoopDoublePoint() {}
@Override
public void add(double delta) {}
}
}
/** No-op implementations of DerivedDoubleCumulative class. */
private static final class NoopDerivedDoubleCumulative extends DerivedDoubleCumulative {
private final int labelKeysSize;
static NoopDerivedDoubleCumulative create(
String name, String description, String unit, List<LabelKey> labelKeys) {
return new NoopDerivedDoubleCumulative(name, description, unit, labelKeys);
}
/** Creates a new {@code NoopDerivedDoubleCumulative}. */
NoopDerivedDoubleCumulative(
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");
labelKeysSize = labelKeys.size();
}
@Override
public <T> void createTimeSeries(
List<LabelValue> labelValues, T obj, ToDoubleFunction<T> function) {
Utils.checkListElementNotNull(Utils.checkNotNull(labelValues, "labelValues"), "labelValue");
Utils.checkArgument(
labelKeysSize == labelValues.size(), "Label Keys and Label Values don't have same size.");
Utils.checkNotNull(function, "function");
}
@Override
public void removeTimeSeries(List<LabelValue> labelValues) {
Utils.checkNotNull(labelValues, "labelValues");
}
@Override
public void clear() {}
}
}