Add Gauge Metrics Instrument (#103543)

* Add Gauge Metrics Instrument * Addressing the feedback * Apply suggestions from code review Co-authored-by: Cijo Thomas <[email protected]> --------- Co-authored-by: Cijo Thomas <[email protected]>
dotnet · Jun 19, 2024 · c529580 · c529580
1 parent eb14da9
commit c529580
Show file tree

Hide file tree

Showing 7 changed files with 424 additions and 59 deletions.
diff --git a/...es/System.Diagnostics.DiagnosticSource/ref/System.Diagnostics.DiagnosticSourceActivity.cs b/...es/System.Diagnostics.DiagnosticSource/ref/System.Diagnostics.DiagnosticSourceActivity.cs
@@ -350,6 +350,18 @@ public sealed class Counter<T> : Instrument<T> where T : struct
         internal Counter(Meter meter, string name, string? unit, string? description) :
                         base(meter, name, unit, description) { throw null; }
     }
+    public sealed class Gauge<T> : Instrument<T> where T : struct
+    {
+        public void Record(T value) { throw null; }
+        public void Record(T value, System.Collections.Generic.KeyValuePair<string, object?> tag) { throw null; }
+        public void Record(T value, System.Collections.Generic.KeyValuePair<string, object?> tag1, System.Collections.Generic.KeyValuePair<string, object?> tag2) { throw null; }
+        public void Record(T value, System.Collections.Generic.KeyValuePair<string, object?> tag1, System.Collections.Generic.KeyValuePair<string, object?> tag2, System.Collections.Generic.KeyValuePair<string, object?> tag3) { throw null; }
+        public void Record(T value, params System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<string, object?>> tags) { throw null; }
+        public void Record(T value, params System.Collections.Generic.KeyValuePair<string, object?>[] tags) { throw null; }
+        public void Record(T value, in TagList tagList) { throw null; }
+        internal Gauge(Meter meter, string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>>? tags) :
+                        base(meter, name, unit, description, tags) { throw null; }
+    }
     public sealed class UpDownCounter<T> : Instrument<T> where T : struct
     {
         public void Add(T delta) { throw null; }
@@ -413,10 +425,12 @@ public abstract class Instrument<T> : Instrument where T : struct
     public delegate void MeasurementCallback<T>(Instrument instrument, T measurement, ReadOnlySpan<System.Collections.Generic.KeyValuePair<string, object?>> tags, object? state) where T : struct;
     public class Meter : IDisposable
     {
-        public Counter<T> CreateCounter<T>(string name, string? unit = null, string? description = null) where T : struct  { throw null; }
-        public Counter<T> CreateCounter<T>(string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>> tags) where T : struct  { throw null; }
-        public UpDownCounter<T> CreateUpDownCounter<T>(string name, string? unit = null, string? description = null) where T : struct  { throw null; }
-        public UpDownCounter<T> CreateUpDownCounter<T>(string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>> tags) where T : struct  { throw null; }
+        public Counter<T> CreateCounter<T>(string name, string? unit = null, string? description = null) where T : struct { throw null; }
+        public Counter<T> CreateCounter<T>(string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>> tags) where T : struct { throw null; }
+        public Gauge<T> CreateGauge<T>(string name) where T : struct { throw null; }
+        public Gauge<T> CreateGauge<T>(string name, string? unit = null, string? description = null, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>>? tags = null) where T : struct { throw null; }
+        public UpDownCounter<T> CreateUpDownCounter<T>(string name, string? unit = null, string? description = null) where T : struct { throw null; }
+        public UpDownCounter<T> CreateUpDownCounter<T>(string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>> tags) where T : struct { throw null; }
         public Histogram<T> CreateHistogram<T>(string name, string? unit = null, string? description = null) where T : struct { throw null; }
         public Histogram<T> CreateHistogram<T>(string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>> tags) where T : struct { throw null; }
         public ObservableCounter<T> CreateObservableCounter<T>(

diff --git a/...raries/System.Diagnostics.DiagnosticSource/src/System.Diagnostics.DiagnosticSource.csproj b/...raries/System.Diagnostics.DiagnosticSource/src/System.Diagnostics.DiagnosticSource.csproj
@@ -53,6 +53,7 @@ System.Diagnostics.DiagnosticSource</PackageDescription>
     <Compile Include="System\Diagnostics\Metrics\AggregatorStore.cs" />
     <Compile Include="System\Diagnostics\Metrics\Counter.cs" />
     <Compile Include="System\Diagnostics\Metrics\ExponentialHistogramAggregator.cs" />
+    <Compile Include="System\Diagnostics\Metrics\Gauge.cs" />
     <Compile Include="System\Diagnostics\Metrics\Histogram.cs" />
     <Compile Include="System\Diagnostics\Metrics\IMeterFactory.cs" />
     <Compile Include="System\Diagnostics\Metrics\Instrument.cs" />

diff --git a/.../System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/AggregationManager.cs b/.../System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/AggregationManager.cs
@@ -316,7 +316,7 @@ private void RemoveInstrumentState(Instrument instrument)
                     }
                 };
             }
