[API Proposal]: Introduce DI friendly IMeter<T> for modern services

[dpk83]

This is edited by @tarekgh

Runtime Metrics APIs Proposal

At present, the metrics APIs that are exposed do not integrate smoothly with DI. This is because the current support relies on creating Meter objects as static, which cannot be utilized within DI containers. As a solution, this proposal recommends developing new APIs that will enable metrics to work seamlessly with DI.

Meter Factory

The IMeterFactory interface is being introduced, which can be registered with the DI container and utilized to create or obtain Meter objects.

IMeterFactory

namespace System.Diagnostics.Metrics
{
    public interface IMeterFactory : IDisposable
    {
        Meter Create(
                string name,
                string? version = null,
                IEnumerable<KeyValuePair<string, object?>>? tags = null);
    }
}

A default implementation will be offered, which should be adequate for most use cases. Nonetheless, users may choose to provide their own implementation for alternative purposes, such as testing.

Meter factories will be accountable for the following responsibilities:

• Creating a new meter.
• Attaching the factory instance to the Meter constructor for all created Meter objects. Additional details regarding this will be addressed later in the metrics APIs' additions.
• Storing created meters in a cache and returning a cached instance if a meter with the same parameters (name, version, and tags) is requested.
• Disposing of all cached Meter objects upon factory disposal.

DI IMeterFactory Registration

The default IMeterFactory registration can be done by the API:

namespace Microsoft.Extensions.Metrics
{
    public static class MetricsServiceExtensions
    {
        public static IServiceCollection AddMetrics(this IServiceCollection services);        
    }
}

Core Metrics APIs Addition

The proposed modifications aim to facilitate the following:

• Inclusion of default tags to the Meter
• Addition of default tags to the instruments
• Incorporation of scope into the Meter involves assigning an IMeterFactory object to the Meter, which serves as a marker for all Meters associated with a particular factory.
• The Meter will now cache non-Observable instruments internally to prevent re-creation when attempting to recreate the same instrument with identical parameters such as name, unit, tags, and generic type.

namespace System.Diagnostics.Metrics
{
    public abstract class Instrument
    {
        protected Instrument(
                    Meter meter,
                    string name,
                    string? unit,
                    string? description,
                    IEnumerable<KeyValuePair<string, object?>>? tags);

         public IEnumerable<KeyValuePair<string, object?>>? Tags { get; }
    }

    public abstract class Instrument<T> : Instrument where T : struct
    {
        protected Instrument(
                    Meter meter,
                    string name,
                    string? unit,
                    string? description, IEnumerable<KeyValuePair<string, object?>>? tags);
    }

    public abstract class ObservableInstrument<T> : Instrument where T : struct
    {
        protected ObservableInstrument(
                    Meter meter,
                    string name,
                    string? unit,
                    string? description,
                    IEnumerable<KeyValuePair<string, object?>> tags);
    }

    public class Meter : IDisposable
    {
        public Meter(
                string name,
                string? version,
                IEnumerable<KeyValuePair<string, object?>>? tags,
                IMeterFactory? factory = null);

        public IEnumerable<KeyValuePair<string, object?>>? Tags { get ; }}

        public IMeterFactory? Factory { get; }

