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