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 io.opencensus.metrics.LabelKey; 23 import java.util.ArrayList; 24 import java.util.Collections; 25 import java.util.List; 26 import javax.annotation.concurrent.Immutable; 27 28 /** 29 * {@link MetricDescriptor} defines a {@code Metric} type and its schema. 30 * 31 * @since 0.17 32 */ 33 @ExperimentalApi 34 @Immutable 35 @AutoValue 36 public abstract class MetricDescriptor { 37 MetricDescriptor()38 MetricDescriptor() {} 39 40 /** 41 * Creates a {@link MetricDescriptor}. 42 * 43 * @param name name of {@code MetricDescriptor}. 44 * @param description description of {@code MetricDescriptor}. 45 * @param unit the metric unit. 46 * @param type type of {@code MetricDescriptor}. 47 * @param labelKeys the label keys associated with the {@code MetricDescriptor}. 48 * @return a {@code MetricDescriptor}. 49 * @since 0.17 50 */ create( String name, String description, String unit, Type type, List<LabelKey> labelKeys)51 public static MetricDescriptor create( 52 String name, String description, String unit, Type type, List<LabelKey> labelKeys) { 53 Utils.checkNotNull(labelKeys, "labelKeys"); 54 Utils.checkListElementNotNull(labelKeys, "labelKey"); 55 return new AutoValue_MetricDescriptor( 56 name, 57 description, 58 unit, 59 type, 60 Collections.unmodifiableList(new ArrayList<LabelKey>(labelKeys))); 61 } 62 63 /** 64 * Returns the metric descriptor name. 65 * 66 * @return the metric descriptor name. 67 * @since 0.17 68 */ getName()69 public abstract String getName(); 70 71 /** 72 * Returns the description of this metric descriptor. 73 * 74 * @return the description of this metric descriptor. 75 * @since 0.17 76 */ getDescription()77 public abstract String getDescription(); 78 79 /** 80 * Returns the unit of this metric descriptor. 81 * 82 * @return the unit of this metric descriptor. 83 * @since 0.17 84 */ getUnit()85 public abstract String getUnit(); 86 87 /** 88 * Returns the type of this metric descriptor. 89 * 90 * @return the type of this metric descriptor. 91 * @since 0.17 92 */ getType()93 public abstract Type getType(); 94 95 /** 96 * Returns the label keys associated with this metric descriptor. 97 * 98 * @return the label keys associated with this metric descriptor. 99 * @since 0.17 100 */ getLabelKeys()101 public abstract List<LabelKey> getLabelKeys(); 102 103 /** 104 * The kind of metric. It describes how the data is reported. 105 * 106 * <p>A gauge is an instantaneous measurement of a value. 107 * 108 * <p>A cumulative measurement is a value accumulated over a time interval. In a time series, 109 * cumulative measurements should have the same start time and increasing end times, until an 110 * event resets the cumulative value to zero and sets a new start time for the following points. 111 * 112 * @since 0.17 113 */ 114 public enum Type { 115 116 /** 117 * An instantaneous measurement of an int64 value. 118 * 119 * @since 0.17 120 */ 121 GAUGE_INT64, 122 123 /** 124 * An instantaneous measurement of a double value. 125 * 126 * @since 0.17 127 */ 128 GAUGE_DOUBLE, 129 130 /** 131 * An instantaneous measurement of a distribution value. The count and sum can go both up and 132 * down. Used in scenarios like a snapshot of time the current items in a queue have spent 133 * there. 134 * 135 * @since 0.17 136 */ 137 GAUGE_DISTRIBUTION, 138 139 /** 140 * An cumulative measurement of an int64 value. 141 * 142 * @since 0.17 143 */ 144 CUMULATIVE_INT64, 145 146 /** 147 * An cumulative measurement of a double value. 148 * 149 * @since 0.17 150 */ 151 CUMULATIVE_DOUBLE, 152 153 /** 154 * An cumulative measurement of a distribution value. The count and sum can only go up, if 155 * resets then the start_time should also be reset. 156 * 157 * @since 0.17 158 */ 159 CUMULATIVE_DISTRIBUTION, 160 161 /** 162 * Some frameworks implemented DISTRIBUTION as a summary of observations (usually things like 163 * request durations and response sizes). While it also provides a total count of observations 164 * and a sum of all observed values, it calculates configurable quantiles over a sliding time 165 * window. 166 * 167 * <p>This is not recommended, since it cannot be aggregated. 168 * 169 * @since 0.17 170 */ 171 SUMMARY, 172 } 173 } 174