From 6d84de324f88e8dd1fe660e652941b660e695eec Mon Sep 17 00:00:00 2001
From: James Crosswell <jamescrosswell@users.noreply.github.com>
Date: Wed, 26 Feb 2025 19:11:03 +1300
Subject: [PATCH 1/3] Added documentation for automatic heap dumps

---
 .../common/configuration/heap-dumps.mdx       | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 docs/platforms/dotnet/common/configuration/heap-dumps.mdx

diff --git a/docs/platforms/dotnet/common/configuration/heap-dumps.mdx b/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
new file mode 100644
index 0000000000000..45dcf6ef90e7f
--- /dev/null
+++ b/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
@@ -0,0 +1,79 @@
+---
+title: Heap Dumps
+sidebar_order: 23
+description: "This experimental feature allows you to automatically capture heap dumps for your application."
+---
+
+<Alert>
+
+The SDK relies on `dotnet-gcdump` to capture the heap dumps. `dotnet-gcdump` requires .NET 6 or later and must be [installed globally](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-gcdump#install) on the machine or container where the heap dumps will be captured.
+
+</Alert>
+
+Using the .NET SDK you can automatically captures heap dumps based on certain triggers. When triggered, the SDK captures the heap dump and sends an event to Sentry with the heap dump as an attachment.
+
+The basic configuration for enabling automatic heap dumps is:
+
+```csharp
+SentrySdk.Init(options => {
+    // All your other options like DSN etc.
+    ...
+    options.EnableHeapDumps(
+        // Triggers if the process uses more than 90% of the total available memory
+        90,
+        // Limit heap dumps to 3 per day with at least 2 hours between each event
+        Debouncer.PerDay(3, TimeSpan.FromHours(2)),
+        // Set the level for heap dump events to Warning
+        SentryLevel.Warning
+        );
+});
+```
+
+### Trigger
+
+The first argument to `EnableHeapDumps` is the *Trigger*. The above example passes an integer as the trigger, which configures the SDK to capture a heap dump when the memory allocated by your application exceeds a certain percentage threshold of total available memory.
+
+Alternatively, there is an overload of `EnableHeapDumps` that allows you to specify a custom trigger:
+
+```csharp
+SentrySdk.Init(options => {
+    // All your other options like DSN etc.
+    ...
+    options.EnableHeapDumps(
+        // Triggers if the process uses more than 10MB of memory
+        (usedMemory, totalMemory) => usedMemory > 10_000_000,
+        // Limit heap dumps to 3 per day with at least 2 hours between each event
+        Debouncer.PerDay(3, TimeSpan.FromHours(2)),
+        // Set the level for heap dump events to Warning
+        SentryLevel.Warning
+        );
+});
+```
+
+### Debouncer
+
+The second argument is a *Debouncer*, which is used to prevent heap dumps from being captured too often.
+
+The above examples configure a debouncer that limits heap dumps to 3 per day with a cooldown of at least 2 hours between each event. The other available debouncers are `PerMinute`, `PerHour`, and `PerApplicationLifetime`.
+
+If no debouncer is specified, this defaults to Debouncer.PerApplicationLifetime(1) - which means only one heap dump will be captured each time the application is run. If the application keeps running for 3 months then no more than one heap dump will be sent during that 3 month period.
+
+### Event Level
+
+The final argument determines the event level to associate with the event that the heap dump is attached to. If you don't specify a value then this defaults to `SentryLevel.Warning`.
+
+## Viewing heap dumps
+
+Heap dumps will be displayed as "Memory threshold exceeded" events in the Sentry UI. Clicking on such an event, you’ll see all the usual event details. However the event will also contain a `.gcdump` file as an attachment, that you can download for analysis.
+
+There are various different tools that you can use to view the dump file:
+- [dotnet-gcdump report](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-gcdump)
+- [dotnet-heapview](https://github.com/1hub/dotnet-heapview)
+- [Visual Studio](https://devblogs.microsoft.com/dotnet/collecting-and-analyzing-memory-dumps/)
+- [Perfview](https://github.com/microsoft/perfview)
+
+## Feedback
+
+This features is currently experimental and we're open to suggestions about how it could be improved.
+
+If you have any feedback about the capabilities or the API design, please join the [discussion on GitHub](https://github.com/getsentry/sentry-dotnet/discussions/3885).

From 65f474c867fd658810ff8e7cd10c5fee0e83bc8c Mon Sep 17 00:00:00 2001
From: James Crosswell <jamescrosswell@users.noreply.github.com>
Date: Mon, 3 Mar 2025 16:30:20 +1300
Subject: [PATCH 2/3] Update
 docs/platforms/dotnet/common/configuration/heap-dumps.mdx

Co-authored-by: Bruno Garcia <bruno@brunogarcia.com>
---
 docs/platforms/dotnet/common/configuration/heap-dumps.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/platforms/dotnet/common/configuration/heap-dumps.mdx b/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
index 45dcf6ef90e7f..ada57b1c06084 100644
--- a/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
+++ b/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
@@ -68,7 +68,7 @@ Heap dumps will be displayed as "Memory threshold exceeded" events in the Sentry
 
 There are various different tools that you can use to view the dump file:
 - [dotnet-gcdump report](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-gcdump)
-- [dotnet-heapview](https://github.com/1hub/dotnet-heapview)
+- [dotnet-heapview](https://github.com/getsentry/dotnet-heapview)
 - [Visual Studio](https://devblogs.microsoft.com/dotnet/collecting-and-analyzing-memory-dumps/)
 - [Perfview](https://github.com/microsoft/perfview)
 

From 23bd3b4b7502fd6cd1e66d602a30347f887dd11a Mon Sep 17 00:00:00 2001
From: James Crosswell <jamescrosswell@users.noreply.github.com>
Date: Mon, 3 Mar 2025 16:30:45 +1300
Subject: [PATCH 3/3] Update heap-dumps.mdx

---
 docs/platforms/dotnet/common/configuration/heap-dumps.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/platforms/dotnet/common/configuration/heap-dumps.mdx b/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
index ada57b1c06084..3bda17b4dd691 100644
--- a/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
+++ b/docs/platforms/dotnet/common/configuration/heap-dumps.mdx
@@ -15,7 +15,7 @@ Using the .NET SDK you can automatically captures heap dumps based on certain tr
 The basic configuration for enabling automatic heap dumps is:
 
 ```csharp
-SentrySdk.Init(options => {
+options => {
     // All your other options like DSN etc.
     ...
     options.EnableHeapDumps(
@@ -26,7 +26,7 @@ SentrySdk.Init(options => {
         // Set the level for heap dump events to Warning
         SentryLevel.Warning
         );
-});
+}
 ```
 
 ### Trigger
@@ -36,7 +36,7 @@ The first argument to `EnableHeapDumps` is the *Trigger*. The above example pass
 Alternatively, there is an overload of `EnableHeapDumps` that allows you to specify a custom trigger:
 
 ```csharp
-SentrySdk.Init(options => {
+options => {
     // All your other options like DSN etc.
     ...
     options.EnableHeapDumps(
@@ -47,7 +47,7 @@ SentrySdk.Init(options => {
         // Set the level for heap dump events to Warning
         SentryLevel.Warning
         );
-});
+}
 ```
 
 ### Debouncer
