[API Proposal]: Introduce source generation based support for .NET metrics API

[dpk83]

Background and motivation

Our team creates Telemetry framework for internal teams and we have created metrics solution. It was created before .NET Meter API came into existence so we created our own IMeter API surface. In our internal project, everything is designed to be highly efficient (consumes less CPU and reducing allocation as much as possible) while providing an easy to use developer friendly API surface. This helps reduce the developer burden, reduces chances of mistakes and at the same time helps gain the performance benefits.

With that in mind we utilized the compile time source generation of roslyn and introduced attributes for various instruments. Here is an example of how the attributes look like in our internal project using our IMeter surface

[Counter<int>("clientRing", "clientType", "region", Name = "TestInstrument")]
public static partial TestInstrument CreateTestInstrument(this IMeter meter); 

Developer writes this signature using Counter attribute and we would generate the source code for this method underneath which generates a highly efficient source using the most efficient mechanism available to achieve the required operations.

Once the above signature is defined, developers can then use it to create the typed counter like this:

// Create the instrument
var testInstrument = meter.CreateTestInstrument();

// The generated source will method generated specifically for this instrument i.e. it will have a method which will have named 
// parameters with names defined in the Counter attribute definition. This makes it easier for a developer to know what dimensions are expected to be passed and can provide it appropriately
// Use it to record metrics wherever needed. 
testInstrument.Add(1, clientRing, clientType, region);

Similarly, these attributes also support strong typed objects e.g.

