Home | History | Annotate | Download | only in export 
      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 
     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    */
     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    */
     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    */
     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    */
     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    */
     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    */
    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