-            else if (genericDefType == typeof(ObservableGauge<>))
+            else if (genericDefType == typeof(ObservableGauge<>) || genericDefType == typeof(Gauge<>))
             {
                 return () =>
                 {

diff --git a/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Gauge.cs b/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Gauge.cs
@@ -0,0 +1,76 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+
+namespace System.Diagnostics.Metrics
+{
+    /// <summary>
+    /// The Gauge is an instrument used to record non-additive values whenever changes occur. For example, record the room background noise level value when changes occur.
+    /// </summary>
+    /// <remarks>
+    /// This class supports only the following generic parameter types: <see cref="byte" />, <see cref="short" />, <see cref="int" />, <see cref="long" />, <see cref="float" />, <see cref="double" />, and <see cref="decimal" />
+    /// </remarks>
+    public sealed class Gauge<T> : Instrument<T> where T : struct
+    {
+        internal Gauge(Meter meter, string name, string? unit, string? description) : this(meter, name, unit, description, null)
+        {
+        }
+
+        internal Gauge(Meter meter, string name, string? unit, string? description, IEnumerable<KeyValuePair<string, object?>>? tags) : base(meter, name, unit, description, tags)
+        {
+            Publish();
+        }
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        public void Record(T value) => RecordMeasurement(value);
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        /// <param name="tag">A key-value pair tag associated with the measurement.</param>
+        public void Record(T value, KeyValuePair<string, object?> tag) => RecordMeasurement(value, tag);
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        /// <param name="tag1">A first key-value pair tag associated with the measurement.</param>
+        /// <param name="tag2">A second key-value pair tag associated with the measurement.</param>
+        public void Record(T value, KeyValuePair<string, object?> tag1, KeyValuePair<string, object?> tag2) => RecordMeasurement(value, tag1, tag2);
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        /// <param name="tag1">A first key-value pair tag associated with the measurement.</param>
+        /// <param name="tag2">A second key-value pair tag associated with the measurement.</param>
+        /// <param name="tag3">A third key-value pair tag associated with the measurement.</param>
+        public void Record(T value, KeyValuePair<string, object?> tag1, KeyValuePair<string, object?> tag2, KeyValuePair<string, object?> tag3) => RecordMeasurement(value, tag1, tag2, tag3);
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        /// <param name="tags">A span of key-value pair tags associated with the measurement.</param>
+        public void Record(T value, params ReadOnlySpan<KeyValuePair<string, object?>> tags) => RecordMeasurement(value, tags);
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        /// <param name="tags">A list of key-value pair tags associated with the measurement.</param>
+        public void Record(T value, params KeyValuePair<string, object?>[] tags) => RecordMeasurement(value, tags.AsSpan());
+
+        /// <summary>
+        /// Record the Gauge current value.
+        /// </summary>
+        /// <param name="value">The Gauge current value.</param>
+        /// <param name="tagList">A <see cref="T:System.Diagnostics.TagList" /> of tags associated with the measurement.</param>
+        public void Record(T value, in TagList tagList) => RecordMeasurement(value, in tagList);
+    }
+}
diff --git a/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Meter.cs b/src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Meter.cs
@@ -143,6 +143,30 @@ private void Initialize(string name, string? version, IEnumerable<KeyValuePair<s
         public Counter<T> CreateCounter<T>(string name, string? unit, string? description, IEnumerable<KeyValuePair<string, object?>>? tags) where T : struct
                 => (Counter<T>)GetOrCreateInstrument<T>(typeof(Counter<T>), name, unit, description, tags, () => new Counter<T>(this, name, unit, description, tags));
 
+        /// <summary>
+        /// Creates a Gauge instrument, which can be used to record non-additive values.
+        /// </summary>
+        /// <param name="name">The instrument name. cannot be null.</param>
+        /// <remarks>
+        /// Gauge is an Instrument which used to record non-additive values.
+        /// Example uses for Gauge: record the room background noise level value when changes occur.
+        /// </remarks>
+        public Gauge<T> CreateGauge<T>(string name) where T : struct => CreateGauge<T>(name, unit: null, description: null, tags: null);
+
+        /// <summary>
+        /// Create a metrics Gauge object.
+        /// </summary>
+        /// <param name="name">The instrument name. cannot be null.</param>
+        /// <param name="unit">Optional instrument unit of measurements.</param>
+        /// <param name="description">Optional instrument description.</param>
+        /// <param name="tags">tags to attach to the Gauge.</param>
+        /// <remarks>
+        /// Gauge is an Instrument which used to record non-additive values.
+        /// Example uses for Gauge: record the room background noise level value when changes occur.
+        /// </remarks>
+        public Gauge<T> CreateGauge<T>(string name, string? unit = null, string? description = null, IEnumerable<KeyValuePair<string, object?>>? tags = null) where T : struct
+                => (Gauge<T>)GetOrCreateInstrument<T>(typeof(Gauge<T>), name, unit, description, tags, () => new Gauge<T>(this, name, unit, description, tags));
+
         /// <summary>
         /// Histogram is an Instrument which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.
         /// </summary>
-Original file line number
+Diff line change
@@ Expand Up / @@ -316,7 +316,7 @@ private void RemoveInstrumentState(Instrument instrument) @@
                         }
                     };
                 }
-                else if (genericDefType == typeof(ObservableGauge<>))
+                else if (genericDefType == typeof(ObservableGauge<>) || genericDefType == typeof(Gauge<>))
                 {
                     return () =>
                     {
@@ Expand Down @@