[Counter<long>(typeof(MyObject), Name="MyStrongTypedInstrument")
public static partial MyCounterInstrument CreateMyCounterInstrument(this IMeter meter);

You can then use it as

var counter = meter.MyCounterInstrument();

counter.Add(10, myObject);

The underlying code generated at the compile time would expand this object's properties into individual dimension, thus simplifying the work for developers.

We are extending this source generation to support .NET Meter API and would like to have this become part of .NET so it can be useful for the broader community.

With the code generation, we have possibilities to provide the highest performance. E.g. we could automatically use the TagList if the total tags are less than or equal to 8 and switch to expanded tag list when there are more. We can skip all the processing upfront if there are no listeners or the instrument is not enabled etc.

We have found this extremely useful and so did our customers. We can build additional functionality on top where we could add a source generator to generate reports of the metrics emitted by a service and all it's dependent libraries (so developers know upfront what metrics can be emitted by libraries that they depend on, which ones are enabled vs which ones are not etc.)

API Proposal

[AttributeUsage(AttributeTargets.Method)]
[Conditional("CODE_GENERATION_ATTRIBUTES")]
public sealed class CounterAttribute<T> : Attribute
{
    public CounterAttribute(params string[] dimensions)
    {
        Dimensions = dimensions;
    }

    public CounterAttribute(Type type)
    {
        Type = type;
    }

    public string? Name { get; set; }
    public string[]? Dimensions { get; }
    public Type? Type { get; }
}

Similarly for HistogramAttribute

API Usage

// Create the signature at some place
[Counter<int>("clientRing", "clientType", "region", Name = "TestInstrument")]
public static partial TestInstrument CreateTestInstrument(this IMeter meter); 


// Create the instrument, where needed 
var testInstrument = meter.CreateTestInstrument();

// Use it to record metrics when needed. 
testInstrument.Add(1, clientRing, clientType, region);

Similarly, these attributes also support strong typed objects e.g.

[Counter<long>(typeof(MyObject), Name="MyStrongTypedInstrument")
public static partial MyCounterInstrument CreateMyCounterInstrument(this IMeter meter);

// Create the instrument using the declared method 
var counter = meter.MyCounterInstrument();

// Record the metric and pass the object when needed
counter.Add(10, myObject);

Alternative Designs

No response

Risks

No response

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[dpk83]

@noahfalk @tarekgh

[noahfalk]

@dpk83 - high level I like the idea of source generation for metrics similar to what exists for logging. I'm curious if you've considered or gotten feedback on designs where the source compiled APIs directly call the instrument APIs vs. returning the instrument to the user and requiring them to make the call? Here is what I imagine usage of the two different styles looks like:

Static factories:

static class MyHomeControllerMetrics
{
    [Counter<long>(typeof(MyObject), Name="MyStrongTypedInstrument")
    public static partial MyCounterInstrument CreateMyCounterInstrument(this IMeter meter);
    [Counter<int>("clientRing", "clientType", "region", Name = "TestInstrument")]
    public static partial TestInstrument CreateTestInstrument(this IMeter meter);
} 

class MyHomeController
{
    MyCounterInstrument _counter;
    TestInstrument _test;
    // ... additional instruments listed here

    public MyHomeController()
    {
        IMeter meter = ...
        _counter = MyHomeControllerMetrics.CreateMyCounterInstrument(meter);
        _test = MyHomeControllerMetrics.CreateTestInstrument(meter);
        // ... additional instruments inited here
    }

    public void DoSomeWork(MyObject obj)
    {
        _counter.Add(10, obj);
    }
}

Direct counter manipulation:

partial class MyHomeControllerMetrics
{
    [Counter(Name="MyStrongTypedInstrument")]
    public partial void AddCounter(long increment, MyObject obj);
    [Counter(Name="TestInstrument")]
    public partial void AddTest(int increment, string clientRing, string clientType, string region);
} 

class MyHomeController
{
    MyHomeControllerMetrics _metrics;

    public MyHomeController()
    {
        IMeter meter = ...
        _metrics = new MyHomeControllerMetrics(meter);
    }

    public void DoSomeWork(MyObject obj)
    {
        _metrics.AddCounter(10, obj);
    }
}

I find the second one a little more appealing for a few reasons:

• simplifies the attributes by inferring most of the information from the partial method signature
• doesn't require generating as much code (1 method/instrument vs. 2 methods and 1 type/counter)
• doesn't require the user to cache each instrument locally saves 2 LoC per instrument after the first

If there are situations that require creating or accessing the instrument I'm not opposed to it, but it didn't seem as streamlined for common usage.

Although out-of-scope here, I'm also imagining further down a roadmap we might use source generation to help streamline emitting multiple types of telemetry without user code needing to cache different factory objects in fields for producing each kind of data they want to send:

// this type could be wrapping any or all of {ILogger, Meter, ActivitySource }
partial class MyHomeControllerInstrumentation
{
    [Counter(Name="MyStrongTypedInstrument")]
    public partial void AddCounter(long increment, MyObject obj);
    [LoggerMessage(Message="Doing the work {clientName}")]
    public partial void LogDoWork(string clientName);
} 

class MyHomeController
{
    MyHomeControllerInstrumentation _instr;

    public MyHomeController(MyHomeControllerInstrumentation instrumentation)
    {
        _instr = instrumentation;
    }

    public void DoSomeWork(MyObject obj)
    {
        _instr.LogDoWork(obj.ClientName);
        _instr.AddCounter(10, obj);
        ...
    }
}

[dpk83]

@noahfalk When we were designing the solution we did consider something down that path, however, the creation of the instrument object becomes really challenging there.

As you didn't add where the creation of the actual counter is taking place based on the overall usage pattern I assume one of the following options.

1. Developers write the constructor for MyHomeControllerInstrumentation which takes in the instrument objects to be used for various instruments. So, if the class has Add methods for 10 different instruments, it will require the caller to pass 10 instrument objects when creating the MyHomeControllerInstrumentation object and then there is this challenge of how do you figure which instrument belongs to which of the Add* method.
2. MyHomeControllerInstrumentation constructor is also source generated. This will require a new attribute to be defined to be used on the class so a constructor can be generated. The problem of how do you map the Add* method with appropriate counter is still a problem here. Specially because now you have to make two different attributes (class attribute and the method attribute) work with each other during source generation.

[noahfalk]

I'm thinking of option 2 in your list above. I'm certainly inexperienced at implementing source generators so it is entirely possible I am overlooking obstacles, but so far in my experimentation the obstacles weren't apparent yet.

This will require a new attribute to be defined to be used on the class so a constructor can be generated.

I'm not sure why this would be the case? Hasn't the class already been identified by the presence of well-known attributes on its methods? I wrote a crude generator that found all methods decorated with the CounterAttribute, determined what class they were contained in and then generated a constructor for that class without the need for a 2nd attribute.

The problem of how do you map the Add* method with appropriate counter is still a problem here

I understand the mapping problem when you talked about option 1, but it was unclear how that problem applied in option 2. This is the user and generated code I was imagining:

// user code
partial class MyHomeControllerMetrics
{
    [Counter(Name="MyStrongTypedInstrument")]
    public partial void AddCounter(long increment, MyObject obj);
    [Counter(Name="TestInstrument")]
    public partial void AddTest(int increment, string clientRing, string clientType, string region);
} 

// generated code
partial class MyHomeControllerMetrics
{
    Counter<long> _c1;
    Counter<int> _c2;

    public MyHomeControllerMetrics(Meter m)
    {
        _c1 = m.CreateCounter<long>("MyStrongTypedInstrument");
        _c2 = m.CreateCounter<int>("TestInstrument");
    }

    public partial void AddCounter(long increment, MyObject obj)
    {
        //hand-waving the conversion of MyObject to tags because it is presumably the same
        //as whatever R9 is doing now in the strong-typed instrument code
        var tags = ...
        _c1.Add(increment, tags);
    }

    public partial void AddTest(int increment, string clientRing, string clientType, string region)
    {
        _c2.Add(increment, 
            KeyValuePair.Create("clientRing", clientRing),
            KeyValuePair.Create("clientType", clientType),
            KeyValuePair.Create("region", region));    
    }
} 

Looking at the Logging generator for comparison the generator appears to understand both the class and list of attributed methods in that class when generating the source. I was assuming the algorithm to generate the source here is roughly:

• scan the ordered list of attributed methods to create an ordered list of needed instruments
• foreach instrument in the list, write field to cache it
• write the constructor inside of which, foreach instrument in the list write the initializer
• foreach attributed method implement its body. The i'th method impl should invoke the i'th instrument because both lists are in the same order.

Maybe I am overlooking major issues and I'm hoping you can help me understand what they are. Thanks!

[dpk83]

I'm not sure why this would be the case? Hasn't the class already been identified by the presence of well-known attributes on its methods?

Yes, the presence of an attribute on the partial method in the class will let you modify the class but things get complicated as we are talking about the class containing multiple attributes all trying to modifying the class. i.e. A class can have a mix of multiple counters and histograms. While each attribute only modifies it's method now it's also modifying the containing class constructor.

Multiple attributes can't coordinate during source generation so having multiple attributes trying to modifying their containing class constructor doesn't look right.

e.g. In your example above each attribute will now need to add a call to create the counter/histogram in the class constructor, so each attribute will then try to create the constructor. As constructors can't be partial you will now add additional logic to check for the presence of constructor and then create one or use an existing one, or you entirely decide that you want to just create the instrument objects directly at the time of declaration.

Another issue with this approach is the fact that all declared instruments are allocated regardless of whether there is any code path using the object. It's a minor point but I am just stating it to surface the limitations.

@geeknoid Let us know your thoughts on the proposal once you are back next week.

[noahfalk]

In your example above each attribute will now need to add a call to create the counter/histogram in the class constructor, so each attribute will then try to create the constructor

Sorry I'm still having trouble understanding where this restriction is coming from? When I look at the existing logger source generator the code path appears to generate the entire class in one operation and the code is aware of all attributed methods in the class simultaneously. Am I misunderstanding something about how the logger code works or is there a reason the counter generator can't work the same way that the logger generator does? Thanks for trying to explain and sorry if I am just missing something.