[System.Diagnostics.DiagnosticSource] Implement metrics advice API

src/libraries/System.Diagnostics.DiagnosticSource/ref/System.Diagnostics.DiagnosticSourceActivity.cs

@@ -357,6 +357,7 @@ public sealed class UpDownCounter<T> : Instrument<T> where T : struct
     }
     public sealed class Histogram<T> : Instrument<T> where T : struct
     {
+        public HistogramAdvice<T>? Advice { get { throw null; } }
         internal Histogram(Meter meter, string name, string? unit, string? description) : base(meter, name, unit, description) { throw null; }
         public void Record(T value) { throw null; }
         public void Record(T value, System.Collections.Generic.KeyValuePair<string, object?> tag) { throw null; }
@@ -410,8 +411,12 @@ public class Meter : IDisposable
         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 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 Histogram<T> CreateHistogram<T>(string name) where T : struct { throw null; }
+        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
+        public Histogram<T> CreateHistogram<T>(string name, string? unit, string? description) where T : struct { throw null; }
+        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
+        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 Histogram<T> CreateHistogram<T>(string name, string? unit = default, string? description = default, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>>? tags = default, HistogramAdvice<T>? advice = default) where T : struct { throw null; }
         public ObservableCounter<T> CreateObservableCounter<T>(
                             string name,
                             Func<T> observeValue,
@@ -568,4 +573,9 @@ public abstract class ObservableInstrument<T> : Instrument where T : struct
         protected ObservableInstrument(Meter meter, string name, string? unit, string? description, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object?>> tags) : base(meter, name, unit, description) { throw null; }
         protected abstract System.Collections.Generic.IEnumerable<Measurement<T>> Observe();
     }
+    public sealed class HistogramAdvice<T> where T : struct
+    {
+        public HistogramAdvice(System.Collections.Generic.IEnumerable<T> explicitBucketBoundaries) { throw null; }
+        public System.Collections.Generic.IReadOnlyList<T>? ExplicitBucketBoundaries { get { throw null; } }
+    }
 }

src/libraries/System.Diagnostics.DiagnosticSource/src/Resources/Strings.resx

@@ -1,17 +1,17 @@
 <?xml version="1.0" encoding="utf-8"?>
 <root>
-  <!--
-    Microsoft ResX Schema
-
+  <!-- 
+    Microsoft ResX Schema 
+    
     Version 2.0
-
-    The primary goals of this format is to allow a simple XML format
-    that is mostly human readable. The generation and parsing of the
-    various data types are done through the TypeConverter classes
+    
+    The primary goals of this format is to allow a simple XML format 
+    that is mostly human readable. The generation and parsing of the 
+    various data types are done through the TypeConverter classes 
     associated with the data types.
-
+    
     Example:
-
+    
     ... ado.net/XML headers & schema ...
     <resheader name="resmimetype">text/microsoft-resx</resheader>
     <resheader name="version">2.0</resheader>
@@ -26,36 +26,36 @@
         <value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value>
         <comment>This is a comment</comment>
     </data>
-
-    There are any number of "resheader" rows that contain simple
+                
+    There are any number of "resheader" rows that contain simple 
     name/value pairs.
-
-    Each data row contains a name, and value. The row also contains a
-    type or mimetype. Type corresponds to a .NET class that support
-    text/value conversion through the TypeConverter architecture.
-    Classes that don't support this are serialized and stored with the
+    
+    Each data row contains a name, and value. The row also contains a 
+    type or mimetype. Type corresponds to a .NET class that support 
+    text/value conversion through the TypeConverter architecture. 
+    Classes that don't support this are serialized and stored with the 
     mimetype set.
-
-    The mimetype is used for serialized objects, and tells the
-    ResXResourceReader how to depersist the object. This is currently not
+    
+    The mimetype is used for serialized objects, and tells the 
+    ResXResourceReader how to depersist the object. This is currently not 
     extensible. For a given mimetype the value must be set accordingly:
-
-    Note - application/x-microsoft.net.object.binary.base64 is the format
-    that the ResXResourceWriter will generate, however the reader can
+    
+    Note - application/x-microsoft.net.object.binary.base64 is the format 
+    that the ResXResourceWriter will generate, however the reader can 
     read any of the formats listed below.
-
+    
     mimetype: application/x-microsoft.net.object.binary.base64
-    value   : The object must be serialized with
+    value   : The object must be serialized with 
             : System.Runtime.Serialization.Formatters.Binary.BinaryFormatter
             : and then encoded with base64 encoding.
-
+    
     mimetype: application/x-microsoft.net.object.soap.base64
-    value   : The object must be serialized with
+    value   : The object must be serialized with 
             : System.Runtime.Serialization.Formatters.Soap.SoapFormatter
             : and then encoded with base64 encoding.
 
     mimetype: application/x-microsoft.net.object.bytearray.base64
