From 178e8b096326b243610dc267be4cb09a97c87b7e Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 7 Nov 2024 09:44:47 +0800 Subject: [PATCH 1/6] Add metrics opt-out section to metrics doc --- aspnetcore/log-mon/metrics/metrics.md | 21 ++++++++++- .../DisableMetrics/DisableMetrics.csproj | 9 +++++ .../metrics/samples/DisableMetrics/Program.cs | 36 +++++++++++++++++++ 3 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj create mode 100644 aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index 2f8cacf28652..8c73bce015b1 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -90,6 +90,7 @@ For more information, see [dotnet-counters](/dotnet/core/diagnostics/dotnet-coun ## Enrich the ASP.NET Core request metric ASP.NET Core has many built-in metrics. The `http.server.request.duration` metric: + * Records the duration of HTTP requests on the server. * Captures request information in tags, such as the matched route and response status code. @@ -106,7 +107,25 @@ The proceeding example: * The tag allows requests to be categorized by marketing medium type, which could be useful when analyzing web app traffic. > [!NOTE] -> Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Too many tags, or tags with an unbound range cause a large combination of tags. Collection tools have a limit on how many combinations they support for a counter and may start filtering results out to avoid excessive memory usage. +> Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Too many tags, or tags with an unbound range cause a large combination of tags, which creates many dimensions. Collection tools have a limit on how many dimensions they support for a counter and may start filtering results out to avoid excessive memory usage. + +## Opt-out of HTTP metrics on certain endpoints and requests + +Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry costs resources to collect and store, and can distort results displayed in a telemetry dashboard. + +HTTP requests to an endpoint can be excluded from metrics by adding metadata. Either: + +* Add the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute to the Web API controller, SignalR hub or gRPC service. +* Call [DisableHttpMetrics()](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics(TBuilder)) when mapping endpoints in app startup: + +:::code language="csharp" source="~/log-mon/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5"::: + +Alternatively, the property has been added for: + +* Advanced scenarios where a request doesn't map to an endpoint. +* Dynamically disabling metrics collection for specific HTTP requests. + +:::code language="csharp" source="~/log-mon/metrics/samples/DisableMetrics/Program.cs" id="snippet_2"::: ## Create custom metrics diff --git a/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj new file mode 100644 index 000000000000..6568b3dcfb4b --- /dev/null +++ b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj @@ -0,0 +1,9 @@ + + + + net9.0 + enable + enable + + + diff --git a/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs new file mode 100644 index 000000000000..cb94e4c6506f --- /dev/null +++ b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs @@ -0,0 +1,36 @@ +#define SECOND // FIRST SECOND +#if NEVER +#elif FIRST +// +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddHealthChecks(); + +var app = builder.Build(); +app.MapHealthChecks("/healthz").DisableHttpMetrics(); +app.Run(); +// +#elif SECOND +using Microsoft.AspNetCore.Http.Features; + +var builder = WebApplication.CreateBuilder(args); +var app = builder.Build(); + +app.MapGet("/", () => "Hello World!"); + +// +// Middleware that conditionally opts-out HTTP requests. +app.Use(async (context, next) => +{ + var metricsFeature = context.Features.Get(); + if (metricsFeature != null && + context.Request.Headers.ContainsKey("x-disable-metrics")) + { + metricsFeature.MetricsDisabled = true; + } + + await next(context); +}); +// + +app.Run(); +#endif From 8a967aaae9cc4a7bf7a6897649a3a2840360e99a Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Thu, 7 Nov 2024 09:47:30 +0800 Subject: [PATCH 2/6] .NET 9 or later --- aspnetcore/log-mon/metrics/metrics.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index 8c73bce015b1..ef0567cee41e 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -109,6 +109,8 @@ The proceeding example: > [!NOTE] > Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Too many tags, or tags with an unbound range cause a large combination of tags, which creates many dimensions. Collection tools have a limit on how many dimensions they support for a counter and may start filtering results out to avoid excessive memory usage. +:::moniker range=">= aspnetcore-9.0" + ## Opt-out of HTTP metrics on certain endpoints and requests Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry costs resources to collect and store, and can distort results displayed in a telemetry dashboard. @@ -127,6 +129,8 @@ Alternatively, the namespace. See [Create custom metrics](/dotnet/core/diagnostics/metrics-instrumentation#create-a-custom-metric) for information on creating custom metrics. From ed8cf24c4ac0f2de14c0865e7c5ef91b84b3a527 Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Tue, 12 Nov 2024 07:30:08 +0800 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> --- aspnetcore/log-mon/metrics/metrics.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index ef0567cee41e..949637fbe59f 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -107,27 +107,27 @@ The proceeding example: * The tag allows requests to be categorized by marketing medium type, which could be useful when analyzing web app traffic. > [!NOTE] -> Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Too many tags, or tags with an unbound range cause a large combination of tags, which creates many dimensions. Collection tools have a limit on how many dimensions they support for a counter and may start filtering results out to avoid excessive memory usage. +> Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Tags that are too numerous or have an unbound range create many tag combinations, resulting in high dimensions. Collection tools have limits on supported dimensions for a counter and may filter results to prevent excessive memory use. :::moniker range=">= aspnetcore-9.0" ## Opt-out of HTTP metrics on certain endpoints and requests -Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry costs resources to collect and store, and can distort results displayed in a telemetry dashboard. +Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry uses resources to collect and store, and can distort results displayed in a telemetry dashboard. -HTTP requests to an endpoint can be excluded from metrics by adding metadata. Either: +HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the [DisableHttpMetrics()](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics(TBuilder)) method: * Add the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute to the Web API controller, SignalR hub or gRPC service. * Call [DisableHttpMetrics()](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics(TBuilder)) when mapping endpoints in app startup: -:::code language="csharp" source="~/log-mon/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5"::: +:::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5"::: Alternatively, the property has been added for: * Advanced scenarios where a request doesn't map to an endpoint. * Dynamically disabling metrics collection for specific HTTP requests. -:::code language="csharp" source="~/log-mon/metrics/samples/DisableMetrics/Program.cs" id="snippet_2"::: +:::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_2"::: :::moniker-end From 6297b36886b17b44f078e002a755807a713d08be Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Tue, 12 Nov 2024 13:39:49 -0800 Subject: [PATCH 4/6] Update aspnetcore/log-mon/metrics/metrics.md --- aspnetcore/log-mon/metrics/metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index 949637fbe59f..c56dab7b4111 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -115,10 +115,10 @@ The proceeding example: Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry uses resources to collect and store, and can distort results displayed in a telemetry dashboard. -HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the [DisableHttpMetrics()](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics(TBuilder)) method: +HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the method: * Add the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute to the Web API controller, SignalR hub or gRPC service. -* Call [DisableHttpMetrics()](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics(TBuilder)) when mapping endpoints in app startup: +* Call when mapping endpoints in app startup: :::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5"::: From 3c9639655284352b92173418fa0a0f1e1ebf39ae Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Tue, 12 Nov 2024 13:52:55 -0800 Subject: [PATCH 5/6] Update aspnetcore/log-mon/metrics/metrics.md --- aspnetcore/log-mon/metrics/metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index c56dab7b4111..b935b2906e78 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -115,10 +115,10 @@ The proceeding example: Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry uses resources to collect and store, and can distort results displayed in a telemetry dashboard. -HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the method: +HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the method: * Add the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute to the Web API controller, SignalR hub or gRPC service. -* Call when mapping endpoints in app startup: +* Call when mapping endpoints in app startup: :::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5"::: From ed7b7a56fc1b9df73519c49e9fb0132323684596 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Tue, 12 Nov 2024 14:08:53 -0800 Subject: [PATCH 6/6] fix xref link --- aspnetcore/log-mon/metrics/metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index b935b2906e78..f438b55439a1 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -115,10 +115,10 @@ The proceeding example: Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry uses resources to collect and store, and can distort results displayed in a telemetry dashboard. -HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the method: +HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics``1(``0)) method: * Add the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute to the Web API controller, SignalR hub or gRPC service. -* Call when mapping endpoints in app startup: +* Call [DisableHttpMetrics](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics``1(``0)) when mapping endpoints in app startup: :::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5":::