diff options
Diffstat (limited to 'api/src/main/java')
5 files changed, 280 insertions, 15 deletions
diff --git a/api/src/main/java/io/opencensus/metrics/Distribution.java b/api/src/main/java/io/opencensus/metrics/Distribution.java index 87f99635..9294b838 100644 --- a/api/src/main/java/io/opencensus/metrics/Distribution.java +++ b/api/src/main/java/io/opencensus/metrics/Distribution.java @@ -45,17 +45,17 @@ public abstract class Distribution { /** * Creates a {@link Distribution}. * - * @param mean mean of the population values. - * @param count count of the population values. - * @param sumOfSquaredDeviations sum of squared deviations of the population values. + * @param count the count of the population values. + * @param sum the sum of the population values. + * @param sumOfSquaredDeviations the sum of squared deviations of the population values. * @param bucketBoundaries bucket boundaries of a histogram. * @param buckets {@link Bucket}s of a histogram. * @return a {@code Distribution}. * @since 0.17 */ public static Distribution create( - double mean, long count, + double sum, double sumOfSquaredDeviations, List<Double> bucketBoundaries, List<Bucket> buckets) { @@ -63,13 +63,13 @@ public abstract class Distribution { Utils.checkArgument( sumOfSquaredDeviations >= 0, "sum of squared deviations should be non-negative."); if (count == 0) { - Utils.checkArgument(mean == 0, "mean should be 0 if count is 0."); + Utils.checkArgument(sum == 0, "sum should be 0 if count is 0."); Utils.checkArgument( sumOfSquaredDeviations == 0, "sum of squared deviations should be 0 if count is 0."); } return new AutoValue_Distribution( - mean, count, + sum, sumOfSquaredDeviations, copyBucketBounds(bucketBoundaries), copyBucketCount(buckets)); @@ -100,20 +100,20 @@ public abstract class Distribution { } /** - * Returns the aggregated mean. + * Returns the aggregated count. * - * @return the aggregated mean. + * @return the aggregated count. * @since 0.17 */ - public abstract double getMean(); + public abstract long getCount(); /** - * Returns the aggregated count. + * Returns the aggregated sum. * - * @return the aggregated count. + * @return the aggregated sum. * @since 0.17 */ - public abstract long getCount(); + public abstract double getSum(); /** * Returns the aggregated sum of squared deviations. diff --git a/api/src/main/java/io/opencensus/metrics/Metric.java b/api/src/main/java/io/opencensus/metrics/Metric.java index b463420c..0c108b56 100644 --- a/api/src/main/java/io/opencensus/metrics/Metric.java +++ b/api/src/main/java/io/opencensus/metrics/Metric.java @@ -22,6 +22,7 @@ import io.opencensus.internal.Utils; import io.opencensus.metrics.Value.ValueDistribution; import io.opencensus.metrics.Value.ValueDouble; import io.opencensus.metrics.Value.ValueLong; +import io.opencensus.metrics.Value.ValueSummary; import java.util.List; import javax.annotation.concurrent.Immutable; @@ -88,9 +89,14 @@ public abstract class Metric { Utils.checkArgument( value instanceof ValueDouble, "Type mismatch: %s, %s.", type, valueClassName); break; + case GAUGE_DISTRIBUTION: case CUMULATIVE_DISTRIBUTION: Utils.checkArgument( value instanceof ValueDistribution, "Type mismatch: %s, %s.", type, valueClassName); + break; + case SUMMARY: + Utils.checkArgument( + value instanceof ValueSummary, "Type mismatch: %s, %s.", type, valueClassName); } } } diff --git a/api/src/main/java/io/opencensus/metrics/MetricDescriptor.java b/api/src/main/java/io/opencensus/metrics/MetricDescriptor.java index e20730e9..5146cd85 100644 --- a/api/src/main/java/io/opencensus/metrics/MetricDescriptor.java +++ b/api/src/main/java/io/opencensus/metrics/MetricDescriptor.java @@ -127,6 +127,15 @@ public abstract class MetricDescriptor { GAUGE_DOUBLE, /** + * An instantaneous measurement of a distribution value. The count and sum can go both up and + * down. Used in scenarios like a snapshot of time the current items in a queue have spent + * there. + * + * @since 0.17 + */ + GAUGE_DISTRIBUTION, + + /** * An cumulative measurement of an int64 value. * * @since 0.17 @@ -141,10 +150,23 @@ public abstract class MetricDescriptor { CUMULATIVE_DOUBLE, /** - * An cumulative measurement of a distribution value. + * An cumulative measurement of a distribution value. The count and sum can only go up, if + * resets then the start_time should also be reset. * * @since 0.17 */ CUMULATIVE_DISTRIBUTION, + + /** + * Some frameworks implemented DISTRIBUTION as a summary of observations (usually things like + * request durations and response sizes). While it also provides a total count of observations + * and a sum of all observed values, it calculates configurable quantiles over a sliding time + * window. + * + * <p>This is not recommended, since it cannot be aggregated. + * + * @since 0.17 + */ + SUMMARY, } } diff --git a/api/src/main/java/io/opencensus/metrics/Summary.java b/api/src/main/java/io/opencensus/metrics/Summary.java new file mode 100644 index 00000000..f23667bb --- /dev/null +++ b/api/src/main/java/io/opencensus/metrics/Summary.java @@ -0,0 +1,187 @@ +/* + * 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 com.google.auto.value.AutoValue; +import io.opencensus.common.ExperimentalApi; +import io.opencensus.internal.Utils; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import javax.annotation.Nullable; +import javax.annotation.concurrent.Immutable; + +/** + * Implementation of the {@link Distribution} as a summary of observations. + * + * <p>This is not recommended, since it cannot be aggregated. + * + * @since 0.17 + */ +@ExperimentalApi +@AutoValue +@Immutable +public abstract class Summary { + Summary() {} + + /** + * Creates a {@link Summary}. + * + * @param count the count of the population values. + * @param sum the sum of the population values. + * @param snapshot bucket boundaries of a histogram. + * @return a {@code Summary} with the given values. + * @since 0.17 + */ + public static Summary create(@Nullable Long count, @Nullable Double sum, Snapshot snapshot) { + checkCountAndSum(count, sum); + Utils.checkNotNull(snapshot, "snapshot"); + return new AutoValue_Summary(count, sum, snapshot); + } + + /** + * Returns the aggregated count. If not available returns {@code null}. + * + * @return the aggregated count. + * @since 0.17 + */ + @Nullable + public abstract Long getCount(); + + /** + * Returns the aggregated sum. If not available returns {@code null}. + * + * @return the aggregated sum. + * @since 0.17 + */ + @Nullable + public abstract Double getSum(); + + /** + * Returns the {@link Snapshot}. + * + * @return the {@code Snapshot}. + * @since 0.17 + */ + public abstract Snapshot getSnapshot(); + + /** + * Represents the summary observation of the recorded events over a sliding time window. + * + * @since 0.17 + */ + @Immutable + @AutoValue + public abstract static class Snapshot { + /** + * Returns the number of values in this {@code Snapshot}. If not available returns {@code null}. + * + * @return the number of values in this {@code Snapshot}. + * @since 0.17 + */ + @Nullable + public abstract Long getCount(); + + /** + * Returns the sum of values in this {@code Snapshot}. If not available returns {@code null}. + * + * @return the sum of values in this {@code Snapshot}. + * @since 0.17 + */ + @Nullable + public abstract Double getSum(); + + /** + * Returns the list of {@code ValueAtPercentile}s in this {@code Snapshot}. + * + * @return the list of {@code ValueAtPercentile}s in this {@code Snapshot}. + * @since 0.17 + */ + public abstract List<ValueAtPercentile> getValueAtPercentiles(); + + /** + * Creates a {@link Snapshot}. + * + * @param count the number of values in this {@code Snapshot}. + * @param sum the number of values in this {@code Snapshot}. + * @param valueAtPercentiles the list of {@code ValueAtPercentile}. + * @return a {@code Snapshot} with the given values. + * @since 0.17 + */ + public static Snapshot create( + @Nullable Long count, @Nullable Double sum, List<ValueAtPercentile> valueAtPercentiles) { + checkCountAndSum(count, sum); + Utils.checkNotNull(valueAtPercentiles, "valueAtPercentiles"); + Utils.checkListElementNotNull(valueAtPercentiles, "value in valueAtPercentiles"); + return new AutoValue_Summary_Snapshot( + count, + sum, + Collections.unmodifiableList(new ArrayList<ValueAtPercentile>(valueAtPercentiles))); + } + + /** + * Represents the value at a given percentile of a distribution. + * + * @since 0.17 + */ + @Immutable + @AutoValue + public abstract static class ValueAtPercentile { + /** + * Returns the percentile in this {@code ValueAtPercentile}. + * + * <p>Must be in the interval (0.0, 100.0]. + * + * @return the percentile in this {@code ValueAtPercentile}. + * @since 0.17 + */ + public abstract double getPercentile(); + + /** + * Returns the value in this {@code ValueAtPercentile}. + * + * @return the value in this {@code ValueAtPercentile}. + * @since 0.17 + */ + public abstract double getValue(); + + /** + * Creates a {@link ValueAtPercentile}. + * + * @param percentile the percentile in this {@code ValueAtPercentile}. + * @param value the value in this {@code ValueAtPercentile}. + * @return a {@code ValueAtPercentile} with the given values. + * @since 0.17 + */ + public static ValueAtPercentile create(double percentile, double value) { + Utils.checkArgument( + 0 < percentile && percentile <= 100.0, + "percentile must be in the interval (0.0, 100.0]"); + Utils.checkArgument(value >= 0, "value must be non-negative"); + return new AutoValue_Summary_Snapshot_ValueAtPercentile(percentile, value); + } + } + } + + private static void checkCountAndSum(@Nullable Long count, @Nullable Double sum) { + Utils.checkArgument(count == null || count >= 0, "count must be non-negative."); + Utils.checkArgument(sum == null || sum >= 0, "sum must be non-negative."); + if (count != null && count == 0) { + Utils.checkArgument(sum == null || sum == 0, "sum must be 0 if count is 0."); + } + } +} diff --git a/api/src/main/java/io/opencensus/metrics/Value.java b/api/src/main/java/io/opencensus/metrics/Value.java index 5dd70c8d..1bc63b79 100644 --- a/api/src/main/java/io/opencensus/metrics/Value.java +++ b/api/src/main/java/io/opencensus/metrics/Value.java @@ -76,6 +76,17 @@ public abstract class Value { } /** + * Returns a {@link Summary} {@link Value}. + * + * @param value value in {@link Summary}. + * @return a {@code Summary} {@code Value}. + * @since 0.17 + */ + public static Value summaryValue(Summary value) { + return ValueSummary.create(value); + } + + /** * Applies the given match function to the underlying data type. * * @since 0.17 @@ -84,6 +95,7 @@ public abstract class Value { Function<? super Double, T> doubleFunction, Function<? super Long, T> longFunction, Function<? super Distribution, T> distributionFunction, + Function<? super Summary, T> summaryFunction, Function<? super Value, T> defaultFunction); /** A 64-bit double-precision floating-point {@link Value}. */ @@ -98,6 +110,7 @@ public abstract class Value { Function<? super Double, T> doubleFunction, Function<? super Long, T> longFunction, Function<? super Distribution, T> distributionFunction, + Function<? super Summary, T> summaryFunction, Function<? super Value, T> defaultFunction) { return doubleFunction.apply(getValue()); } @@ -132,6 +145,7 @@ public abstract class Value { Function<? super Double, T> doubleFunction, Function<? super Long, T> longFunction, Function<? super Distribution, T> distributionFunction, + Function<? super Summary, T> summaryFunction, Function<? super Value, T> defaultFunction) { return longFunction.apply(getValue()); } @@ -169,6 +183,7 @@ public abstract class Value { Function<? super Double, T> doubleFunction, Function<? super Long, T> longFunction, Function<? super Distribution, T> distributionFunction, + Function<? super Summary, T> summaryFunction, Function<? super Value, T> defaultFunction) { return distributionFunction.apply(getValue()); } @@ -191,6 +206,41 @@ public abstract class Value { abstract Distribution getValue(); } - // TODO(songya): Add support for Summary type. - // This is an aggregation that produces percentiles directly. + /** + * {@link ValueSummary} contains a snapshot representing values calculated over an arbitrary time + * window. + */ + @AutoValue + @Immutable + abstract static class ValueSummary extends Value { + + ValueSummary() {} + + @Override + public final <T> T match( + Function<? super Double, T> doubleFunction, + Function<? super Long, T> longFunction, + Function<? super Distribution, T> distributionFunction, + Function<? super Summary, T> summaryFunction, + Function<? super Value, T> defaultFunction) { + return summaryFunction.apply(getValue()); + } + + /** + * Creates a {@link ValueSummary}. + * + * @param value the {@link Summary} value. + * @return a {@code ValueSummary}. + */ + static ValueSummary create(Summary value) { + return new AutoValue_Value_ValueSummary(value); + } + + /** + * Returns the {@link Summary} value. + * + * @return the {@code Summary} value. + */ + abstract Summary getValue(); + } } |