-    value   : The object must be serialized into a byte array
+    value   : The object must be serialized into a byte array 
             : using a System.ComponentModel.TypeConverter
             : and then encoded with base64 encoding.
     -->
@@ -174,4 +174,7 @@
   <data name="InvalidInstrumentType" xml:space="preserve">
     <value>The instrument is of different generic type.</value>
   </data>
-</root>
+  <data name="InvalidHistogramExplicitBucketBoundaries" xml:space="preserve">
+    <value>Histogram explicit bucket boundaries MUST be specified in ascending order and CANNOT contain duplicate values.</value>
+  </data>
+</root>

src/libraries/System.Diagnostics.DiagnosticSource/src/System.Diagnostics.DiagnosticSource.csproj

@@ -54,6 +54,7 @@ System.Diagnostics.DiagnosticSource</PackageDescription>
     <Compile Include="System\Diagnostics\Metrics\Counter.cs" />
     <Compile Include="System\Diagnostics\Metrics\ExponentialHistogramAggregator.cs" />
     <Compile Include="System\Diagnostics\Metrics\Histogram.cs" />
+    <Compile Include="System\Diagnostics\Metrics\HistogramAdvice.cs" />
     <Compile Include="System\Diagnostics\Metrics\IMeterFactory.cs" />
     <Compile Include="System\Diagnostics\Metrics\Instrument.cs" />
     <Compile Include="System\Diagnostics\Metrics\Instrument.common.cs" />

src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/Histogram.cs

@@ -15,12 +15,19 @@ namespace System.Diagnostics.Metrics
     /// </remarks>
     public sealed class Histogram<T> : Instrument<T> where T : struct
     {
-        internal Histogram(Meter meter, string name, string? unit, string? description) : this(meter, name, unit, description, tags: null)
+        /// <summary>
+        /// Gets the <see cref="HistogramAdvice{T}"/> associated with the instrument.
+        /// </summary>
+        public HistogramAdvice<T>? Advice { get; }
+
+        internal Histogram(Meter meter, string name, string? unit, string? description) : this(meter, name, unit, description, tags: null, advice: null)
         {
         }
 
-        internal Histogram(Meter meter, string name, string? unit, string? description, IEnumerable<KeyValuePair<string, object?>>? tags) : base(meter, name, unit, description, tags)
+        internal Histogram(Meter meter, string name, string? unit, string? description, IEnumerable<KeyValuePair<string, object?>>? tags, HistogramAdvice<T>? advice) : base(meter, name, unit, description, tags)
         {
+            Advice = advice;
+
             Publish();
         }
 

src/libraries/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Metrics/HistogramAdvice.cs

@@ -0,0 +1,63 @@
+// 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>
+    /// Contains settings used to advise metrics consumers how to construct storage for <see cref="Histogram{T}"/> instruments.
+    /// </summary>
+    /// <typeparam name="T">Histogram value type.</typeparam>
+    public sealed class HistogramAdvice<T> where T : struct
+    {
+        /// <summary>
+        /// Constructs a new instance of <see cref="HistogramAdvice{T}"/>.
+        /// </summary>
+        /// <param name="explicitBucketBoundaries">
+        /// <para>Explicit bucket boundaries advised to be used with the histogram.</para>
+        /// <para>Notes:
+        /// <list type="bullet">
+        /// <item>Bucket boundaries MUST be specified in ascending order and CANNOT contain duplicate values.</item>
+        /// <item>An empty set of bucket boundaries hints that the histogram should NOT contain buckets and should only track count and sum values.</item>
+        /// </list>
+        /// </para>
+        /// </param>
+        public HistogramAdvice(IEnumerable<T> explicitBucketBoundaries)
+        {
+            if (explicitBucketBoundaries is null)
+            {
+                throw new ArgumentNullException(nameof(explicitBucketBoundaries));
+            }
+
+            List<T> explicitBucketBoundariesCopy = [.. explicitBucketBoundaries];
+
+            if (!IsSortedAndDistinct(explicitBucketBoundariesCopy))
+            {
+                throw new ArgumentException(SR.InvalidHistogramExplicitBucketBoundaries, nameof(explicitBucketBoundaries));
+            }
+
+            ExplicitBucketBoundaries = explicitBucketBoundariesCopy;
+        }
+
+        /// <summary>
+        /// Gets the explicit bucket boundaries advised to be used with the histogram.
+        /// </summary>
+        public IReadOnlyList<T>? ExplicitBucketBoundaries { get; }
+
+        private static bool IsSortedAndDistinct(List<T> values)
+        {
+            Comparer<T> comparer = Comparer<T>.Default;
+
+            for (int i = 1; i < values.Count; i++)
+            {
+                if (comparer.Compare(values[i - 1], values[i]) >= 0)
+                {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+    }
+}