[Instrumentation.AspNetCore, Instrumentation.HttpClient] Add Enrichment instructions

src/OpenTelemetry.Instrumentation.AspNetCore/README.md

@@ -311,6 +311,52 @@ the library you can do so as follows:
 });
 ```
 
+#### Enriching ASP.NET Core Request Metrics
+
+ASP.NET Core supports enriching request metrics using `IHttpMetricsTagsFeature`.
+This feature allows you to add custom tags to metrics like `http.server.request.duration`,
+which records the duration of HTTP requests on the server.
+
+Here's an example of enriching the `http.server.request.duration` metric:
+
+```csharp
+using Microsoft.AspNetCore.Http.Features;
+
+var builder = WebApplication.CreateBuilder();
+var app = builder.Build();
+
+app.Use(async (context, next) =>
+{
+    var tagsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
+    if (tagsFeature != null)
+    {
+        var source = context.Request.Query["utm_medium"].ToString() switch
+        {
+            "" => "none",
+            "social" => "social",
+            "email" => "email",
+            "organic" => "organic",
+            _ => "other"
+        };
+        tagsFeature.Tags.Add(new KeyValuePair<string, object?>("mkt_medium", source));
+    }
+
+    await next.Invoke();
+});
+
+app.MapGet("/", () => "Hello World!");
+
+app.Run();
+```
+
+In this example:
+
+* Middleware is added to enrich the ASP.NET Core request metric.
+* `IHttpMetricsTagsFeature` is obtained from the `HttpContext`.
+  This feature is only available if someone is listening to the metric.
+* A custom tag `mkt_medium` is added to the `http.server.request.duration` metric.
+  The value of this tag is determined based on the `utm_medium` query string parameter.
+
 #### RecordException
 
 This instrumentation automatically sets Activity Status to Error if an unhandled

src/OpenTelemetry.Instrumentation.Http/README.md

@@ -263,6 +263,66 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .Build();
 ```
 
+#### Enriching HttpClient Metrics
+
+Metrics enrichment in HttpClient allows adding custom tags to metrics, such as
+`http.client.request.duration`. This is especially useful for categorizing
+metrics in dashboards or alerts.
+
+Using `HttpMetricsEnrichmentContext` for Enrichment
+To enrich metrics, you can register callbacks with `HttpMetricsEnrichmentContext`.
+This requires setting up a custom `DelegatingHandler` that intercepts requests
+and adds custom tags before they are sent to the server.
+
+Here's how you can implement a custom `DelegatingHandler` to enrich metrics:
+
+```csharp
+using System.Net.Http.Metrics;
+
+using HttpClient client = new(new EnrichmentHandler() { InnerHandler = new HttpClientHandler() });
+
+await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=A");
+await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=B");
+
+sealed class EnrichmentHandler : DelegatingHandler
+{
+    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+    {
+        HttpMetricsEnrichmentContext.AddCallback(request, static context =>
+        {
+            if (context.Response is not null) // Response is null when an exception occurs.
+            {
+                // Use any information available on the request or the response to emit custom tags.
+                string? value = context.Response.Headers.GetValues("Enrichment-Value").FirstOrDefault();
+                if (value != null)
+                {
+                    context.AddCustomTag("enrichment_value", value);
+                }
+            }
+        });
+        return base.SendAsync(request, cancellationToken);
+    }
+}
+```
+
+If you're working with IHttpClientFactory, you can use AddHttpMessageHandler
+to register the EnrichmentHandler:
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
+using System.Net.Http.Metrics;
+
+ServiceCollection services = new();
+services.AddHttpClient(Options.DefaultName).AddHttpMessageHandler(() => new EnrichmentHandler());
+
+ServiceProvider serviceProvider = services.BuildServiceProvider();
+HttpClient client = serviceProvider.GetRequiredService<HttpClient>();
+
+await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=A");
+await client.GetStringAsync("https://httpbin.org/response-headers?Enrichment-Value=B");
+```
+
 #### .NET Framework
 
 ##### Filter HttpWebRequest API