[API Proposal]: provide some common used histogram bucket boundaries
- Dominant language
- C#
- Stars
- 18.3k
- Forks
- 5.6k
- PR merge metrics
- PR metrics pending
Description
### Background and motivation
When we want to create a histogram metrics, it's better to specify the buckets to keep the metrics making sense, and it would be great if we could provide some built-in histogram buckets advices, for example, http request duration, it would be helpful for both http client request duration metrics and asp.net core web server request duration metrics, and some operations likes that duration
- https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md#metric-httpserverrequestduration
- https://github.com/dotnet/aspnetcore/blob/fdb85879beb744398982b0f2eea50da0fa93b329/src/Shared/Metrics/MetricsConstants.cs#L10-L12
- https://github.com/dotnet/runtime/blob/df846d69e1666f9c6060f2487975b568f3ed93bb/src/libraries/System.Net.Http/src/System/Net/Http/DiagnosticsHelper.cs#L13-L19
### API Proposal
```csharp
namespace System.Diagnostics.Metrics;
public sealed class HistogramBucketBoundaries
{
// Follows boundaries from http.server.request.duration/http.client.request.duration
public static readonly IReadOnlyList CommonDuration = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
}
```
### API Usage
```csharp
var consumeDurationMetrics = new Meter("ConsumerMetrics")
.CreateHistogram(
"consume.duration",
unit: "s",
description: "Duration of Consumer handling process.",
advice: HistogramBucketBoundaries.CommonDuration
);
var startTimestamp = Stopwatch.GetTimestamp();
// processing ..
var duration = Stopwatch.GetElapsedTime(startTimestamp);
consumeDurationMetrics.Record(duration.TotalSeconds);
```
### Alternative Designs
_No response_
### Risks
_No response_
Contributor guide
Research direction
Start by reviewing the proposed HistogramBucketBoundaries API in System.Diagnostics.Metrics and compare its CommonDuration values with the referenced OpenTelemetry semantic conventions, ASP.NET Core MetricsConstants.cs, and .NET DiagnosticsHelper.cs. Determine the API shape and compatibility requirements, then validate that the resulting guidance covers the cited HTTP duration use cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100