Rename histogram configuration bucketbounds to boundaries (#2638)

docs/metrics/customizing-the-sdk/Program.cs

@@ -33,8 +33,8 @@ public static void Main(string[] args)
             // Rename an instrument to new name.
             .AddView(instrumentName: "MyCounter", name: "MyCounterRenamed")
 
-            // Change Histogram bounds
-            .AddView(instrumentName: "MyHistogram", new HistogramConfiguration() { BucketBounds = new double[] { 10, 20 } })
+            // Change Histogram boundaries
+            .AddView(instrumentName: "MyHistogram", new ExplicitBucketHistogramConfiguration() { Boundaries = new double[] { 10, 20 } })
 
             // For the instrument "MyCounterCustomTags", aggregate with only the keys "tag1", "tag2".
             .AddView(instrumentName: "MyCounterCustomTags", new MetricStreamConfiguration() { TagKeys = new string[] { "tag1", "tag2" } })
@@ -48,7 +48,7 @@ public static void Main(string[] args)
                  if (instrument.Meter.Name.Equals("CompanyA.ProductB.Library2") &&
                      instrument.GetType().Name.Contains("Histogram"))
                  {
-                     return new HistogramConfiguration() { BucketBounds = new double[] { 10, 20 } };
+                     return new ExplicitBucketHistogramConfiguration() { Boundaries = new double[] { 10, 20 } };
                  }
 
                  return null;

docs/metrics/customizing-the-sdk/README.md

@@ -218,30 +218,31 @@ with the metric are of interest to you.
       })
 ```
 
-#### Specify custom bounds for Histogram
+#### Specify custom boundaries for Histogram
 
-By default, the bounds used for a Histogram are [`{ 0, 5, 10, 25, 50, 75, 100,
+By default, the boundaries used for a Histogram are [`{ 0, 5, 10, 25, 50, 75, 100,
 250, 500,
 1000}`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#explicit-bucket-histogram-aggregation).
-Views can be used to provide custom bounds for a Histogram. The measurements are
-then aggregated using the custom bounds provided instead of the the default
-bounds. This requires the use of `HistogramConfiguration`.
+Views can be used to provide custom boundaries for a Histogram. The measurements
+are then aggregated using the custom boundaries provided instead of the the
+default boundaries. This requires the use of `ExplicitBucketHistogramConfiguration`.
 
 ```csharp
-   // Change Histogram bounds to count measurements under the following buckets:
+   // Change Histogram boundaries to count measurements under the following buckets:
    // (-inf, 10]
    // (10, 20]
    // (20, +inf)
    .AddView(
       instrumentName: "MyHistogram",
-      new HistogramConfiguration{ BucketBounds = new double[] { 10, 20 } })
+      new ExplicitBucketHistogramConfiguration
+        { Boundaries = new double[] { 10, 20 } })
 
-   // If you provide an empty `double` array as `BucketBounds` to the `HistogramConfiguration`,
+   // If you provide an empty `double` array as `Boundaries` to the `ExplicitBucketHistogramConfiguration`,
    // the SDK will only export the sum and count for the measurements.
    // There are no buckets exported in this case.
    .AddView(
       instrumentName: "MyHistogram",
-      new HistogramConfiguration { BucketBounds = new double[] { } })
+      new ExplicitBucketHistogramConfiguration { Boundaries = new double[] { } })
 ```
 
 ```csharp
@@ -251,10 +252,10 @@ bounds. This requires the use of `HistogramConfiguration`.
          if (instrument.Meter.Name == "CompanyA.ProductB.LibraryC" &&
             instrument.Name == "MyHistogram")
          {
-            // `HistogramConfiguration` is a child class of `MetricStreamConfiguration`
-            return new HistogramConfiguration
+            // `ExplicitBucketHistogramConfiguration` is a child class of `MetricStreamConfiguration`
+            return new ExplicitBucketHistogramConfiguration
             {
-               BucketBounds = new double[] { 10, 20 },
+               Boundaries = new double[] { 10, 20 },
             };
          }
 

src/OpenTelemetry/.publicApi/net461/PublicAPI.Unshipped.txt

@@ -35,10 +35,10 @@ OpenTelemetry.Metrics.ExportModes.Push = 1 -> OpenTelemetry.Metrics.ExportModes
 OpenTelemetry.Metrics.ExportModesAttribute
 OpenTelemetry.Metrics.ExportModesAttribute.ExportModesAttribute(OpenTelemetry.Metrics.ExportModes supported) -> void
 OpenTelemetry.Metrics.ExportModesAttribute.Supported.get -> OpenTelemetry.Metrics.ExportModes
-OpenTelemetry.Metrics.HistogramConfiguration
-OpenTelemetry.Metrics.HistogramConfiguration.BucketBounds.get -> double[]
-OpenTelemetry.Metrics.HistogramConfiguration.BucketBounds.set -> void
-OpenTelemetry.Metrics.HistogramConfiguration.HistogramConfiguration() -> void
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Boundaries.get -> double[]
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Boundaries.set -> void
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.ExplicitBucketHistogramConfiguration() -> void
 OpenTelemetry.Metrics.IPullMetricExporter
 OpenTelemetry.Metrics.IPullMetricExporter.Collect.get -> System.Func<int, bool>
 OpenTelemetry.Metrics.IPullMetricExporter.Collect.set -> void
@@ -100,8 +100,8 @@ override OpenTelemetry.Metrics.BaseExportingMetricReader.Dispose(bool disposing)
 override OpenTelemetry.Metrics.BaseExportingMetricReader.OnCollect(int timeoutMilliseconds) -> bool
 override OpenTelemetry.Metrics.BaseExportingMetricReader.OnShutdown(int timeoutMilliseconds) -> bool
 override OpenTelemetry.Metrics.BaseExportingMetricReader.ProcessMetrics(in OpenTelemetry.Batch<OpenTelemetry.Metrics.Metric> metrics, int timeoutMilliseconds) -> bool
-override OpenTelemetry.Metrics.HistogramConfiguration.Aggregation.get -> OpenTelemetry.Metrics.Aggregation
-override OpenTelemetry.Metrics.HistogramConfiguration.Aggregation.set -> void
+override OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Aggregation.get -> OpenTelemetry.Metrics.Aggregation
+override OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Aggregation.set -> void
 override OpenTelemetry.Metrics.MeterProviderBuilderBase.AddInstrumentation<TInstrumentation>(System.Func<TInstrumentation> instrumentationFactory) -> OpenTelemetry.Metrics.MeterProviderBuilder
 override OpenTelemetry.Metrics.MeterProviderBuilderBase.AddMeter(params string[] names) -> OpenTelemetry.Metrics.MeterProviderBuilder
 override OpenTelemetry.Metrics.PeriodicExportingMetricReader.Dispose(bool disposing) -> void

src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt

@@ -35,10 +35,10 @@ OpenTelemetry.Metrics.ExportModes.Push = 1 -> OpenTelemetry.Metrics.ExportModes
 OpenTelemetry.Metrics.ExportModesAttribute
 OpenTelemetry.Metrics.ExportModesAttribute.ExportModesAttribute(OpenTelemetry.Metrics.ExportModes supported) -> void
 OpenTelemetry.Metrics.ExportModesAttribute.Supported.get -> OpenTelemetry.Metrics.ExportModes
-OpenTelemetry.Metrics.HistogramConfiguration
-OpenTelemetry.Metrics.HistogramConfiguration.BucketBounds.get -> double[]
-OpenTelemetry.Metrics.HistogramConfiguration.BucketBounds.set -> void
-OpenTelemetry.Metrics.HistogramConfiguration.HistogramConfiguration() -> void
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Boundaries.get -> double[]
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Boundaries.set -> void
+OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.ExplicitBucketHistogramConfiguration() -> void
 OpenTelemetry.Metrics.IPullMetricExporter
 OpenTelemetry.Metrics.IPullMetricExporter.Collect.get -> System.Func<int, bool>
 OpenTelemetry.Metrics.IPullMetricExporter.Collect.set -> void
@@ -100,8 +100,8 @@ override OpenTelemetry.Metrics.BaseExportingMetricReader.Dispose(bool disposing)
 override OpenTelemetry.Metrics.BaseExportingMetricReader.OnCollect(int timeoutMilliseconds) -> bool
 override OpenTelemetry.Metrics.BaseExportingMetricReader.OnShutdown(int timeoutMilliseconds) -> bool
 override OpenTelemetry.Metrics.BaseExportingMetricReader.ProcessMetrics(in OpenTelemetry.Batch<OpenTelemetry.Metrics.Metric> metrics, int timeoutMilliseconds) -> bool
-override OpenTelemetry.Metrics.HistogramConfiguration.Aggregation.get -> OpenTelemetry.Metrics.Aggregation
-override OpenTelemetry.Metrics.HistogramConfiguration.Aggregation.set -> void
+override OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Aggregation.get -> OpenTelemetry.Metrics.Aggregation
+override OpenTelemetry.Metrics.ExplicitBucketHistogramConfiguration.Aggregation.set -> void
 override OpenTelemetry.Metrics.MeterProviderBuilderBase.AddInstrumentation<TInstrumentation>(System.Func<TInstrumentation> instrumentationFactory) -> OpenTelemetry.Metrics.MeterProviderBuilder
 override OpenTelemetry.Metrics.MeterProviderBuilderBase.AddMeter(params string[] names) -> OpenTelemetry.Metrics.MeterProviderBuilder
 override OpenTelemetry.Metrics.PeriodicExportingMetricReader.Dispose(bool disposing) -> void

src/OpenTelemetry/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+* Renamed `HistogramConfiguration` to `ExplicitBucketHistogramConfiguration`
+  and changed its member `BucketBounds` to `Boundaries`.
+  ([#2638](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2638))
+
 * Metrics with the same name but from different meters are allowed.
   ([#2634](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2634))
 

src/OpenTelemetry/Metrics/HistogramConfiguration.cs → src/OpenTelemetry/Metrics/ExplicitBucketHistogramConfiguration.cs

@@ -1,4 +1,4 @@
-// <copyright file="HistogramConfiguration.cs" company="OpenTelemetry Authors">
+// <copyright file="ExplicitBucketHistogramConfiguration.cs" company="OpenTelemetry Authors">
 // Copyright The OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -18,17 +18,18 @@
 
 namespace OpenTelemetry.Metrics
 {
-    public class HistogramConfiguration : MetricStreamConfiguration
+    public class ExplicitBucketHistogramConfiguration : MetricStreamConfiguration
     {
         private Aggregation aggregation = Aggregation.Histogram;
 
         /// <summary>
-        /// Gets or sets the custom histogram bounds.
+        /// Gets or sets the values representing explicit histogram bucket
+        /// boundary values.
         /// </summary>
         /// <remarks>
         /// The array must be in ascending order with distinct values.
         /// </remarks>
-        public double[] BucketBounds { get; set; }
+        public double[] Boundaries { get; set; }
 
         public override Aggregation Aggregation
         {

src/OpenTelemetry/Metrics/MeterProviderBuilderExtensions.cs

@@ -86,12 +86,12 @@ public static MeterProviderBuilder AddView(this MeterProviderBuilder meterProvid
                 throw new ArgumentException($"Custom view name {metricStreamConfiguration.Name} is invalid.", nameof(metricStreamConfiguration.Name));
             }
 
-            if (metricStreamConfiguration is HistogramConfiguration histogramConfiguration)
+            if (metricStreamConfiguration is ExplicitBucketHistogramConfiguration histogramConfiguration)
             {
-                // Validate histogram bounds
-                if (histogramConfiguration.BucketBounds != null && !IsSortedAndDistinct(histogramConfiguration.BucketBounds))
+                // Validate histogram boundaries
+                if (histogramConfiguration.Boundaries != null && !IsSortedAndDistinct(histogramConfiguration.Boundaries))
                 {
-                    throw new ArgumentException($"Histogram bounds must be in ascending order with distinct values", nameof(histogramConfiguration.BucketBounds));
+                    throw new ArgumentException($"Histogram boundaries must be in ascending order with distinct values", nameof(histogramConfiguration.Boundaries));
                 }
             }
 

src/OpenTelemetry/Metrics/MeterProviderSdk.cs

@@ -195,8 +195,8 @@ internal MeterProviderSdk(
                                 Metric metric;
                                 var metricDescription = metricStreamConfig?.Description ?? instrument.Description;
                                 string[] tagKeysInteresting = metricStreamConfig?.TagKeys;
-                                double[] histogramBucketBounds = (metricStreamConfig is HistogramConfiguration histogramConfig
-                                    && histogramConfig.BucketBounds != null) ? histogramConfig.BucketBounds : null;
+                                double[] histogramBucketBounds = (metricStreamConfig is ExplicitBucketHistogramConfiguration histogramConfig
+                                    && histogramConfig.Boundaries != null) ? histogramConfig.Boundaries : null;
                                 metric = new Metric(instrument, temporality, metricName, metricDescription, histogramBucketBounds, tagKeysInteresting);
 
                                 this.metrics[index] = metric;

test/OpenTelemetry.Tests/Metrics/AggregatorTest.cs

@@ -59,8 +59,8 @@ public void HistogramDistributeToAllBucketsDefault()
         [Fact]
         public void HistogramDistributeToAllBucketsCustom()
         {
-            var bounds = new double[] { 10, 20 };
-            var histogramPoint = new MetricPoint(AggregationType.Histogram, DateTimeOffset.Now, null, null, bounds);
+            var boundaries = new double[] { 10, 20 };
+            var histogramPoint = new MetricPoint(AggregationType.Histogram, DateTimeOffset.Now, null, null, boundaries);
 
             // 5 recordings <=10
             histogramPoint.Update(-10);
@@ -80,7 +80,7 @@ public void HistogramDistributeToAllBucketsCustom()
 
             // Count  = # of recordings
             Assert.Equal(7, histogramPoint.LongValue);
-            Assert.Equal(bounds.Length + 1, histogramPoint.BucketCounts.Length);
+            Assert.Equal(boundaries.Length + 1, histogramPoint.BucketCounts.Length);
             Assert.Equal(5, histogramPoint.BucketCounts[0]);
             Assert.Equal(2, histogramPoint.BucketCounts[1]);
             Assert.Equal(0, histogramPoint.BucketCounts[2]);
@@ -89,8 +89,8 @@ public void HistogramDistributeToAllBucketsCustom()
         [Fact]
         public void HistogramWithOnlySumCount()
         {
-            var bounds = new double[] { };
-            var histogramPoint = new MetricPoint(AggregationType.HistogramSumCount, DateTimeOffset.Now, null, null, bounds);
+            var boundaries = new double[] { };
+            var histogramPoint = new MetricPoint(AggregationType.HistogramSumCount, DateTimeOffset.Now, null, null, boundaries);
 
             histogramPoint.Update(-10);
             histogramPoint.Update(0);

test/OpenTelemetry.Tests/Metrics/MetricTestData.cs

@@ -41,7 +41,7 @@ public static IEnumerable<object[]> ValidInstrumentNames
                     new object[] { new string('m', 63) },
            };
 
-        public static IEnumerable<object[]> InvalidHistogramBounds
+        public static IEnumerable<object[]> InvalidHistogramBoundaries
            => new List<object[]>
            {
                     new object[] { new double[] { 0, 0 } },

test/OpenTelemetry.Tests/Metrics/MetricViewTests.cs

@@ -93,13 +93,13 @@ public void AddViewWithNullMetricStreamConfigurationThrowsArgumentnullException(
         }
 
         [Theory]
-        [MemberData(nameof(MetricTestData.InvalidHistogramBounds), MemberType = typeof(MetricTestData))]
-        public void AddViewWithInvalidHistogramBoundsThrowsArgumentException(double[] bounds)
+        [MemberData(nameof(MetricTestData.InvalidHistogramBoundaries), MemberType = typeof(MetricTestData))]
+        public void AddViewWithInvalidHistogramBoundsThrowsArgumentException(double[] boundaries)
         {
             var ex = Assert.Throws<ArgumentException>(() => Sdk.CreateMeterProviderBuilder()
-                .AddView("name1", new HistogramConfiguration { BucketBounds = bounds }));
+                .AddView("name1", new ExplicitBucketHistogramConfiguration { Boundaries = boundaries }));
 
-            Assert.Contains("Histogram bounds must be in ascending order with distinct values", ex.Message);
+            Assert.Contains("Histogram boundaries must be in ascending order with distinct values", ex.Message);
         }
 
         [Theory]
@@ -355,11 +355,11 @@ public void ViewToProduceCustomHistogramBound()
         {
             using var meter = new Meter(Utils.GetCurrentMethodName());
             var exportedItems = new List<Metric>();
-            var bounds = new double[] { 10, 20 };
+            var boundaries = new double[] { 10, 20 };
             using var meterProvider = Sdk.CreateMeterProviderBuilder()
                 .AddMeter(meter.Name)
-                .AddView("MyHistogram", new HistogramConfiguration() { Name = "MyHistogramDefaultBound" })
-                .AddView("MyHistogram", new HistogramConfiguration() { BucketBounds = bounds })
+                .AddView("MyHistogram", new ExplicitBucketHistogramConfiguration() { Name = "MyHistogramDefaultBound" })
+                .AddView("MyHistogram", new ExplicitBucketHistogramConfiguration() { Boundaries = boundaries })
                 .AddInMemoryExporter(exportedItems)
                 .Build();
 
@@ -409,7 +409,7 @@ public void ViewToProduceCustomHistogramBound()
 
             Assert.Equal(40, histogramPoint.DoubleValue);
             Assert.Equal(7, histogramPoint.LongValue);
-            Assert.Equal(bounds.Length + 1, histogramPoint.BucketCounts.Length);
+            Assert.Equal(boundaries.Length + 1, histogramPoint.BucketCounts.Length);
             Assert.Equal(5, histogramPoint.BucketCounts[0]);
             Assert.Equal(2, histogramPoint.BucketCounts[1]);
             Assert.Equal(0, histogramPoint.BucketCounts[2]);