1// Copyright 2016-18, OpenCensus Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package opencensus.proto.stats.v1;
18
19import "google/protobuf/timestamp.proto";
20
21option go_package = "github.com/census-instrumentation/opencensus-proto/gen-go/stats/v1";
22
23option java_multiple_files = true;
24option java_package = "io.opencensus.proto.stats.v1";
25option java_outer_classname = "StatsProto";
26
27option ruby_package = "OpenCensus.Proto.Stats.V1";
28
29// TODO(bdrutu): Consider if this should be moved to a "tags" directory to match the API structure.
30message Tag {
31  string key = 1;
32  string value = 2;
33}
34
35// Measure .
36message Measure {
37  // A string by which the measure will be referred to, e.g. "rpc_server_latency". Names MUST be
38  // unique within the library.
39  string name = 1;
40
41  // Describes the measure, e.g. "RPC latency in seconds".
42  string description = 2;
43
44  // Describes the unit used for the Measure. Follows the format described by
45  // http://unitsofmeasure.org/ucum.html.
46  string unit = 3;
47
48  enum Type {
49    // Unknown type.
50    TYPE_UNSPECIFIED = 0;
51    // Indicates an int64 Measure.
52    INT64 = 1;
53    // Indicates a double Measure.
54    DOUBLE = 2;
55  }
56
57  // The type used for this Measure.
58  Type type = 4;
59}
60
61message View {
62  // A string by which the View will be referred to, e.g. "rpc_latency". Names MUST be unique
63  // within the library.
64  string name = 1;
65
66  // Describes the view, e.g. "RPC latency distribution"
67  string description = 2;
68
69  // The Measure to which this view is applied.
70  Measure measure = 3;
71
72  // An array of tag keys. These values associated with tags of this name form the basis by which
73  // individual stats will be aggregated (one aggregation per unique tag value). If none are
74  // provided, then all data is recorded in a single aggregation.
75  repeated string columns = 4;
76
77  // The description of the aggregation used for this view which describes how data collected are
78  // aggregated.
79  oneof aggregation {
80    // Counts the number of measurements recorded.
81    CountAggregation count_aggregation = 5;
82    // Indicates that data collected and aggregated with this Aggregation will be summed up.
83    SumAggregation sum_aggregation = 6;
84    // Indicates that data collected and aggregated with this Aggregation will represent the last
85    // recorded value. This is useful to support Gauges.
86    LastValueAggregation last_value_aggregation = 7;
87    // Indicates that the desired Aggregation is a histogram distribution. A distribution
88    // Aggregation may contain a histogram of the values in the population. User should define the
89    // bucket boundaries for that histogram (see DistributionAggregation).
90    DistributionAggregation distribution_aggregation = 8;
91  }
92}
93
94message CountAggregation {}
95
96message SumAggregation {}
97
98message LastValueAggregation {}
99
100message DistributionAggregation {
101  // A Distribution may optionally contain a histogram of the values in the
102  // population. The bucket boundaries for that histogram are described by
103  // `bucket_bounds`. This defines `size(bucket_bounds) + 1` (= N)
104  // buckets. The boundaries for bucket index i are:
105  //
106  // (-infinity, bucket_bounds[i]) for i == 0
107  // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-2
108  // [bucket_bounds[i-1], +infinity) for i == N-1
109  //
110  // i.e. an underflow bucket (number 0), zero or more finite buckets (1
111  // through N - 2, and an overflow bucket (N - 1), with inclusive lower
112  // bounds and exclusive upper bounds.
113  //
114  // If `bucket_bounds` has no elements (zero size), then there is no
115  // histogram associated with the Distribution. If `bucket_bounds` has only
116  // one element, there are no finite buckets, and that single element is the
117  // common boundary of the overflow and underflow buckets. The values must
118  // be monotonically increasing.
119  repeated double bucket_bounds = 1;
120}
121
122// Describes a data point to be collected for a Measure.
123message Measurement {
124  repeated Tag tags = 1;
125
126  // The name of the measure to which the value is applied.
127  string measure_name = 2;
128
129  // The recorded value, MUST have the appropriate type to match the Measure.
130  oneof value {
131    double double_value = 3;
132    int64 int_value = 4;
133  }
134
135  // The time when this measurement was recorded. If the implementation uses a async buffer to
136  // record measurements this may be the time when the measurement was read from the buffer.
137  google.protobuf.Timestamp time = 5;
138}
139