[Feature Request]: Add synchronous gauge instrument #92625
Description
Edited by @tarekgh
OpenTelemetry has introduced the Gauge instrument, designed to record non-additive values when changes occur. For example, it can measure the background noise level, where summing the values from multiple rooms would be nonsensical.
Proposal
namespace System.Diagnostics.Metrics;
public class Meter : IDisposable
{
public Gauge<T> CreateGauge<T>(string name) where T : struct {}
public Gauge<T> CreateGauge<T>(string name, string? unit = null, string? description = null, IEnumerable<KeyValuePair<string, object?>>? tags = null) where T : struct {}
}
public sealed class Gauge<T> : Instrument<T> where T : struct
{
public void Record(T value) {}
public void Record(T value, KeyValuePair<string, object?> tag) { }
public void Record(T value, KeyValuePair<string, object?> tag1, KeyValuePair<string, object?> tag2) { }
public void Record(T value, KeyValuePair<string, object?> tag1, KeyValuePair<string, object?> tag2, KeyValuePair<string, object?> tag3) { }
public void Record(T value, params ReadOnlySpan<KeyValuePair<string, object?>> tags) { }
public void Record(T value, params KeyValuePair<string, object?>[] tags) { }
public void Record(T value, in TagList tagList) { }
//
// Instrument<T> properties
//
public Meter Meter { get; }
public string Name { get; }
public string? Description { get; }
public string? Unit { get; }
public IEnumerable<KeyValuePair<string, object?>>? Tags { get; }
public bool Enabled { get; }
public virtual bool IsObservable { get; }
}Usage Example
Meter meter = new Meter("MeasurmentLibrary.Sound");
Gauge<int> gauge= meter.CreateGauge<int>(name: "NoiseLevel", unit: "dB", description: "Background Noise Level"); // dB is Decibel, the sound intensity level unit
gauge.Record(10, new TagList { "Room1", "dB"});Original Description
OpenTelemetry has now defined a synchronous gauge. If the OTel maintainers agree the spec is sufficiently stable we should implement it in System.Diagnostics.Metrics. Feel free to replace this stub with a more complete description of the new API surface.
In addition to adding the API, we also need to add support for it to the MetricsEventSource.
OTel issue: open-telemetry/opentelemetry-dotnet#4805
cc @tarekgh