dotnet / dotnet/runtime

[API Proposal]: provide some common used histogram bucket boundaries

Open
#132,734 3 comments 0 reactions 0 assignees View on GitHub
api-suggestion area-System.Diagnostics.Metric
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.