Add metrics opt-out section to metrics doc

Author: JamesNK

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>(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 <xref:Microsoft.AspNetCore.Http.Features.IHttpMetricsTagsFeature.MetricsDisabled?displayProperty=nameWithType> 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
 

aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs

@@ -0,0 +1,36 @@
+#define SECOND // FIRST SECOND
+#if NEVER
+#elif FIRST
+// <snippet_1>
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHealthChecks();
+
+var app = builder.Build();
+app.MapHealthChecks("/healthz").DisableHttpMetrics();
+app.Run();
+// </snippet_1>
+#elif SECOND
+using Microsoft.AspNetCore.Http.Features;
+
+var builder = WebApplication.CreateBuilder(args);
+var app = builder.Build();
+
+app.MapGet("/", () => "Hello World!");
+
+// <snippet_2>
+// Middleware that conditionally opts-out HTTP requests.
+app.Use(async (context, next) =>
+{
+    var metricsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
+    if (metricsFeature != null &&
+        context.Request.Headers.ContainsKey("x-disable-metrics"))
+    {
+        metricsFeature.MetricsDisabled = true;
+    }
+
+    await next(context);
+});
+// </snippet_2>
+
+app.Run();
+#endif