[System.Diagnostics.DiagnosticSource] Implement metrics advice API

[CodeBlanch]

Fixes #63650

/cc @tarekgh @vishweshbankwar

[dotnet-issue-labeler]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[tarekgh]

CC @noahfalk

[tarekgh]

LGTM. Thanks @CodeBlanch for providing the implementation.

[tarekgh]

public sealed class InstrumentAdvice where T : struct

I think we need a parameter-less constructor here and inside it we need to call Instrument.ValidateTypeParameter<T>()

https://github.com/dotnet/runtime/blob/29f3110fc971c8cc48f18956d347e58c54bd0639/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Instrument.cs#L141C30-L141C38

[CodeBlanch]

Updated

[tarekgh]

do we need to add the constructor to the ref file too src\libraries\System.Diagnostics.DiagnosticSource\ref\System.Diagnostics.DiagnosticSourceActivity.cs?

[CodeBlanch]

It doesn't complain without it so maybe it is an implied thing? I went ahead and added it though.

[tarekgh]

Right. the compiler automatically generates the parameter-less constructor. So, it implicitly existed in the ref too. It is good to explicitly list it as we add some code there.

[tarekgh]

CC @noahfalk if need to take one final look before we merge.

[noahfalk]

I've still got concerns about the 'init' keyword :)

[noahfalk]

I've still got concerns about 'init' due to the difficulty invoking it from .NET Framework while using the officially supported 7.3 C# language version. Maybe in the future we'll decide to drop support for .NET Framework but we've not agreed to that so far.

I maintain the suggestion to define this property with as 'set', not 'init' and if we want to protect against mutations then we can make a read-only copy.

[tarekgh]

I humbly disagree. As I mentioned before, doing the allocation and copying is not good IMO especially we need to maintain that in the future too. We discussed that in the design review and didn't get any objection. Also, init is already used in the same library too.

[CodeBlanch]

The code as-is already takes a copy of the data 😄 The issue I think set creates is more that it can't be changed after the first publish of a metric. What OTel is going to do is on instrument published take the advice and construct the buckets after which point they are fixed. So having the set could just be misleading for users thinking they can set it whenever. init really conveys the meaning nicely for what this class is doing.

I guess we could have set throw based on some internal state tracking if the thing was published? But then what if you hand the same advice class to multiple instruments? 🤔

[stephentoub]

Why must T be a value type?

[stephentoub]

Oh, I see, it's not that it needs to be a value type, it's that it must be just one of byte, short, int, long, double, float, or decimal. Do we use such a constraint in other places for the same purpose?

[tarekgh]

We support only specific set of types

runtime/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Instrument.cs

Lines 141 to 149 in ced2117

	internal static void ValidateTypeParameter<T>()
	{
	Type type = typeof(T);
	if (type != typeof(byte) && type != typeof(short) && type != typeof(int) && type != typeof(long) &&
	type != typeof(double) && type != typeof(float) && type != typeof(decimal))
	{
	throw new InvalidOperationException(SR.Format(SR.UnsupportedType, type));
	}
	}

The supported T types in the advice class should exactly match the same supported types in Instrument<T>. Metrics work only with numerical types.

[tarekgh]

Do we use such a constraint in other places for the same purpose?

I am not aware of other places other than metrics. @tannergooding may know if there are other places that apply similar restrictions.

[stephentoub]

But we already use the same constraint for the same limited set of types elsewhere in metrics?

[noahfalk]

But we already use the same constraint for the same limited set of types elsewhere in metrics?

Correct. For Instrument<T> we do the same type validation here:
https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Instrument.common.cs#L40