1 /* 2 * Copyright 2018, 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.export; 18 19 import com.google.auto.value.AutoValue; 20 import io.opencensus.common.ExperimentalApi; 21 import io.opencensus.internal.Utils; 22 import java.util.ArrayList; 23 import java.util.Collections; 24 import java.util.List; 25 import javax.annotation.Nullable; 26 import javax.annotation.concurrent.Immutable; 27 28 /** 29 * Implementation of the {@link Distribution} as a summary of observations. 30 * 31 * <p>This is not recommended, since it cannot be aggregated. 32 * 33 * @since 0.17 34 */ 35 @ExperimentalApi 36 @AutoValue 37 @Immutable 38 public abstract class Summary { Summary()39 Summary() {} 40 41 /** 42 * Creates a {@link Summary}. 43 * 44 * @param count the count of the population values. 45 * @param sum the sum of the population values. 46 * @param snapshot bucket boundaries of a histogram. 47 * @return a {@code Summary} with the given values. 48 * @since 0.17 49 */ create(@ullable Long count, @Nullable Double sum, Snapshot snapshot)50 public static Summary create(@Nullable Long count, @Nullable Double sum, Snapshot snapshot) { 51 checkCountAndSum(count, sum); 52 Utils.checkNotNull(snapshot, "snapshot"); 53 return new AutoValue_Summary(count, sum, snapshot); 54 } 55 56 /** 57 * Returns the aggregated count. If not available returns {@code null}. 58 * 59 * @return the aggregated count. 60 * @since 0.17 61 */ 62 @Nullable getCount()63 public abstract Long getCount(); 64 65 /** 66 * Returns the aggregated sum. If not available returns {@code null}. 67 * 68 * @return the aggregated sum. 69 * @since 0.17 70 */ 71 @Nullable getSum()72 public abstract Double getSum(); 73 74 /** 75 * Returns the {@link Snapshot}. 76 * 77 * @return the {@code Snapshot}. 78 * @since 0.17 79 */ getSnapshot()80 public abstract Snapshot getSnapshot(); 81 82 /** 83 * Represents the summary observation of the recorded events over a sliding time window. 84 * 85 * @since 0.17 86 */ 87 @Immutable 88 @AutoValue 89 public abstract static class Snapshot { 90 /** 91 * Returns the number of values in this {@code Snapshot}. If not available returns {@code null}. 92 * 93 * @return the number of values in this {@code Snapshot}. 94 * @since 0.17 95 */ 96 @Nullable getCount()97 public abstract Long getCount(); 98 99 /** 100 * Returns the sum of values in this {@code Snapshot}. If not available returns {@code null}. 101 * 102 * @return the sum of values in this {@code Snapshot}. 103 * @since 0.17 104 */ 105 @Nullable getSum()106 public abstract Double getSum(); 107 108 /** 109 * Returns the list of {@code ValueAtPercentile}s in this {@code Snapshot}. 110 * 111 * @return the list of {@code ValueAtPercentile}s in this {@code Snapshot}. 112 * @since 0.17 113 */ getValueAtPercentiles()114 public abstract List<ValueAtPercentile> getValueAtPercentiles(); 115 116 /** 117 * Creates a {@link Snapshot}. 118 * 119 * @param count the number of values in this {@code Snapshot}. 120 * @param sum the number of values in this {@code Snapshot}. 121 * @param valueAtPercentiles the list of {@code ValueAtPercentile}. 122 * @return a {@code Snapshot} with the given values. 123 * @since 0.17 124 */ create( @ullable Long count, @Nullable Double sum, List<ValueAtPercentile> valueAtPercentiles)125 public static Snapshot create( 126 @Nullable Long count, @Nullable Double sum, List<ValueAtPercentile> valueAtPercentiles) { 127 checkCountAndSum(count, sum); 128 Utils.checkListElementNotNull( 129 Utils.checkNotNull(valueAtPercentiles, "valueAtPercentiles"), "valueAtPercentile"); 130 return new AutoValue_Summary_Snapshot( 131 count, 132 sum, 133 Collections.unmodifiableList(new ArrayList<ValueAtPercentile>(valueAtPercentiles))); 134 } 135 136 /** 137 * Represents the value at a given percentile of a distribution. 138 * 139 * @since 0.17 140 */ 141 @Immutable 142 @AutoValue 143 public abstract static class ValueAtPercentile { 144 /** 145 * Returns the percentile in this {@code ValueAtPercentile}. 146 * 147 * <p>Must be in the interval (0.0, 100.0]. 148 * 149 * @return the percentile in this {@code ValueAtPercentile}. 150 * @since 0.17 151 */ getPercentile()152 public abstract double getPercentile(); 153 154 /** 155 * Returns the value in this {@code ValueAtPercentile}. 156 * 157 * @return the value in this {@code ValueAtPercentile}. 158 * @since 0.17 159 */ getValue()160 public abstract double getValue(); 161 162 /** 163 * Creates a {@link ValueAtPercentile}. 164 * 165 * @param percentile the percentile in this {@code ValueAtPercentile}. 166 * @param value the value in this {@code ValueAtPercentile}. 167 * @return a {@code ValueAtPercentile} with the given values. 168 * @since 0.17 169 */ create(double percentile, double value)170 public static ValueAtPercentile create(double percentile, double value) { 171 Utils.checkArgument( 172 0 < percentile && percentile <= 100.0, 173 "percentile must be in the interval (0.0, 100.0]"); 174 Utils.checkArgument(value >= 0, "value must be non-negative"); 175 return new AutoValue_Summary_Snapshot_ValueAtPercentile(percentile, value); 176 } 177 } 178 } 179 checkCountAndSum(@ullable Long count, @Nullable Double sum)180 private static void checkCountAndSum(@Nullable Long count, @Nullable Double sum) { 181 Utils.checkArgument(count == null || count >= 0, "count must be non-negative."); 182 Utils.checkArgument(sum == null || sum >= 0, "sum must be non-negative."); 183 if (count != null && count == 0) { 184 Utils.checkArgument(sum == null || sum == 0, "sum must be 0 if count is 0."); 185 } 186 } 187 } 188