Skip to content

Commit

Permalink
refinement
Browse files Browse the repository at this point in the history
  • Loading branch information
@yzhuge
yzhuge committed Oct 24, 2020
1 parent 0b3cc20 commit 6c68c14
Showing 1 changed file with 61 additions and 54 deletions.
115 changes: 61 additions & 54 deletions opentelemetry/proto/metrics/v1/metrics.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ message IntSum {
// as a sum of all reported measurements over a time interval.
message DoubleSum {
repeated DoubleDataPoint data_points = 1;

// aggregation_temporality describes if the aggregator reports delta changes
// since last report time, or cumulative changes since a fixed start time.
AggregationTemporality aggregation_temporality = 2;
Expand Down Expand Up @@ -504,94 +504,101 @@ message DoubleHistogramDataPoint {
// measurements that were used to form the data point
repeated DoubleExemplar exemplars = 8;

// When bounds have a pattern, an alternate method may be used to encode them, reducing message size.
// Only one of explicit_bounds, linear_bounds, exponential_bounds should be defined.
// For performance reason, "oneof" is not used. When more than one methods are defined,
// the consumer will use only one in the precedence of:
// explicit_bounds, linear_bounds, exponential_bounds

// When bounds have a pattern, an alternate encoding method may be used.
// Only one method should be defined. For performance reason, "oneof" is not used.
// When more than one methods are defined, the receiver will use only one in the precedence of:
// explicit_bounds, linear_bounds, exponential_bounds, log_linear_bounds
LinearBounds linear_bounds = 9;
ExponentialBounds exponential_bounds = 10;
LogLinearBounds log_linear_bounds = 11;

// LinearBounds. Bounds can be generated via
// for (int i = 0; i < num_of_bounds; i++)
// bounds[i] = offset + width * i
// boundList.add(offset + width * i);
message LinearBounds {
double offset = 1;
double width = 2;
uint32 num_of_bounds = 3;
}

// ExponentialBounds. Bounds are on log scale.
// The bound sequence is stitched together with negative bounds, zero bound, and positive bounds.
// Formula to generate explicit bounds from exponential bounds here are for demonstration purpose only.
// If the message receiver natively understands exponential histograms, it will not need to generate every bound.
// The bound sequence is stitched together using negative bounds, zero bound, and positive bounds.
// The formula to generate explicit bounds here are for demonstration purpose only.
// If the message receiver natively stores exponential histograms, it will not need to generate explicit bound.
// It will only need to convert exponential bound parameters to its native parameters.
message ExponentialBounds {
double reference = 1;
double base = 2;

// The bound sequence starts with negative values generated via:
// for (int i = index_offset_for_negative_numbers + num_of_bounds_for_negative_numbers - 1;
// i <= index_offset_for_negative_numbers;
// i--)
// bound[i] = -1 * reference * (base ^ i)
// for (int i = num_of_bounds_for_negative_numbers - 1; i >= 0; i--)
// int exponent = i + index_offset_for_negative_numbers;
// boundList.add( -1 * reference * power(base, exponent));
//
// Example of reference=1, base=2, index_offset_for_negative_numbers=-2, num_of_bounds_for_negative_numbers=6
// bounds: -8 -4 -2 -1 -.5 -.25
// i: 3 2 1 0 -1 -2
// bounds: -8 -4 -2 -1 -.5 -.25
// exponent: 3 2 1 0 -1 -2
// Note that the loop on i goes down, so that negative numbers with larger absolute values
// (but smaller arithmetic values) come first.
// num_of_bounds_for_negative_numbers may be zero if there are no negative numbers.
// (but smaller arithmetic values) are added first.

sint32 index_offset_for_negative_numbers = 3;
uint32 num_of_bounds_for_negative_numbers = 4;

// If has_counter_for_zero is true, a bound of zero follows the negative bounds.
// If has_counter_for_zero is true, add a bound of zero using:
// boundList.add(0);
bool has_counter_for_zero = 5;

// Positive bounds follow the zero bound. Positive bounds are generated via:
// for (int i = index_offset_for_positive_numbers;
// i <= index_offset_for_positive_numbers + num_of_bounds_for_positive_numbers - 1;
// i++)
// bound[i] = reference * (base ^ i)
// for (int i = 0; i < num_of_bounds_for_positive_numbers; i++)
// int exponent = i + index_offset_for_positive_numbers;
// boundList.add( reference * power(base, exponent));
//
// Example of reference=1, base=2, index_offset_for_positive_numbers=-3, num_of_bounds_for_positive_numbers=8
// bound: .125 .25 .5 1 2 4 8 16
// i: -3 -2 -1 0 1 2 3 4
// num_of_bounds_for_positive_numbers may be zero if there are no positive numbers.
// bound: .125 .25 .5 1 2 4 8 16
// exponent: -3 -2 -1 0 1 2 3 4

sint32 index_offset_for_positive_numbers = 6;
uint32 num_of_bounds_for_positive_numbers = 7;
}

// Certain histograms (such as HdrHistogram) further divide an exponential bucket
// into multiple linear subbuckets.
// num_of_linear_subbuckets at 1 or 0 (default) means no linear subbuckets.
// Example of reference 1, base 2 exponential buckets, with 4 linear subbuckets:
// bound: .5 .625 .75 .875 1 1.25 1.5 1.75 2 2.5 3 3.5 4
// i: -4 -3 -2 -1 0 1 2 3 4 5 6 7 8

// When num_of_linear_subbuckets is greater than 1, positive bounds are computed as:
// for (int i = index_offset_for_positive_numbers;
// i <= index_offset_for_positive_numbers + num_of_bounds_for_positive_numbers - 1;
// i++)
// int exponent;
// int subbucketNumber; // In the range of [0, num_of_linear_subbuckets - 1]
// if (i >= 0) {
// exponent = i / num_of_linear_subbuckets;
// subbucketNumber = i % num_of_linear_subbuckets;
// } else {
// exponent = (i - num_of_linear_subbuckets + 1) / num_of_linear_subbuckets; // Round down toward -infinity
// subbucketNumber = i - exponent * num_of_linear_subbuckets;
// }
// double bucketStart = reference * (base ^ exponent);
// double bucketWidth = bucketStart * (base - 1);
// bound[i] = bucketStart + bucketWidth * (subbucketNumber / num_of_linear_subbuckets)
//
// For negative bounds, the formula is similar, except that index loop will go down and bound[i] will be converted
// negative number.
// In LogLinearBounds, each exponential bucket is divided linearly into multiple subbuckets.
// LogLinearBounds is an extension of ExponentialBounds. Similar to ExponentialBounds,
// the bound sequence is stitched together using negative bounds, zero bound, and positive bounds.
//
// Example of LogLinearBounds with num_of_linear_subbuckets=4 on ExponentialBounds of
// reference=1, base=2, index_offset_for_positive_numbers=-4, num_of_bounds_for_positive_numbers=15,
//
// bound: .5 .625 .75 .875 1 1.25 1.5 1.75 2 2.5 3 3.5 4 5 6
// index: -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9 10
//
// Note: Index need not start or end on multiples of num_of_linear_subbuckets.
//
// Positive bounds are computed as:
// for (int count = 0; count < num_of_bounds_for_positive_numbers; count++)
// int i = count + index_offset_for_positive_numbers;
// int exponent;
// int subbucketNumber; // In the range of [0, num_of_linear_subbuckets - 1]
// if (i >= 0) {
// exponent = i / num_of_linear_subbuckets;
// subbucketNumber = i % num_of_linear_subbuckets;
// } else {
// exponent = (i - num_of_linear_subbuckets + 1) / num_of_linear_subbuckets; // Round down toward -infinity
// subbucketNumber = i - exponent * num_of_linear_subbuckets;
// }
// double bucketStart = reference * power(base, exponent);
// double bucketWidth = bucketStart * (base - 1);
// // Add a fraction of bucketWidth to bucketStart to get the bound.
// boundList.add( bucketStart + bucketWidth * ((double)subbucketNumber / num_of_linear_subbuckets));
//
// For negative bounds, the formula is similar, except that the index loop will go down and the bound will be converted
// to a negative number.
//
// If has_counter_for_zero is true, add a zero bound between negative and positive bounds.
// There are no subbuckets between last negative bucket and 0, or between 0 and first positive bucket.

uint32 num_of_linear_subbuckets = 8;
message LogLinearBounds {
ExponentialBounds exponential_bounds = 1;
uint32 num_of_linear_subbuckets = 2;
}
}

Expand Down

0 comments on commit 6c68c14

Please sign in to comment.