Marked AutoHeapDump functionality as experimental

Author: jamescrosswell

Directory.Build.props

@@ -11,6 +11,9 @@
     <Features>strict</Features>
     <ImplicitUsings>true</ImplicitUsings>
 
+    <!-- Ignore our own diagnostic ids - these are meant to be external warnings only -->
+    <NoWarn>$(NoWarn);SENTRY0001</NoWarn>
+
     <!-- Allow references to unsigned assemblies (like MAUI) from signed projects -->
     <NoWarn>$(NoWarn);CS8002</NoWarn>
 

src/Sentry/Debouncer.cs

@@ -1,9 +1,14 @@
+using Sentry.Infrastructure;
+
 namespace Sentry;
 
+#if MEMORY_DUMP_SUPPORTED
+
 /// <summary>
 /// A debouncer that can be used to limit the number of occurrences of an event within a given interval and optionally,
 /// enforce a minimum cooldown period between events.
 /// </summary>
+[Experimental(DiagnosticId.ExperimentalFeature)]
 public class Debouncer
 {
     internal enum DebouncerInterval { Minute, Hour, Day, ApplicationLifetime }
@@ -101,3 +106,5 @@ internal bool CanProcess(DateTimeOffset? timestamp = null)
         return _cooldown is not { } cooldown || _lastEvent + cooldown <= eventTime;
     }
 }
+
+#endif

src/Sentry/HeapDumpTriggers.cs

@@ -1,11 +1,16 @@
+using Sentry.Infrastructure;
+
 namespace Sentry;
 
+#if MEMORY_DUMP_SUPPORTED
+
 /// <summary>
 /// Delegate that determines whether a heap dump should be triggered or not.
 /// </summary>
 /// <param name="usedMemory">Memory currently used by the process</param>
 /// <param name="totalMemory">Total available memory</param>
 /// <returns><see langword="true"/> if the heap dump should be triggered; otherwise, <see langword="false"/>.</returns>
+[Experimental(DiagnosticId.ExperimentalFeature)]
 public delegate bool HeapDumpTrigger(long usedMemory, long totalMemory);
 
 internal static class HeapDumpTriggers
@@ -25,3 +30,5 @@ internal static HeapDumpTrigger MemoryPercentageThreshold(int memoryPercentageTh
         };
     }
 }
+
+#endif

src/Sentry/Infrastructure/DiagnosticId.cs

@@ -0,0 +1,11 @@
+namespace Sentry.Infrastructure;
+
+internal static class DiagnosticId
+{
+#if NET5_0_OR_GREATER
+    /// <summary>
+    /// Indicates that the feature is experimental and may be subject to change or removal in future versions.
+    /// </summary>
+    internal const string ExperimentalFeature = "SENTRY0001";
+#endif
+}

src/Sentry/Internal/HeapDumpOptions.cs

@@ -1,3 +1,7 @@
 namespace Sentry.Internal;
 
+#if MEMORY_DUMP_SUPPORTED
+
 internal record HeapDumpOptions(HeapDumpTrigger Trigger, Debouncer Debouncer, SentryLevel Level);
+
+#endif

src/Sentry/SentryOptions.cs

@@ -525,9 +525,18 @@ public int MaxQueueItems
 #if MEMORY_DUMP_SUPPORTED
 
     /// <summary>
+    /// <para>
     /// Configures a heap dump to be captured if the percentage of memory used exceeds a certain threshold.
     /// This can be useful to diagnose memory leaks.
+    /// </para>
+    /// <para>
+    /// Note: This feature requires `dotnet-gcdump` to be installed globally on the machine or container where the heap
+    /// dumps will be captured. You can install this by running: `dotnet tool install --global dotnet-gcdump`
+    /// </para>
     /// </summary>
+    /// <remarks>
+    /// This API is experimental and may change in future versions.
+    /// </remarks>
     /// <param name="memoryPercentageThreshold">
     /// The memory threshold at which to trigger a heap dump, as a percentage of total available memory.
     /// Must be a number between 1 and 99.
@@ -538,6 +547,7 @@ public int MaxQueueItems
     /// </param>
     /// <param name="level">Optional parameter controlling the event level associated with heap dumps.
     /// Defaults to <see cref="SentryLevel.Warning"/>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
     public void EnableHeapDumps(short memoryPercentageThreshold, Debouncer? debouncer = null, SentryLevel level = SentryLevel.Warning)
         => EnableHeapDumps(HeapDumpTriggers.MemoryPercentageThreshold(memoryPercentageThreshold), debouncer, level);
 
