[API Proposal]: HttpClient Metrics Enchainment and Filtering

[xsoheilalizadeh]

This is the proposal to add enrichment and filtering to HttpClient metrics in order to have the ability to enhance the metrics, currently, we have these features in Tracing but they are missing in Metrics.

Use cases

Enrichment

There are cases that it would be needed to enrich the current metrics, for example when users need to have HTTP route in the metrics,
services could have egress requests to an external HTTP server and having those metrics for each route would be essential.

The enrichment could happen on HttpResponseMessage because it includes also the request as a property.

Sdk.CreateMeterProviderBuilder()
   .AddHttpClientInstrumentation(options =>
    {
        options.Enrich = (HttpResponseMessage response, ref TagList tags) =>
        {
            response.RequestMessage.Options.TryGetValue(httpRouteOptionKey, out var httpRoute);
            tags.Add(SemanticConventions.AttributeHttpRoute, httpRoute);
        };
    })
    .Build();

Filtering

It could be possible that you would need to filter some requests, I don't see it as a necessary feature but a nice to have.

var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddHttpClientInstrumentation(options =>
    {
        options.FilterHttpRequestMessage = message =>
        {
            return message.RequestUri.AbsolutePath == "/";
        };
    })
    .AddInMemoryExporter(metrics)
    .Build();

API

HttpClientMetricsInstrumentationOptions

/// <summary>
/// Options for HttpClient metrics instrumentation.
/// </summary>
public class HttpClientMetricsInstrumentationOptions
{
    /// <summary>
    /// Delegate for enrichment of recorded metric with additional tags.
    /// </summary>
    /// <param name="response"><see cref="HttpResponseMessage"/>: the HttpResponseMessage object.</param>
    /// <param name="tags"><see cref="TagList"/>: List of current tags. You can add additional tags to this list. </param>
    public delegate void HttpClientMetricEnrichmentFunc(HttpResponseMessage response, ref TagList tags);

    /// <summary>
    /// Gets or sets a filter function that determines whether or not to
    /// collect telemetry on a per request basis.
    /// </summary>
    /// <remarks>
    /// <para><b>FilterHttpRequestMessage is only executed on .NET and .NET
    /// Core runtimes. <see cref="HttpClient"/> and <see
    /// cref="HttpWebRequest"/> on .NET and .NET Core are both implemented
    /// using <see cref="HttpRequestMessage"/>.</b></para>
    /// Notes:
    /// <list type="bullet">
    /// <item>The return value for the filter function is interpreted as:
    /// <list type="bullet">
    /// <item>If filter returns <see langword="true" />, the request is
    /// collected.</item>
    /// <item>If filter returns <see langword="false" /> or throws an
    /// exception the request is NOT collected.</item>
    /// </list></item>
    /// </list>
    /// </remarks>
    public Func<HttpRequestMessage, bool> FilterHttpRequestMessage { get; set; }

    /// <summary>
    /// Gets or sets an function to enrich a recorded metric with additional custom tags.
    /// </summary>
    public HttpClientMetricEnrichmentFunc Enrich { get; set; }
}

MeterProviderBuilderExtensions

/// <summary>
/// Extension methods to simplify registering of HttpClient instrumentation.
/// </summary>
public static class MeterProviderBuilderExtensions
{
    /// <summary>
    /// Enables HttpClient instrumentation.
    /// </summary>
    /// <param name="builder"><see cref="MeterProviderBuilder"/> being configured.</param>
    /// <param name="configureHttpClientMetricsInstrumentationOptions">Callback action for configuring <see cref="HttpClientMetricsInstrumentationOptions"/>.</param>
    /// <returns>The instance of <see cref="MeterProviderBuilder"/> to chain the calls.</returns>
    public static MeterProviderBuilder AddHttpClientInstrumentation(this MeterProviderBuilder builder, Action<HttpClientMetricsInstrumentationOptions> configureHttpClientMetrics

    /// <summary>
    /// Enables HttpClient instrumentation.
    /// </summary>
    /// <param name="builder"><see cref="MeterProviderBuilder"/> being configured.</param>
    /// <param name="name">Name which is used when retrieving options.</param>
    /// <param name="configureHttpClientMetricsInstrumentationOptions">Callback action for configuring <see cref="HttpClientMetricsInstrumentationOptions"/>.</param>
    /// <returns>The instance of <see cref="MeterProviderBuilder"/> to chain the calls.</returns>
    public static MeterProviderBuilder AddHttpClientInstrumentation(this MeterProviderBuilder builder, string name, Action<HttpClientMetricsInstrumentationOptions> configureHttp

}

PR: open-telemetry/opentelemetry-dotnet#4374

[vchirikov]

Up
ping: @reyang, @CodeBlanch

[cijothomas]

This needs to be put on hold, as the plan is to remove the Metric enrich/filter from Asp.Net Core as well in the first stable release of the instrumentations. There is a desire to leverage the built-in enrich capability offered by .NET itself, but that'd only work for .NET 8.

There is no specification for general purpose enriching (and filtering also I think) of Metrics yet, so I understand options exposed by InstrumentationLibraries are the only way to enrich metrics :(.