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.common.Timestamp;
22 import io.opencensus.internal.Utils;
23 import io.opencensus.metrics.LabelKey;
24 import io.opencensus.metrics.LabelValue;
25 import java.util.ArrayList;
26 import java.util.Collections;
27 import java.util.List;
28 import javax.annotation.Nullable;
29 import javax.annotation.concurrent.Immutable;
30 
31 /**
32  * A collection of data points that describes the time-varying values of a {@code Metric}.
33  *
34  * @since 0.17
35  */
36 @ExperimentalApi
37 @Immutable
38 @AutoValue
39 public abstract class TimeSeries {
40 
TimeSeries()41   TimeSeries() {}
42 
43   /**
44    * Creates a {@link TimeSeries}.
45    *
46    * @param labelValues the {@code LabelValue}s that uniquely identify this {@code TimeSeries}.
47    * @param points the data {@code Point}s of this {@code TimeSeries}.
48    * @param startTimestamp the start {@code Timestamp} of this {@code TimeSeries}. Must be non-null
49    *     for cumulative {@code Point}s.
50    * @return a {@code TimeSeries}.
51    * @since 0.17
52    */
create( List<LabelValue> labelValues, List<Point> points, @Nullable Timestamp startTimestamp)53   public static TimeSeries create(
54       List<LabelValue> labelValues, List<Point> points, @Nullable Timestamp startTimestamp) {
55     Utils.checkNotNull(points, "points");
56     Utils.checkListElementNotNull(points, "point");
57     return createInternal(
58         labelValues, Collections.unmodifiableList(new ArrayList<Point>(points)), startTimestamp);
59   }
60 
61   /**
62    * Creates a {@link TimeSeries}.
63    *
64    * @param labelValues the {@code LabelValue}s that uniquely identify this {@code TimeSeries}.
65    * @param point the single data {@code Point} of this {@code TimeSeries}.
66    * @param startTimestamp the start {@code Timestamp} of this {@code TimeSeries}. Must be non-null
67    *     for cumulative {@code Point}s.
68    * @return a {@code TimeSeries}.
69    * @since 0.17
70    */
createWithOnePoint( List<LabelValue> labelValues, Point point, @Nullable Timestamp startTimestamp)71   public static TimeSeries createWithOnePoint(
72       List<LabelValue> labelValues, Point point, @Nullable Timestamp startTimestamp) {
73     Utils.checkNotNull(point, "point");
74     return createInternal(labelValues, Collections.singletonList(point), startTimestamp);
75   }
76 
77   /**
78    * Creates a {@link TimeSeries}.
79    *
80    * @param labelValues the {@code LabelValue}s that uniquely identify this {@code TimeSeries}.
81    * @param points the data {@code Point}s of this {@code TimeSeries}.
82    * @param startTimestamp the start {@code Timestamp} of this {@code TimeSeries}. Must be non-null
83    *     for cumulative {@code Point}s.
84    * @return a {@code TimeSeries}.
85    */
createInternal( List<LabelValue> labelValues, List<Point> points, @Nullable Timestamp startTimestamp)86   private static TimeSeries createInternal(
87       List<LabelValue> labelValues, List<Point> points, @Nullable Timestamp startTimestamp) {
88     // Fail fast on null lists to prevent NullPointerException when copying the lists.
89     Utils.checkNotNull(labelValues, "labelValues");
90     Utils.checkListElementNotNull(labelValues, "labelValue");
91     return new AutoValue_TimeSeries(
92         Collections.unmodifiableList(new ArrayList<LabelValue>(labelValues)),
93         points,
94         startTimestamp);
95   }
96 
97   /**
98    * Returns the set of {@link LabelValue}s that uniquely identify this {@link TimeSeries}.
99    *
100    * <p>Apply to all {@link Point}s.
101    *
102    * <p>The order of {@link LabelValue}s must match that of {@link LabelKey}s in the {@code
103    * MetricDescriptor}.
104    *
105    * @return the {@code LabelValue}s.
106    * @since 0.17
107    */
getLabelValues()108   public abstract List<LabelValue> getLabelValues();
109 
110   /**
111    * Returns the data {@link Point}s of this {@link TimeSeries}.
112    *
113    * @return the data {@code Point}s.
114    * @since 0.17
115    */
getPoints()116   public abstract List<Point> getPoints();
117 
118   /**
119    * Returns the start {@link Timestamp} of this {@link TimeSeries} if the {@link Point}s are
120    * cumulative, or {@code null} if the {@link Point}s are gauge.
121    *
122    * @return the start {@code Timestamp} or {@code null}.
123    * @since 0.17
124    */
125   @Nullable
getStartTimestamp()126   public abstract Timestamp getStartTimestamp();
127 }
128