@@ -550,6 +560,9 @@ public void EnableHeapDumps(short memoryPercentageThreshold, Debouncer? debounce
     /// dumps will be captured. You can install this by running: `dotnet tool install --global dotnet-gcdump`
     /// </para>
     /// </summary>
+    /// <remarks>
+    /// This API is experimental and may change in future versions.
+    /// </remarks>
     /// <param name="trigger">
     /// A custom trigger function that accepts the current memory usage and total available memory as arguments and
     /// return true to indicate that a heap dump should be captured or false otherwise.
@@ -560,6 +573,7 @@ public void EnableHeapDumps(short memoryPercentageThreshold, Debouncer? debounce
     /// </param>
     /// <param name="level">Optional parameter controlling the event level associated with heap dumps.
     /// Defaults to <see cref="SentryLevel.Warning"/>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
     public void EnableHeapDumps(HeapDumpTrigger trigger, Debouncer? debouncer = null, SentryLevel level = SentryLevel.Warning)
         => HeapDumpOptions = new HeapDumpOptions(trigger, debouncer ?? Debouncer.PerApplicationLifetime(), level);
 

test/Sentry.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt

@@ -75,6 +75,7 @@ namespace Sentry
         ManagedBackgroundThread = 1,
         Native = 2,
     }
+    [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
     public class Debouncer
     {
         public static Sentry.Debouncer PerApplicationLifetime(int eventMaximum = 1, System.TimeSpan? cooldown = default) { }
@@ -132,6 +133,7 @@ namespace Sentry
     {
         public static void SetTags(this Sentry.IHasTags hasTags, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, string>> tags) { }
     }
+    [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
     public delegate bool HeapDumpTrigger(long usedMemory, long totalMemory);
     public static class HintTypes
     {
@@ -730,7 +732,9 @@ namespace Sentry
         public void DisableSystemDiagnosticsMetricsIntegration() { }
         public void DisableUnobservedTaskExceptionCapture() { }
         public void DisableWinUiUnhandledExceptionIntegration() { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
         public void EnableHeapDumps(Sentry.HeapDumpTrigger trigger, Sentry.Debouncer? debouncer = null, Sentry.SentryLevel level = 2) { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
         public void EnableHeapDumps(short memoryPercentageThreshold, Sentry.Debouncer? debouncer = null, Sentry.SentryLevel level = 2) { }
         public System.Collections.Generic.IEnumerable<Sentry.Extensibility.ISentryEventProcessor> GetAllEventProcessors() { }
         public System.Collections.Generic.IEnumerable<Sentry.Extensibility.ISentryEventExceptionProcessor> GetAllExceptionProcessors() { }

test/Sentry.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt

@@ -75,6 +75,7 @@ namespace Sentry
         ManagedBackgroundThread = 1,
         Native = 2,
     }
+    [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
     public class Debouncer
     {
         public static Sentry.Debouncer PerApplicationLifetime(int eventMaximum = 1, System.TimeSpan? cooldown = default) { }
@@ -132,6 +133,7 @@ namespace Sentry
     {
         public static void SetTags(this Sentry.IHasTags hasTags, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, string>> tags) { }
     }
+    [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
     public delegate bool HeapDumpTrigger(long usedMemory, long totalMemory);
     public static class HintTypes
     {
@@ -730,7 +732,9 @@ namespace Sentry
         public void DisableSystemDiagnosticsMetricsIntegration() { }
         public void DisableUnobservedTaskExceptionCapture() { }
         public void DisableWinUiUnhandledExceptionIntegration() { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
         public void EnableHeapDumps(Sentry.HeapDumpTrigger trigger, Sentry.Debouncer? debouncer = null, Sentry.SentryLevel level = 2) { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
         public void EnableHeapDumps(short memoryPercentageThreshold, Sentry.Debouncer? debouncer = null, Sentry.SentryLevel level = 2) { }
         public System.Collections.Generic.IEnumerable<Sentry.Extensibility.ISentryEventProcessor> GetAllEventProcessors() { }
         public System.Collections.Generic.IEnumerable<Sentry.Extensibility.ISentryEventExceptionProcessor> GetAllExceptionProcessors() { }

test/Sentry.Tests/ApiApprovalTests.Run.Net4_8.verified.txt

@@ -74,13 +74,6 @@ namespace Sentry
         Managed = 0,
         ManagedBackgroundThread = 1,
     }
-    public class Debouncer
-    {
-        public static Sentry.Debouncer PerApplicationLifetime(int eventMaximum = 1, System.TimeSpan? cooldown = default) { }
-        public static Sentry.Debouncer PerDay(int eventMaximum = 1, System.TimeSpan? cooldown = default) { }
-        public static Sentry.Debouncer PerHour(int eventMaximum = 1, System.TimeSpan? cooldown = default) { }
-        public static Sentry.Debouncer PerMinute(int eventMaximum = 1, System.TimeSpan? cooldown = default) { }
-    }
     [System.Flags]
     public enum DeduplicateMode
     {
@@ -130,7 +123,6 @@ namespace Sentry
     {
         public static void SetTags(this Sentry.IHasTags hasTags, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, string>> tags) { }
     }
-    public delegate bool HeapDumpTrigger(long usedMemory, long totalMemory);
     public static class HintTypes
     {
         public const string HttpResponseMessage = "http-response-message";

test/Sentry.Tests/DebouncerTests.cs

@@ -1,5 +1,7 @@
 namespace Sentry.Tests;
 
+#if MEMORY_DUMP_SUPPORTED
+
 public class DebouncerTests
 {
     [Fact]
@@ -142,3 +144,5 @@ public void RecordOccurence_AfterInterval_ResetsInterval()
         debouncer._lastEvent.Should().Be(secondEventTime);
     }
 }
+
+#endif