        public Counter<T> CreateCounter<T>(
                            string name,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public UpDownCounter<T> CreateUpDownCounter<T>(
                            string name,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public Histogram<T> CreateHistogram<T>(
                            string name,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableCounter<T> CreateObservableCounter<T>(
                            string name,
                            Func<T> observeValue,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableCounter<T> CreateObservableCounter<T>(
                            string name,
                            Func<Measurement<T>> observeValue,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableCounter<T> CreateObservableCounter<T>(
                            string name,
                            Func<IEnumerable<Measurement<T>>> observeValues,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableUpDownCounter<T> CreateObservableUpDownCounter<T>(
                            string name,
                            Func<T> observeValue,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableUpDownCounter<T> CreateObservableUpDownCounter<T>(
                            string name,
                            Func<Measurement<T>> observeValue,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableUpDownCounter<T> CreateObservableUpDownCounter<T>(
                            string name,
                            Func<IEnumerable<Measurement<T>>> observeValues,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableGauge<T> CreateObservableGauge<T>(
                            string name,
                            Func<T> observeValue,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableGauge<T> CreateObservableGauge<T>(
                            string name,
                            Func<Measurement<T>> observeValue,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;

        public ObservableGauge<T> CreateObservableGauge<T>(
                            string name,
                            Func<IEnumerable<Measurement<T>>> observeValues,
                            string? unit,
                            string? description,
                            IEnumerable<KeyValuePair<string, object?>> tags) where T : struct;
}

Testing Helper

The InstrumentRecorder class has been introduced to facilitate metric testing with DI. With this class, it is straightforward to monitor a particular instrument and its meter readings, and then generate reports on the values published by the instrument.

namespace Microsoft.Extensions.Metrics
{
    public sealed class InstrumentRecorder<T> : IDisposable where T : struct
    {
        public InstrumentRecorder(Instrument instrument);
        public InstrumentRecorder(
                        IMeterFactory? meterFactory,
                        string meterName,
                        string instrumentName);
        public InstrumentRecorder(
                        Meter meter,
                        string instrumentName);
    
        public Instrument Instrument { get; }

        public IEnumerable<Measurement<T>> GetMeasurements();
        public void Dispose();
    }
}

Code Example

    //
    // Register Metrics
    //

    services.AddMetrics();

    //
    // Access the MeterFactory
    //

    IMeterFactory meterFactory = serviceProvider.GetRequiredService<IMeterFactory>();

    //
    // Create Meter
    //

    Meter meter = meterFactory.Create(
                            "MeterName",
                            "version",
                            new TagList()
                            {
                                { "Key1", "Value1" },
                                { "Key2", "Value2" }
                            });

    //
    // Create Instrument
    //

    Counter<int> counter = meter.CreateCounter<int>(
                            "CounterName",
                            "cm",
                            "Test counter 1",
                            new TagList() { { "K1", "V1" } });

    //
    // Test instrument published values
    //

    var recorder = new InstrumentRecorder<int>(meterFactory, "MeterName", "CounterName");
    // can do the following too:
    // var recorder = new InstrumentRecorder<int>(counter);
    counter. Add(1);
    Assert.Equal(1, recorder.GetMeasurements().ElementAt(0));

end of @tarekgh edit and start of old description

Background and motivation

.NET exposes Meter API to instrument code for collecting metrics. Currently the Meter is a class which doesn't work well with DI (Dependency Injection) based model. In order to create a meter object a developer currently need to create an object of the Meter class and pass the meter name, something like this

var meter = new Meter("myMeter");

While this works find on a smaller scale, for large scale complex services this starts becoming difficult to manage and having a DI based API surface could make things much simpler. Apart from the fact that DI would improve the testability of the code, it will also allow for better management of creation of Meter object in a consistent fashion. With DI based approach a meter can be consistently created with the type name of the class where the meter is injected, which opens up a lot of possibilities for further extensions that could simplify the programming model.

We have a metrics solution that our teams uses. When we implemented the solution .NET metrics API was not in existence so we had created our own API surface for metrics. We introduced DI friendly IMeter and IMeter which works similar to ILogger and ILogger. Over the time we found the DI friendly surface extremely useful and extensible, it turned out to be super easy for services and has allowed us to have a consistent approach of creating meter object everywhere. Service owners and library owners don't need to worry about cooking up names for the meter object and the meter object automatically gets created with consistent naming. This allows us to add various capabilities by providing filtering based on the meter names via config. Few examples of the capabilities

• Services can configure the state of individual meters via config (i.e. enable/disable a meter by configuring the metering state in their appsettings.json using the type name of namespace, similar to how one can configure logging levels with .NET ILogger)
• Services can configure different destinations for metrics generated by different meter objects. This works even when using third party libraries seamlessly as long as the libraries are using DI to inject meter. etc.

Modern .NET services use DI heavily due to it's benefits and the trend will only increase going forward. Based on our experience with IMeter API and the feedback of simplicity from our customers, we think it would be highly useful for the rest of the community too.

API Proposal

namespace System.Diagnostics.Metrics;

public interface IMeter
{
}

public interface IMeter<out TCategoryName> : IMeter
{
}

OR

namespace System.Diagnostics.Metrics;

public class Meter<out TCategoryName>
{
}

API Usage

public class MyClass
{
    // Inject Meter<T> object using DI
    public MyClass(IMeter<MyClass> meter)
    {
        var counter = meter.CreateCounter<long>("counter1");
    }
}

public class AnotherClass
{
    // Inject a meter with the full name of the provided T gets injected using DI.
    public AnotherClass(IMeter<AnotherClass> meter)
    {
        var counter = meter.CreateCounter<long>("counter2");
    }
}

Alternative Designs

The alternative is to write a custom DI wrapper for Meter and introduce Meter in a wrapper which then defeats the purpose of exposing the Meter API exposed from .NET directly.

Risks

It's a new addition to existing APIs so shouldn't cause breaking changes.

Tagging subscribers to this area: @dotnet/area-extensions-dependencyinjection
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

.NET exposes Meter API to instrument code for collecting metrics. Currently the Meter is a class which doesn't work well with DI (Dependency Injection) based model. In order to create a meter object a developer currently need to create an object of the Meter class and pass the meter name, something like this

var meter = new Meter("myMeter");

While this works find on a smaller scale, for large scale complex services this starts becoming difficult to manage and having a DI based API surface could make things much simpler. Apart from the fact that DI would improve the testability of the code, it will also allow for better management of creation of Meter object in a consistent fashion. With DI based approach a meter can be consistently created with the type name of the class where the meter is injected, which opens up a lot of possibilities for further extensions that could simplify the programming model.

In R9, we have a metrics solution. When we implemented the solution .NET metrics API was not in existence so we had created our own API surface for metrics. We introduced DI friendly IMeter and IMeter which works similar to ILogger and ILogger. Over the time we found the DI friendly surface extremely useful and extensible, it turned out to be super easy for services and has allowed us to have a consistent approach of creating meter object everywhere. Service owners and library owners don't need to worry about cooking up names for the meter object and the meter object automatically gets created with consistent naming. This allows us to add various capabilities by providing filtering based on the meter names via config. Few examples of the capabilities

• Services can configure the state of individual meters via config (i.e. enable/disable a meter by configuring the metering state in their appsettings.json using the type name of namespace, similar to how one can configure logging levels with .NET ILogger)
• Services can configure different destinations for metrics generated by different meter objects. This works even when using third party libraries seamlessly as long as the libraries are using DI to inject meter. etc.

Modern .NET services use DI heavily due to it's benefits and the trend will only increase going forward. Based on our experience with IMeter API and the feedback of simplicity from our customers, we think it would be highly useful for the rest of the community too.

Here are examples to implementations and usage in R9

• IMeterT
• Example of registering IMeter
• Example of injection of IMeter and usage
• Example of the extensibility it open up to control various things via config here . This is similar to .NET's logging config

API Proposal

namespace System.Diagnostics.Metrics;

public interface IMeter
{
}

public interface IMeter<out TCategoryName> : IMeter
{
}

OR

namespace System.Diagnostics.Metrics;

public class Meter<out TCategoryName>
{
}

API Usage

public class MyClass
{
    // Inject Meter<T> object using DI
    public MyClass(IMeter<MyClass> meter)
    {
        var counter = meter.CreateCounter<long>("counter1");
    }
}

public class AnotherClass
{
    // Inject a meter with the full name of the provided T gets injected using DI.
    public AnotherClass(IMeter<AnotherClass> meter)
    {
        var counter = meter.CreateCounter<long>("counter2");
    }
}

Alternative Designs

The alternative is to write a custom DI wrapper for Meter and introduce Meter in a wrapper which then defeats the purpose of exposing the Meter API exposed from .NET directly.

Risks

It's a new addition to existing APIs so shouldn't cause breaking changes.

Author:	dpk83
Assignees:	-
Labels:	api-suggestion, area-Extensions-DependencyInjection
Milestone:	-

[julealgon]

With DI based approach a meter can be consistently created with the type name of the class where the meter is injected, which opens up a lot of possibilities for further extensions that could simplify the programming model.

This part turned me off.

The same pattern is used with ILogger and I see it more as a workaround to lack of injection target inspection in the container itself. If you look at the ILogger<T> type, it "does nothing", it's basically a marker interface to differentiate registrations in the container: again, a workaround.

Instead of expanding on that (IMHO terrible) practice, I'd rather see something similar to how HttpClient is handled today. It suffers from similar issues, but they were solved without "hurting" the type itself: HttpClient remains non-generic, but there are injection helpers that facilitate associating a given HttpClient with the service that is going to consume it.

Now... don't get me wrong: I still think even the AddHttpClient methods are also hacky workarounds to the underlying root problem here which is an inability of inspecting the target injection type during dependency injection. It would be nice to have that as it would allow you to have all these patterns without dedicated container extensions, but that's probably a separate discussion altogether.

Lastly, about this:

public class MyClass
{
    // Inject Meter<T> object using DI
    public MyClass(IMeter<MyClass> meter)
    {
        var counter = meter.CreateCounter<long>("counter1");
    }
}

I'm not very fond of having instrument creation happening inside my classes either. In all scenarios where I've used custom metrics, I've always made sure to configure and set them all up in the container, and inject the counters. Consumers shouldn't have to know how to create the counters (and gauges, and other instruments); they should only use them.

On that front, what I've also done is extract a ICounter<T> interface for my own purposes, and test around that.

If this proposal is seriously taken into consideration, I'd also recommend potentially extracting common interfaces for the instruments themselves as they are, IMHO, the core of the untestability in regards to metrics classes.

[tarekgh]

Thanks @julealgon for the feedback, it is helpful. We'll look at this at some point next year. I am wondering if you have any specific proposal that you think addresses the request in the proper way.

[julealgon]

We'll look at this at some point next year.

That's good to hear. This API is indeed extremely unfriendly to modern patterns using Extensions.Hosting.

I am wondering if you have any specific proposal that you think addresses the request in the proper way.

Aside from providing an interface to each instrument type, I think this entire namespace needs a companion "Extensions.Hosting" extension with methods to add metrics and instruments to the container. In a sense, this approach wouldn't be too far off from what Azure and OTEL provide with their Microsoft.Extensions.Azure and OpenTelemetry.Extensions.Hosting respectively.

As for the API, I could see very similar needs to what the various AddHttpClient extensions provide:

• Possibility of "tying" a specific instrument to a service
• Possibility of tying a named instrument to a service
• Possibility of resolving a named instrument from inside a service (some sort of I{Instrument}Factory analogous to IHttpClientFactory)

As well as some stuff that would have to be thought from scratch I think:

• Possibility of tying multiple instruments to the same service (I actually have this exact requirement in one of our APIs)
• Fluent API to create and add Meter instances to the container along with their instruments

As part of this work, I'd also like to see better integration with OTEL itself, so that one doesn't need to pass strings around to indicate the meters to track etc. Maybe add some method in the OTEL extensions that just "honors all meters defined in the container automatically" (that's what would make the most sense in my use cases).

Lastly, I just want to emphasize again how hard and convoluted it is to create some of these container-related extensions, and that is mostly due to restrictions on what the MS container keeps track of. It would be really nice if MS reconsidered the feature-set it provides out of the native container, so that things such as "named/keyed registrations" and "target-based injection decisions" were possible natively (especially the latter).

For reference, I'll drop one of our more advanced usages here (should help people understand where I'm coming from). Things have been renamed/simplified from the actual code:

    public static MeterProviderBuilder AddCustomStuffInstrumentation(
        this MeterProviderBuilder meterProviderBuilder)
    {
        ArgumentNullException.ThrowIfNull(meterProviderBuilder);

        const string meterName = "Company.Product";

        return meterProviderBuilder
            .ConfigureServices(
                services => services
                    .AddSingleton<CustomStuffAvailabilityReportingContext>()
                    .AddSingleton<ICustomStuffAvailabilityReportingContext>(p => p.GetRequiredService<CustomStuffAvailabilityReportingContext>())
                    .AddHostedService<CustomStuffAvailabilityReportingService>()
                    .AddHostedService<InstanceInitializerService<ObservableGauge<int>>>()
                    .AddSingleton(_ => new Meter(meterName))
                    .AddSingleton(
                        p =>
                        {
                            var reportingContext = p.GetRequiredService<ICustomStuffAvailabilityReportingContext>();

                            return p
                                .GetRequiredService<Meter>()
                                .CreateObservableGauge(
                                    "available-stuff",
                                    observeValue: () => reportingContext.LastStuffCountReading,
                                    unit: "Stuff",
                                    description: "Tracks how much stuff is available.");
                        })

                    .AddNamedSingleton(
                        p => p
                            .GetRequiredService<Meter>()
                            .CreateUpDownCounterOfInt(
                                "pending-stuff",
                                unit: "Stuff",
                                description: "Tracks how much stuff is pending."),
                        name: CounterRegistrationNames.Pending)

                    .AddNamedSingleton(
                        p => p
                            .GetRequiredService<Meter>()
                            .CreateUpDownCounterOfInt(
                                "available-things",
                                unit: "Thing",
                                description: "Tracks how many things are available."),
                        name: CounterRegistrationNames.Available)

                    .AddNamedSingleton(
                        p => p
                            .GetRequiredService<Meter>()
                            .CreateCounter<int>(
                                "confirmed-things",
                                unit: "CodeRanges",
                                description: "Tracks how many things have been confirmed.")
                            .AdaptToICounter(),
                        name: CounterRegistrationNames.Confirmed)

                    .AddTransient<IStuffTracker>(p => new StuffTracker(
                        pendingStuffCounter: p.GetRequiredNamedService<ICounter<int>>(CounterRegistrationNames.Pending),
                        availableThingsCounter: p.GetRequiredNamedService<ICounter<int>>(CounterRegistrationNames.Available),
                        confirmedThingsCounter: p.GetRequiredNamedService<ICounter<int>>(CounterRegistrationNames.Confirmed)))

                    .Decorate<IRequestHandler<IngestStuffRequest, IngestStuffResponse>, IngestStuffMetricsHandler>()
                    .Decorate<IRequestHandler<CancelThingRequest, CancelThingResponse>, ThingCancellationMetricsHandler>()
                    .Decorate<IRequestHandler<ConfirmThingRequest, ConfirmThingResponse>, ThingConfirmationMetricsHandler>()
                    .Decorate<IRequestHandler<ReserveStuffRequest, ReserveStuffResponse>, StuffReservationMetricsHandler>())
            .AddMeter(meterName);
    }

Notes about this implementation:

• CustomStuffAvailabilityReportingContext is used as an "ambient" storage to communicate a hosted service with an ObservableGauge.
• The InstanceInitializerService is there to "force" initialization of the gauge (I wish I didn't have to do this, but the gauge only starts when it is first resolved from the container of course...)
• The AddNamedSingleton is our custom extension to register named instances in the container (using Lazy<T, TMetadata> internally). Obviously wish this had a native counterpart but there is none
• The CreateUpDownCounterOfInt is just a .NET6 workaround for UpDownCounter support (creates a custom ICounter implementation that uses 2 counters internally: one to represent increments, and another to represent decrements). This is going away now that we've migrated to .NET7 and can use the actual UpDownCounter instrument
• AdaptToICounter is a custom extension that returns an adapter that implements our custom ICounter interface (abstraction to enable proper testing)
• StuffTracker relies on 3 counters and updates them depending on some methods that are called on it. This is where being able to inject multiple instruments in the same target service would be useful
• Decorate is just using Scrutor to add a few decorators to some of our existing command handlers (MediatR), so that we can update the 3 counters depending on what actions are performed

Our initial implementation only contained the 3 counters. The ObservableGauge + Hosted Service were added later as another workaround: they will be removed soon.

Of note as well, is how unfriendly to DI the ObservableGauge API is... the whole thing about passing a container-controlled state object from the gauge to the service was really hard to get right, especially with having to force initialization of the gauge separately.