Add "hints" in Metric API to provide things like histogram bounds

[tarekgh]

Metrics currently supports the Histogram instrument, which is used to publish measurement data. The data aggregator (such as the OpenTelemetry SDK) divides the full interval of possible values into consecutive, non-overlapping ranges called buckets. The OpenTelemetry SDK currently uses some defaults to define the bucket boundaries, but it also provides a way to customize or configure these boundaries. OpenTelemetry has introduced a new specification that allows creators of the Histogram instrument to specify advised bucket boundary values, which will be the recommended values for Histogram data aggregation.

Explicit bucket boundaries OpenTelemetry specs.

Proposal

namespace System.Diagnostics.Metrics;

+public sealed class HistogramAdvice<T> where T : struct
+{
+    public HistogramAdvice(IEnumerable<T> explicitBucketBoundaries) { ... }
+    public IEnumerable<T> ExplicitBucketBoundaries { get; }
+}

public class Meter
{
    public System.Diagnostics.Metrics.Histogram<T> CreateHistogram<T> (
        string name,
        string? unit = default,
        string? description = default) where T : struct;

    public Histogram<T> CreateHistogram<T>(
        string name,
        string? unit,
        string? description,
        IEnumerable<KeyValuePair<string, object?>>? tags) where T : struct;

+   public System.Diagnostics.Metrics.Histogram<T> CreateHistogram<T> (
+       string name,
+       string? unit,
+       string? description,
+       IEnumerable<KeyValuePair<string, object?>>? tags,
+       HistogramAdvice<T> advice) where T : struct;
}

+public sealed class Histogram<T> : System.Diagnostics.Metrics.Instrument<T> where T : struct
+{
+    public HistogramAdvice<T>? Advice { get; }
+}

Usage Example

private static readonly Meter MyMeter = new("MyApplicationMeter");​

...

Histogram<long> requestLatencyHistogram = MyMeter.CreateHistogram<long>(
                                           name: "RequestLatency", 
                                           unit: "ms", 
                                           description: "Request Latency", 
                                           tags: null, 
                                           new HistogramAdvice<long>(new long[] { 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 }));​

requestLatencyHistogram.Record(150)

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[noahfalk]

No design has materialized yet, moving this out to Future.

[JamesNK]

I have a scenario for using this feature. OpenTelemetry has some default bucket bounds for histograms. However, some histograms have recommended bounds.

For example, http.server.duration recommends some values: https://github.com/open-telemetry/opentelemetry-specification/blob/ce2c5946faa9c961ea01d89c7aed83621865b67b/specification/metrics/semantic_conventions/http-metrics.md#metric-httpserverduration

This metric SHOULD be specified with ExplicitBucketBoundaries of [ 0, 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 ].

ASP.NET Core has a very similar histogram, http-server-request-duration. It should be used with the same bounds.

Currently, someone configuring OpenTelemetry to export meter measurements must use the default bucket bounds. To override, you must add a view for that counter to get the desired bucket sizes.

services
    .AddOpenTelemetry()
        .WithMetrics(metrics =>
        {
            metrics
                .AddView("request-duration", new ExplicitBucketHistogramConfiguration
                {
                    Boundaries = new double[] { 0, 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 }
                })
                .AddMeter("Microsoft.AspNetCore.Hosting", "Microsoft.AspNetCore.Server.Kestrel")
                .AddPrometheusExporter();
        })

https://github.com/bradygaster/dotnet-cloud-native-build-2023/blob/c14269055669823659e7962ef9da4d700e597133/ContosoOnline/Diagnostics/DiagnosticServiceCollectionExtensions.cs#L33-L36

Histograms should support the advice feature to configure recommended explicit bounds: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice

[JamesNK]

API proposal:

namespace System.Diagnostics.Metrics;

+public sealed class HistogramAdvice
+{
+    public IReadOnlyList<double>? ExplicitBucketBoundaries { get; init; }
+}

public class Meter
{
    public System.Diagnostics.Metrics.Histogram<T> CreateHistogram<T> (
        string name,
        string? unit = default,
        string? description = default) where T : struct;
+   public System.Diagnostics.Metrics.Histogram<T> CreateHistogram<T> (
+       string name,
+       string? unit = default,
+       string? description = default,
+       HistogramAdvice? advice = default) where T : struct;
}

+public sealed class Histogram<T> : System.Diagnostics.Metrics.Instrument<T> where T : struct
+{
+    public HistogramAdvice Advice { get; }
+}

Open Questions

• Histogram<T> is based around a generic argument as the numerical type of the measurement. ExplicitBucketBoundaries is currently double. Does it need to be T? What does that mean for APIs that would use this, e.g. opentelemetry-dotnet SDK? The Java prototype of advice uses double boundaries for long and double histogram implementations: Prototype histogram advice API (i.e. Hints) open-telemetry/opentelemetry-java#5217