Automatically capture heap dumps

CHANGELOG.md

@@ -11,8 +11,8 @@
 - `SentryOptions.EnableTracing` has been removed. Instead, tracing should be enabled or disabled by setting the `SentryOptions.TracesSampleRate` or by using `SentryOptions.TracesSampler` to configure a sampling function ([#3569](https://github.com/getsentry/sentry-dotnet/pull/3569))
 - The `FailedRequestTargets`, `TagFilters` and `TracePropagationTargets` options have all been changed from `SubstringOrRegexPattern` to `IList<StringOrRegex>` ([#3566](https://github.com/getsentry/sentry-dotnet/pull/3566))
 - `Scope.Transaction` is now always stored as an `AsyncLocal` also in [Global Mode](https://docs.sentry.io/platforms/dotnet/configuration/options/#is-global-mode-enabled), to prevent auto-instrumented spans from the UI ending up parented to transactions from a background task (or vice versa). ([#3596](https://github.com/getsentry/sentry-dotnet/pull/3596))
+- Heap dumps can be captured automatically when memory usage exceeds a configurable threshold ([#3667](https://github.com/getsentry/sentry-dotnet/pull/3667))
 
-## Unreleased
 ## 4.12.1
 
 ### Fixes

Directory.Build.props

@@ -1,7 +1,7 @@
 <Project>
 
   <PropertyGroup>
-    <VersionPrefix>4.12.1</VersionPrefix>
+    <VersionPrefix>4.12.2-alpha</VersionPrefix>
     <LangVersion>12</LangVersion>
     <AccelerateBuildsInVisualStudio>true</AccelerateBuildsInVisualStudio>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Sentry.sln.DotSettings

@@ -4,6 +4,7 @@
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=OS/@EntryIndexedValue">OS</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=QL/@EntryIndexedValue">QL</s:String>
 	<s:String x:Key="/Default/CodeStyle/Naming/CSharpNaming/Abbreviations/=UI/@EntryIndexedValue">UI</s:String>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=debouncer/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Enricher/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=enrichers/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=instrumenter/@EntryIndexedValue">True</s:Boolean>

samples/Sentry.Samples.Console.Basic/Program.cs

@@ -4,6 +4,7 @@
  * - Performance Tracing (Transactions / Spans)
  * - Release Health (Sessions)
  * - MSBuild integration for Source Context (see the csproj)
+ * - Heap Dumps (.NET 6.0 or later)
  *
  * For more advanced features of the SDK, see Sentry.Samples.Console.Customized.
  */
@@ -12,6 +13,8 @@
 
 using System.Net.Http;
 
+CancellationTokenSource cts = new();
+
 SentrySdk.Init(options =>
 {
     // You can set here in code, or you can set it in the SENTRY_DSN environment variable.
@@ -33,66 +36,133 @@
 
     // This option tells Sentry to capture 100% of traces. You still need to start transactions and spans.
     options.TracesSampleRate = 1.0;
-});
 
-// This starts a new transaction and attaches it to the scope.
-var transaction = SentrySdk.StartTransaction("Program Main", "function");
-SentrySdk.ConfigureScope(scope => scope.Transaction = transaction);
+#if NET6_0_OR_GREATER
+    // This option tells Sentry to capture a heap dump when the process uses more than 5% of the total memory. The heap
+    // dump will be sent to Sentry as a file attachment.
+    options.EnableHeapDumps(5);
+
+    // This determines the level of heap dump events that are sent to Sentry
+    options.HeapDumpEventLevel = SentryLevel.Warning;
 
-// Do some work. (This is where you'd have your own application logic.)
-await FirstFunction();
-await SecondFunction();
-await ThirdFunction();
+    // A debouncer can be configured to tell Sentry how frequently to send heap dumps. In this case we've configured it
+    // to capture a maximum of 3 events per day and to wait at least 1 hour between each event.
+    options.HeapDumpDebouncer = Debouncer.PerDay(3, TimeSpan.FromHours(1));
 
-// Always try to finish the transaction successfully.
-// Unhandled exceptions will fail the transaction automatically.
-// Optionally, you can try/catch the exception, and call transaction.Finish(exception) on failure.
-transaction.Finish();
+    // This is an example of intercepting events before they get sent to Sentry. Typically, you might use this to
+    // filter events that you didn't want to send but in this case we're using it to detect when a heap dump has
+    // been captured, so we know when to stop allocating memory in the heap dump demo.
+    options.SetBeforeSend((evt, hint) =>
+    {
+        cts.Cancel();
+        return evt; // If we returned null here, that would stop the event from being sent
+    });
+#endif
+});
 
-async Task FirstFunction()
+#if NET6_0_OR_GREATER
+await Task.Delay(1000);
+Console.WriteLine();
+Console.WriteLine("Choose a demo:");
+Console.WriteLine("1. Tracing");
+Console.WriteLine("2. Heap Dump");
+Console.WriteLine("... or press any other key to quit.");
+switch (Console.ReadKey().KeyChar)
 {
-    // This is an example of making an HttpRequest. A trace us automatically captured by Sentry for this.
-    var messageHandler = new SentryHttpMessageHandler();
-    var httpClient = new HttpClient(messageHandler, true);
-    var html = await httpClient.GetStringAsync("https://example.com/");
-    Console.WriteLine(html);
+    case '1':
+        await TracingDemo();
+        break;
+    case '2':
+        await HeapDumpDemo(cts.Token);
+        break;
 }
+#else
+    await TracingDemo();
+#endif
 
-async Task SecondFunction()
+async Task TracingDemo()
 {
-    var span = transaction.StartChild("function", nameof(SecondFunction));
+    // This starts a new transaction and attaches it to the scope.
+    var transaction = SentrySdk.StartTransaction("Program Main", "function");
+    SentrySdk.ConfigureScope(scope => scope.Transaction = transaction);
 
-    try
-    {
-        // Simulate doing some work
-        await Task.Delay(100);
+    // Do some work. (This is where you'd have your own application logic.)
+    await FirstFunction();
+    await SecondFunction();
+    await ThirdFunction();
+
+    // Always try to finish the transaction successfully.
+    // Unhandled exceptions will fail the transaction automatically.
+    // Optionally, you can try/catch the exception, and call transaction.Finish(exception) on failure.
+    transaction.Finish();
 
-        // Throw an exception
-        throw new ApplicationException("Something happened!");
+    async Task FirstFunction()
+    {
+        // This is an example of making an HttpRequest. A trace us automatically captured by Sentry for this.
+        var messageHandler = new SentryHttpMessageHandler();
+        var httpClient = new HttpClient(messageHandler, true);
+        var html = await httpClient.GetStringAsync("https://example.com/");
+        Console.WriteLine(html);
     }
-    catch (Exception exception)
+
+    async Task SecondFunction()
     {
-        // This is an example of capturing a handled exception.
-        SentrySdk.CaptureException(exception);
-        span.Finish(exception);
+        var span = transaction.StartChild("function", nameof(SecondFunction));
+
+        try
+        {
+            // Simulate doing some work
+            await Task.Delay(100);
+
+            // Throw an exception
+            throw new ApplicationException("Something happened!");
+        }
+        catch (Exception exception)
+        {
+            // This is an example of capturing a handled exception.
+            SentrySdk.CaptureException(exception);
+            span.Finish(exception);
+        }
+
+        span.Finish();
     }
 
-    span.Finish();
+    async Task ThirdFunction()
+    {
+        var span = transaction.StartChild("function", nameof(ThirdFunction));
+        try
+        {
+            // Simulate doing some work
+            await Task.Delay(100);
+
+            // This is an example of an unhandled exception.  It will be captured automatically.
+            throw new InvalidOperationException("Something happened that crashed the app!");
+        }
+        finally
+        {
+            span.Finish();
+        }
+    }
 }
 
-async Task ThirdFunction()
+// Heap dumps are only supported in .NET 6.0 or later.
+#if NET6_0_OR_GREATER
+async Task HeapDumpDemo(CancellationToken cancellationToken)
 {
-    var span = transaction.StartChild("function", nameof(ThirdFunction));
-    try
+    var memoryHog = new List<byte[]>();
+    Console.WriteLine();
+    Console.WriteLine("Hogging memory...");
+
+    // Sentry checks memory usage every time a full garbage collection occurs. It might take a while to trigger this,
+    // although we've configured some ridiculously aggressive settings in the runtimeconfig.template.json file to make
+    // this happen more quickly, for the purposes of this demo... definitely don't do this in production!
+    while (cancellationToken.IsCancellationRequested == false)
     {
-        // Simulate doing some work
-        await Task.Delay(100);
-
-        // This is an example of an unhandled exception.  It will be captured automatically.
-        throw new InvalidOperationException("Something happened that crashed the app!");
-    }
-    finally
-    {
-        span.Finish();
+        var array = new byte[2_000_000_000];
+        array.Initialize();
+        memoryHog.Add(array);
     }
+    GC.KeepAlive(memoryHog);
+    await Task.CompletedTask;
 }
+#endif

samples/Sentry.Samples.Console.Basic/Sentry.Samples.Console.Basic.csproj

@@ -4,7 +4,7 @@
     <OutputType>Exe</OutputType>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <TargetFrameworks>net8.0;net6.0;net462</TargetFrameworks>
+    <TargetFrameworks>net8.0;net462</TargetFrameworks>
   </PropertyGroup>
   <PropertyGroup Condition="$(TargetFramework.StartsWith('net8'))">
     <PublishAot>true</PublishAot>

samples/Sentry.Samples.Console.Basic/runtimeconfig.template.json

@@ -0,0 +1,6 @@
+{
+  "configProperties": {
+    "System.GC.ConserveMemory": 9,
+    "System.GC.HighMemoryPercent": 20
+  }
+}

src/Sentry/BindableSentryOptions.cs

@@ -21,6 +21,9 @@ internal partial class BindableSentryOptions
     public string? Environment { get; set; }
     public string? Dsn { get; set; }
     public int? MaxQueueItems { get; set; }
+#if NET6_0_OR_GREATER && !(IOS || ANDROID)
+    public SentryLevel? HeapDumpEventLevel { get; set; }
+#endif
     public int? MaxCacheItems { get; set; }
     public TimeSpan? ShutdownTimeout { get; set; }
     public TimeSpan? FlushTimeout { get; set; }
@@ -68,6 +71,9 @@ public void ApplyTo(SentryOptions options)
         options.Environment = Environment ?? options.Environment;
         options.Dsn = Dsn ?? options.Dsn;
         options.MaxQueueItems = MaxQueueItems ?? options.MaxQueueItems;
+#if NET6_0_OR_GREATER && !(IOS || ANDROID)
+        options.HeapDumpEventLevel = HeapDumpEventLevel ?? options.HeapDumpEventLevel;
+#endif
         options.MaxCacheItems = MaxCacheItems ?? options.MaxCacheItems;
         options.ShutdownTimeout = ShutdownTimeout ?? options.ShutdownTimeout;
         options.FlushTimeout = FlushTimeout ?? options.FlushTimeout;

src/Sentry/Debouncer.cs

@@ -0,0 +1,108 @@
+namespace Sentry;
+
+/// <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>
+public class Debouncer
+{
+    internal enum DebouncerInterval { Minute, Hour, Day, ApplicationLifetime }
+
+    internal DateTimeOffset _intervalStart = DateTimeOffset.MinValue;
+    internal DateTimeOffset _lastEvent = DateTimeOffset.MinValue;
+    internal int _occurrences;
+
+    internal readonly DebouncerInterval _intervalType;
+    internal readonly int _eventMaximum;
+    private readonly TimeSpan? _cooldown;
+
+    private Debouncer(DebouncerInterval intervalType, int eventMaximum = 1, TimeSpan? cooldown = null)
+    {
+        _intervalType = intervalType;
+        _cooldown = cooldown;
+        _eventMaximum = eventMaximum;
+    }
+
+    /// <summary>
+    /// Creates a debouncer that limits the number of events per minute
+    /// </summary>
+    /// <param name="eventMaximum">The maximum number of events that will be processed per minute</param>
+    /// <param name="cooldown">An optional obligatory cooldown since the last event before any other events will be processed</param>
+    /// <returns></returns>
+    public static Debouncer PerMinute(int eventMaximum = 1, TimeSpan? cooldown = null)
+        => new(DebouncerInterval.Minute, eventMaximum, cooldown);
+
+    /// <summary>
+    /// Creates a debouncer that limits the number of events per hour
+    /// </summary>
+    /// <param name="eventMaximum">The maximum number of events that will be processed per hour</param>
+    /// <param name="cooldown">An optional obligatory cooldown since the last event before any other events will be processed</param>
+    /// <returns></returns>
+    public static Debouncer PerHour(int eventMaximum = 1, TimeSpan? cooldown = null)
+        => new(DebouncerInterval.Hour, eventMaximum, cooldown);
+
+    /// <summary>
+    /// Creates a debouncer that limits the number of events per day
+    /// </summary>
+    /// <param name="eventMaximum">The maximum number of events that will be processed per day</param>
+    /// <param name="cooldown">An optional obligatory cooldown since the last event before any other events will be processed</param>
+    /// <returns></returns>
+    public static Debouncer PerDay(int eventMaximum = 1, TimeSpan? cooldown = null)
+        => new(DebouncerInterval.Day, eventMaximum, cooldown);
+
+    /// <summary>
+    /// Creates a debouncer that limits the number of events that will be processed for the lifetime of the application
+    /// </summary>
+    /// <param name="eventMaximum">The maximum number of events that will be processed</param>
+    /// <param name="cooldown">An optional obligatory cooldown since the last event before any other events will be processed</param>
+    /// <returns></returns>
+    public static Debouncer PerApplicationLifetime(int eventMaximum = 1, TimeSpan? cooldown = null)
+        => new(DebouncerInterval.ApplicationLifetime, eventMaximum, cooldown);
+
+    private TimeSpan IntervalTimeSpan()
+    {
+        switch (_intervalType)
+        {
+            case DebouncerInterval.Minute:
+                return TimeSpan.FromMinutes(1);
+            case DebouncerInterval.Hour:
+                return TimeSpan.FromHours(1);
+            case DebouncerInterval.Day:
+                return TimeSpan.FromDays(1);
+            case DebouncerInterval.ApplicationLifetime:
+                return TimeSpan.MaxValue;
+            default:
+                throw new ArgumentOutOfRangeException(nameof(_intervalType));
+        }
+    }
+
+    internal void RecordOccurence(DateTimeOffset? timestamp = null)
+    {
+        var eventTime = timestamp ?? DateTimeOffset.UtcNow;
+
+        if (eventTime - _intervalStart >= IntervalTimeSpan())
+        {
+            _intervalStart = eventTime;
+            _occurrences = 0;
+        }
+
+        _occurrences++;
+        _lastEvent = eventTime;
+    }
+
+    internal bool CanProcess(DateTimeOffset? timestamp = null)
+    {
+        if (_occurrences >= _eventMaximum)
+        {
+            return false;
+        }
+
+        var eventTime = timestamp ?? DateTimeOffset.UtcNow;
+        if (_cooldown is { } cooldown && _lastEvent + cooldown > eventTime)
+        {
+            return false;
+        }
+
+        return true;
+    }
+}

src/Sentry/GCDump.props

@@ -0,0 +1,30 @@
+<Project>
+  <!-- Check if we're building for a target framework that supports dotnet-gcdump -->
+  <PropertyGroup>
+    <PlatformIsLegacy Condition="$(TargetFramework.StartsWith('net4')) or $(TargetFramework.StartsWith('netstandard'))">true</PlatformIsLegacy>
+    <PlatformIsMobile Condition="$(TargetFramework.EndsWith('android')) or $(TargetFramework.EndsWith('ios')) or $(TargetFramework.EndsWith('maccatalyst'))">true</PlatformIsMobile>
+    <PlatformSupportsGcDump Condition="!($(PlatformIsLegacy) == 'true' or $(PlatformIsMobile) == 'true')">true</PlatformSupportsGcDump>
+
+    <GCDumpVersion>8.0.547301</GCDumpVersion>
+    <GCDumpRootDirectory>$([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)..\..\tools\gcdump\'))</GCDumpRootDirectory>
+    <GCDumpTempDirectory>$(GCDumpRootDirectory)$(GCDumpVersion)\</GCDumpTempDirectory>
+    <!-- This is just where the relevant files are stored in the dotnet-gcdump Nuget package -->
+    <GCDumpIncludeFiles>$(GCDumpTempDirectory).store\dotnet-gcdump\$(GCDumpVersion)\dotnet-gcdump\$(GCDumpVersion)\tools\net6.0\any\</GCDumpIncludeFiles>
+  </PropertyGroup>
+
+  <Target Name="DownloadGCDump" BeforeTargets="CollectPackageReferences" Condition="'$(PlatformSupportsGcDump)' == 'true'">
+    <Message Importance="normal" Text="Found dotnet-gcdump - skipping download... " Condition="Exists('$(GCDumpIncludeFiles)')" />
+    <Message Importance="normal" Text="dotnet-gcdump not found... downloading to $(GCDumpTempDirectory)" Condition="!Exists('$(GCDumpIncludeFiles)')" />
+
+    <!-- NuGet doesn't have any "download" functionality, so we'll install it locally to a temporary folder   -->
+    <Exec Command="dotnet tool install dotnet-gcdump --version $(GCDumpVersion) --tool-path $(GCDumpTempDirectory)" Condition="!Exists('$(GCDumpIncludeFiles)')" IgnoreExitCode="true" />
+
+    <Message Importance="high" Text="Unable to locate dotnet-gcdump files after install : $(GCDumpIncludeFiles)" Condition="!Exists('$(GCDumpIncludeFiles)')" />
+  </Target>
+
+  <!-- Include GCDump in the Sentry Nuget package. -->
+  <ItemGroup Condition="'$(PlatformSupportsGcDump)' == 'true'">
+    <None Include="$(GCDumpIncludeFiles)**" Pack="true" PackagePath="tools\dotnet-gcdump\" />
+  </ItemGroup>
+
+</Project>