initial version

.gitignore

@@ -17,3 +17,6 @@
 
 # Vim
 .swp
+
+# Generated code
+/gen/

opentelemetry/proto/metrics/v1/metrics.proto

@@ -484,9 +484,6 @@ message DoubleHistogramDataPoint {
   // Otherwise all option fields and "buckets" field must be omitted in which case the
   // distribution of values in the histogram is unknown and only the total count and sum are known.
 
-  // explicit_bounds is the only supported bucket option currently.
-  // TODO: Add more bucket options.
-
   // explicit_bounds specifies buckets with explicitly defined bounds for values.
   // The bucket boundaries are described by "bounds" field.
   //
@@ -506,6 +503,96 @@ message DoubleHistogramDataPoint {
   // (Optional) List of exemplars collected from
   // 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
+
+  LinearBounds linear_bounds = 9;
+  ExponentialBounds exponential_bounds = 10;
+
+  // LinearBounds. Bounds can be generated via
+  // for (int i = 0; i < num_of_bounds; i++)
+  //     bounds[i] = 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.
+  // 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)
+    //
+    // 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
+    // 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.
+
+    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.
+    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)
+    //
+    // 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.
+
+    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.
+
+    uint32 num_of_linear_subbuckets = 8;
+  }
 }
 
 // A representation of an exemplar, which is a sample input int measurement.