open-telemetry
/
opentelemetry-dotnet
mirror of https://github.com/open-telemetry/opentelemetry-dotnet.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rename histogram configuration bucketbounds to boundaries (#2638)

This commit is contained in:
Cijo Thomas 2021-11-17 20:26:03 -08:00 committed by GitHub
parent 1be29c85cc
commit 66d2621170
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 57 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/metrics/customizing-the-sdk/Program.cs
View File

@ -33,8 +33,8 @@ public class Program
// 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 class Program
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;

25
docs/metrics/customizing-the-sdk/README.md
View File

@ -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 },
};
}

12
src/OpenTelemetry/.publicApi/net461/PublicAPI.Unshipped.txt
View File

@ -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

12
src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt
View File

@ -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

4
src/OpenTelemetry/CHANGELOG.md
View File

@ -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))

9
src/OpenTelemetry/Metrics/HistogramConfiguration.cs → src/OpenTelemetry/Metrics/ExplicitBucketHistogramConfiguration.cs
View File

@ -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 @@ using System;
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
{

8
src/OpenTelemetry/Metrics/MeterProviderBuilderExtensions.cs
View File

@ -86,12 +86,12 @@ namespace OpenTelemetry.Metrics
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));
}
}

4
src/OpenTelemetry/Metrics/MeterProviderSdk.cs
View File

@ -195,8 +195,8 @@ namespace OpenTelemetry.Metrics
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;

10
test/OpenTelemetry.Tests/Metrics/AggregatorTest.cs
View File

@ -59,8 +59,8 @@ namespace OpenTelemetry.Metrics.Tests
[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 @@ namespace OpenTelemetry.Metrics.Tests
// 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 @@ namespace OpenTelemetry.Metrics.Tests
[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);

2
test/OpenTelemetry.Tests/Metrics/MetricTestData.cs
View File

@ -41,7 +41,7 @@ namespace OpenTelemetry.Metrics.Tests
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 } },

16
test/OpenTelemetry.Tests/Metrics/MetricViewTests.cs
View File

@ -93,13 +93,13 @@ namespace OpenTelemetry.Metrics.Tests
}
[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 @@ namespace OpenTelemetry.Metrics.Tests
{
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 @@ namespace OpenTelemetry.Metrics.Tests
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]);