Add endpoint metadata to disable HTTP metrics

[JamesNK]

Background and Motivation

.NET 8 added support for metrics to ASP.NET Core. The most commonly used metric is http.server.request.duration, which captures request duration along with many other tags.

Today this metric is always captured, however there are situations where it is useful to disable collection. For example, system endpoints such as health checks and Prometheus scraping. These system endpoints are regularly polled and can distort expected results for people who want metrics to reflect true application usage.

There is high customer interest in solving this issue: #50654

Proposed API

There are two ways to specify metrics are disabled. The first is statically, per-endpoint, using metadata.

Assembly Microsoft.AspNetCore.Http.Abstractions:

namespace Microsoft.AspNetCore.Http.Metadata;

+ public interface IDisableHttpMetricsMetadata
+ {
+ }

Assembly Microsoft.AspNetCore.Http.Extensions:

namespace Microsoft.AspNetCore.Http;

+ public sealed class DisableHttpMetricsAttribute : Attribute, IDisableHttpMetricsMetadata
+ {
+ }

+ public static class HttpMetricsEndpointConventionBuilderExtensions
+ {
+     public static IEndpointConventionBuilder DisableHttpMetrics(this IEndpointConventionBuilder builder);
+ }

The second is dynamically disabling, per-request, using a feature.

namespace Microsoft.AspNetCore.Http.Features;

public interface IHttpMetricsTagsFeature
{
+     // This is a DIM property added to an existing interface.
+     // It's not ideal, but I don't think it is worth adding a new interface.
+     // I believe with a DIM property, setting it does nothing, and it will always return false. This is fine.
+     public bool MetricsDisabled { get; set; }
}

Usage Examples

Controller:

public class SystemController
{
    [DisableHttpMetrics]
    public IActionResult HealthCheck()
    {
        // ...
    }
}

Minimal API:

app.MapPrometheusScrapingEndpoint().DisableHttpMetrics();

Dynamically:

app.Use(async (context, next) =>
{
    // Disable metrics 50% of the time.
    if (Random.Shared.Next(0, 10) % 2 == 0)
    {
        context.Features.GetRequiredFeature<IHttpMetricsTagsFeature>().MetricsDisabled = true;
    }
    await next.Invoke();
});

Alternative Designs

Add a dedicated feature, e.g. IHttpMetricsDisableFeature, that would allow requests (or middleware) to decide whether to disable metrics dynamically.

Risks

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[Tratcher]

I wonder if devs would also exclude long running requests from metrics?

[WeihanLi]

In addition to this, what about adding checks before outputting metrics, think it would be more flexible
when there's any filter returned false, metrics should be disabled

public interface IHttpMetricsFilter
{
    Task<bool> InvokeAsync(HttpContext httpContext);
}

[halter73]

Would this affect the "http.server.active_requests" metric? If so, how would that work given that it's incremented before routing and the metric is tracked by the IHttpApplication? If not, would it be better to call this something like [DisableRequestDurationMetrics]?

[DisableHttpMetrics] sounds very broad. Is there anything other than the "http.server.request.duration" metric you could foresee us wanting to disable based on this metadata? If excluding requests from the "http.server.request.duration" metric is the primary motivator for this metadata as #50654 suggests, we wouldn't want to have people unintentionally opting out of getting other "http" metrics for that endpoint just because they didn't want warnings for long request durations.

Also, would we use this by default for relevant SignalR/Blazor endpoints? It seems safer to do if it just affects the request duration metric. @BrennanConroy

[halter73]

Also, the IEndpointConventionBuilder extension method should probably do the TBuilder thing for better chaining.

[halter73]

API review notes:

• Should we put "Duration" in the API?
  • "http.server.request.duration" is the uber metric for HTTP requests. Making this metadata too focused on "duration" would imply that other details about the request are recorded when they wouldn't be.
• Let's do the TBuilder pattern for the IEndpointConventionBuilder extension method.
• Should IHttpMetricsTagsFeature be IHttpMetricsDisableFeature or a more generic IHttpMetricsFeature?
• Could IHttpMetricsTagsFeature.MetricsDisabled be a method instead? DisableMetrics()?
  • There's no point adding tags if the metrics feature is disabled, that makes it potentially useful to people using the IHttpMetricsTagsFeature.
  • Or we could add a method to disable metrics and keep a get-only property.
• Are names like [DisableHttpMetrics] too broad when in namespaces like Microsoft.AspNetCore.Http? Would people think it does more like disable logging?
  • There's no namespace for types specific to ASP.NET Core metrics yet, and we didn't want to add it for this.
  • This is something the core framework does and refers to as "metrics" or "meters". We don't use "metric" in other places to refer to other things.

API Approved!

// Microsoft.AspNetCore.Http.Abstractions.dll
namespace Microsoft.AspNetCore.Http.Metadata;

+ public interface IDisableHttpMetricsMetadata
+ {
+ }

// Microsoft.AspNetCore.Http.Extensions.dll
+ public sealed class DisableHttpMetricsAttribute : Attribute, IDisableHttpMetricsMetadata
+ {
+ }

+ public static class HttpMetricsEndpointConventionBuilderExtensions
+ {
+     public static TBuilder DisableHttpMetrics<TBuilder>(this TBuilder builder) where TBuilder : IEndpointConventionBuilder;
+ }

// Microsoft.AspNetCore.Http.Features.dll
namespace Microsoft.AspNetCore.Http.Features;

public interface IHttpMetricsTagsFeature
{
+     public bool MetricsDisabled
+    {
+        get => false;
+        set => { }
+    }
}