From 66d2621170c614313c81fc82e4f6c79218244974 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Wed, 17 Nov 2021 20:26:03 -0800 Subject: [PATCH] Rename histogram configuration bucketbounds to boundaries (#2638) --- docs/metrics/customizing-the-sdk/Program.cs | 6 ++--- docs/metrics/customizing-the-sdk/README.md | 25 ++++++++++--------- .../.publicApi/net461/PublicAPI.Unshipped.txt | 12 ++++----- .../netstandard2.0/PublicAPI.Unshipped.txt | 12 ++++----- src/OpenTelemetry/CHANGELOG.md | 4 +++ ...> ExplicitBucketHistogramConfiguration.cs} | 9 ++++--- .../Metrics/MeterProviderBuilderExtensions.cs | 8 +++--- src/OpenTelemetry/Metrics/MeterProviderSdk.cs | 4 +-- .../Metrics/AggregatorTest.cs | 10 ++++---- .../Metrics/MetricTestData.cs | 2 +- .../Metrics/MetricViewTests.cs | 16 ++++++------ 11 files changed, 57 insertions(+), 51 deletions(-) rename src/OpenTelemetry/Metrics/{HistogramConfiguration.cs => ExplicitBucketHistogramConfiguration.cs} (79%) diff --git a/docs/metrics/customizing-the-sdk/Program.cs b/docs/metrics/customizing-the-sdk/Program.cs index 7e2e9111edd..c6a51ec40ac 100644 --- a/docs/metrics/customizing-the-sdk/Program.cs +++ b/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; diff --git a/docs/metrics/customizing-the-sdk/README.md b/docs/metrics/customizing-the-sdk/README.md index 2fcc67b921f..01c13a963dd 100644 --- a/docs/metrics/customizing-the-sdk/README.md +++ b/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 }, }; } diff --git a/src/OpenTelemetry/.publicApi/net461/PublicAPI.Unshipped.txt b/src/OpenTelemetry/.publicApi/net461/PublicAPI.Unshipped.txt index c22a2f15aa6..fa81310cf4f 100644 --- a/src/OpenTelemetry/.publicApi/net461/PublicAPI.Unshipped.txt +++ b/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 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 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(System.Func instrumentationFactory) -> OpenTelemetry.Metrics.MeterProviderBuilder override OpenTelemetry.Metrics.MeterProviderBuilderBase.AddMeter(params string[] names) -> OpenTelemetry.Metrics.MeterProviderBuilder override OpenTelemetry.Metrics.PeriodicExportingMetricReader.Dispose(bool disposing) -> void diff --git a/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt b/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt index c22a2f15aa6..fa81310cf4f 100644 --- a/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt +++ b/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 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 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(System.Func instrumentationFactory) -> OpenTelemetry.Metrics.MeterProviderBuilder override OpenTelemetry.Metrics.MeterProviderBuilderBase.AddMeter(params string[] names) -> OpenTelemetry.Metrics.MeterProviderBuilder override OpenTelemetry.Metrics.PeriodicExportingMetricReader.Dispose(bool disposing) -> void diff --git a/src/OpenTelemetry/CHANGELOG.md b/src/OpenTelemetry/CHANGELOG.md index 7b2edf66061..c80a6f22c49 100644 --- a/src/OpenTelemetry/CHANGELOG.md +++ b/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)) diff --git a/src/OpenTelemetry/Metrics/HistogramConfiguration.cs b/src/OpenTelemetry/Metrics/ExplicitBucketHistogramConfiguration.cs similarity index 79% rename from src/OpenTelemetry/Metrics/HistogramConfiguration.cs rename to src/OpenTelemetry/Metrics/ExplicitBucketHistogramConfiguration.cs index 9f6d12e289b..59311583843 100644 --- a/src/OpenTelemetry/Metrics/HistogramConfiguration.cs +++ b/src/OpenTelemetry/Metrics/ExplicitBucketHistogramConfiguration.cs @@ -1,4 +1,4 @@ -// +// // 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; /// - /// Gets or sets the custom histogram bounds. + /// Gets or sets the values representing explicit histogram bucket + /// boundary values. /// /// /// The array must be in ascending order with distinct values. /// - public double[] BucketBounds { get; set; } + public double[] Boundaries { get; set; } public override Aggregation Aggregation { diff --git a/src/OpenTelemetry/Metrics/MeterProviderBuilderExtensions.cs b/src/OpenTelemetry/Metrics/MeterProviderBuilderExtensions.cs index 043225fd8d2..233d0cdd3a5 100644 --- a/src/OpenTelemetry/Metrics/MeterProviderBuilderExtensions.cs +++ b/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)); } } diff --git a/src/OpenTelemetry/Metrics/MeterProviderSdk.cs b/src/OpenTelemetry/Metrics/MeterProviderSdk.cs index 2771ded7a74..c6de1775113 100644 --- a/src/OpenTelemetry/Metrics/MeterProviderSdk.cs +++ b/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; diff --git a/test/OpenTelemetry.Tests/Metrics/AggregatorTest.cs b/test/OpenTelemetry.Tests/Metrics/AggregatorTest.cs index 46d6f505115..870e60d3040 100644 --- a/test/OpenTelemetry.Tests/Metrics/AggregatorTest.cs +++ b/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); diff --git a/test/OpenTelemetry.Tests/Metrics/MetricTestData.cs b/test/OpenTelemetry.Tests/Metrics/MetricTestData.cs index aab52a57fff..0664dc18c00 100644 --- a/test/OpenTelemetry.Tests/Metrics/MetricTestData.cs +++ b/test/OpenTelemetry.Tests/Metrics/MetricTestData.cs @@ -41,7 +41,7 @@ public static IEnumerable ValidInstrumentNames new object[] { new string('m', 63) }, }; - public static IEnumerable InvalidHistogramBounds + public static IEnumerable InvalidHistogramBoundaries => new List { new object[] { new double[] { 0, 0 } }, diff --git a/test/OpenTelemetry.Tests/Metrics/MetricViewTests.cs b/test/OpenTelemetry.Tests/Metrics/MetricViewTests.cs index a446f160fca..c9dfe79cc61 100644 --- a/test/OpenTelemetry.Tests/Metrics/MetricViewTests.cs +++ b/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(() => 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(); - 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]);