[Diagnostics] Add EventPipe Buffer Mode and EventFilter

docs/core/diagnostics/dotnet-gcdump.md

@@ -1,8 +1,9 @@
 ---
 title: dotnet-gcdump diagnostic tool - .NET CLI
 description: Learn how to install and use dotnet-gcdump CLI tool to collect GC (Garbage Collector) dumps of live .NET processes using the .NET EventPipe.
-ms.date: 06/03/2025
+ms.date: 07/02/2026
 ms.topic: reference
+ai-usage: ai-assisted
 ---
 # Heap analysis tool (dotnet-gcdump)
 
@@ -46,6 +47,9 @@ The `dotnet-gcdump` global tool collects GC (Garbage Collector) dumps of live .N
 - Analyzing roots of objects (answering questions like, "what still has a reference to this type?").
 - Collecting general statistics about the counts of objects on the heap.
 
+> [!NOTE]
+> `dotnet-gcdump collect` and `report` default to non-lossy (`Block`) buffering, which produces complete dumps on large heaps. `Block` requires a .NET 11+ target runtime; on older runtimes the tool automatically falls back to the lossy buffer.
+
 ### View the GC dump captured from dotnet-gcdump
 
 On Windows, `.gcdump` files can be viewed in [PerfView](https://github.com/microsoft/perfview) for analysis or in Visual Studio. Currently, there is no way of opening a `.gcdump` on non-Windows platforms.
@@ -80,7 +84,7 @@ Collects a GC dump from a currently running process.
 ### Synopsis
 
 ```console
-dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-file-path>] [-v|--verbose] [-t|--timeout <timeout>] [-n|--name <name>] [--dsrouter <ios|ios-sim|android|android-emu>]
+dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-file-path>] [-v|--verbose] [-t|--timeout <timeout>] [-n|--name <name>] [--dsrouter <ios|ios-sim|android|android-emu>] [--buffering-mode <Drop|Block>]
 ```
 
 ### Options
@@ -131,6 +135,13 @@ dotnet-gcdump collect [-h|--help] [-p|--process-id <pid>] [-o|--output <gcdump-f
 
   Starts [dotnet-dsrouter](dotnet-dsrouter.md) and connects to it. Requires [dotnet-dsrouter](dotnet-dsrouter.md) to be installed. Run `dotnet-dsrouter -h` for more information.
 
+- **`--buffering-mode <Drop|Block>`**
+
+  Sets how the runtime buffers events while the GC dump is collected. Accepts `0`/`Drop` or `1`/`Block` (case-insensitive), and defaults to `Block`.
+
+  - `0` / `Drop`: the lossy circular buffer. Events are dropped when the buffer overflows.
+  - `1` / `Block` (default): non-lossy collection. The runtime blocks event producers until the buffer drains instead of overwriting events when the buffer fills, which produces a complete GC dump on large heaps. `Block` requires a .NET 11+ target runtime and can make collection slower because the target application pauses more while the GC dump is collected. On older runtimes, the tool automatically falls back to `Drop` (lossy).
+
 > [!NOTE]
 > To collect a GC dump using `dotnet-gcdump`, it needs to be run as the same user as the user running target process or as root. Otherwise, the tool will fail to establish a connection with the target process.
 
@@ -198,7 +209,7 @@ Generate a report from a previously generated GC dump or from a running process,
 ### Synopsis
 
 ```console
-dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <HeapStat>]
+dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <HeapStat>] [--buffering-mode <Drop|Block>]
 ```
 
 ### Options
@@ -215,6 +226,13 @@ dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <Heap
 
   The type of report to generate. Available options: heapstat (default).
 
+- **`--buffering-mode <Drop|Block>`**
+
+  When you report from a running process with `--process-id`, sets how the runtime buffers events while the GC dump is collected. Accepts `0`/`Drop` or `1`/`Block` (case-insensitive), and defaults to `Block`. The option has no effect when you report from an existing `.gcdump` file.
+
+  - `0` / `Drop`: the lossy circular buffer. Events are dropped when the buffer overflows.
+  - `1` / `Block` (default): non-lossy collection. The runtime blocks event producers until the buffer drains instead of overwriting events when the buffer fills, which produces a complete report on large heaps. `Block` requires a .NET 11+ target runtime and can make collection slower because the target application pauses more while the GC dump is collected. On older runtimes, the tool automatically falls back to `Drop` (lossy).
+
 ### Examples
 
 - Generate a heap statistics report from a previously created `.gcdump` file:
@@ -253,7 +271,7 @@ dotnet-gcdump report [-h|--help] [-p|--process-id <pid>] [-t|--report-type <Heap
 
 - `dotnet-gcdump` is unable to generate a `.gcdump` file due to missing information, for example, **[Error] Exception during gcdump: System.ApplicationException: ETL file shows the start of a heap dump but not its completion.**. Or, the `.gcdump` file doesn't include the entire heap.
 
-   `dotnet-gcdump` works by collecting a trace of events emitted by the garbage collector during an induced generation 2 collection. If the heap is sufficiently large, or there isn't enough memory to scale the eventing buffers, then the events required to reconstruct the heap graph from the trace may be dropped. In this case, to diagnose issues with the heap, it's recommended to collect a dump of the process.
+   `dotnet-gcdump` works by collecting a trace of events emitted by the garbage collector during an induced generation 2 collection. If the heap is sufficiently large, or there isn't enough memory to scale the eventing buffers, then the events required to reconstruct the heap graph from the trace might be dropped. On a .NET 11+ target runtime, the default non-lossy `--buffering-mode Block` prevents this by blocking event producers instead of dropping events. On older runtimes, where the tool falls back to the lossy buffer, or as an alternative, collect a dump of the process to diagnose issues with the heap.
 
 - `dotnet-gcdump` appears to cause an Out Of Memory issue in a memory constrained environment.
 

docs/core/diagnostics/dotnet-trace.md

@@ -1,9 +1,10 @@
 ---
 title: dotnet-trace diagnostic tool - .NET CLI
 description: Learn how to install and use the dotnet-trace CLI tool to collect .NET traces of a running process without the native profiler, by using the .NET EventPipe.
-ms.date: 06/10/2026
+ms.date: 07/02/2026
 ms.topic: reference
 ms.custom: sfi-ropc-nochange
+ai-usage: ai-assisted
 ---
 # dotnet-trace performance analysis utility
 
@@ -85,6 +86,7 @@ Collects a diagnostic trace from a running process or launches a child process a
 
 ```dotnetcli
 dotnet-trace collect
+    [--buffering-mode <Drop|Block>]
     [--buffersize <size>]
     [--clreventlevel <clreventlevel>]
     [--clrevents <clrevents>]
@@ -108,6 +110,13 @@ dotnet-trace collect
 
 ### Options
 
+- **`--buffering-mode <Drop|Block>`**
+
+  Sets how the runtime buffers events. Accepts `0`/`Drop` or `1`/`Block` (case-insensitive), and defaults to `Drop`.
+
+  - `0` / `Drop` (default): the lossy circular buffer. Events are dropped when the buffer overflows.
+  - `1` / `Block`: non-lossy tracing. The runtime blocks the threads emitting events until the buffer drains instead of dropping events, which produces a complete trace. `Block` requires a .NET 11+ target runtime and can make the traced application slower because event-emitting threads pause while the buffer stays full. On older runtimes, starting the trace fails; retry with `Drop` (the default).
+
 - **`--buffersize <size>`**
 
   Sets the size of the in-memory buffer, in megabytes. Default 256 MB.

docs/core/diagnostics/eventpipe.md

@@ -1,8 +1,9 @@
 ---
 title: EventPipe Overview
 description: Learn about EventPipe and how to use it for tracing your .NET applications to diagnose performance issues.
-ms.date: 03/19/2026
+ms.date: 07/02/2026
 ms.topic: overview
+ai-usage: ai-assisted
 ---
 
 # EventPipe
@@ -81,6 +82,12 @@ However, you can use the following environment variables to set up an EventPipe
 
   > [!NOTE]
   > If the target process writes events too frequently, it can overflow this buffer and some events might be dropped. If too many events are getting dropped, increase the buffer size to see if the number of dropped events reduces. If the number of dropped events does not decrease with a larger buffer size, it may be due to a slow reader preventing the target process' buffers from being flushed.
+  >
+  > As of .NET 11, a streaming session can opt into non-lossy buffering with `DOTNET_EventPipeBufferingMode=1` (or `--buffering-mode Block` in [dotnet-trace](./dotnet-trace.md)) to block the threads emitting events instead of dropping them. Non-lossy buffering trades application throughput for completeness.
+
+* `DOTNET_EventPipeBufferingMode`: Available in .NET 11 and later. Controls how the startup EventPipe session's buffer behaves when it fills faster than it's drained. Set it to `0` (default) for the lossy circular buffer that drops events on overflow, or `1` for non-lossy (Block) buffering, which pauses the threads that emit events until the buffer drains so that no events are dropped. Any other value falls back to `0`. This setting applies only to a streaming session (see `DOTNET_EventPipeOutputStreaming`); it's ignored for non-streaming file sessions.
+
+* `DOTNET_EventPipeOutputStreaming`: Set this to `1` to stream the startup EventPipe session's events continuously instead of buffering them and writing at process exit. A streaming session is required for `DOTNET_EventPipeBufferingMode=1` (non-lossy) to take effect.
 
 * `DOTNET_EventPipeProcNumbers`: Set this to `1` to enable capturing processor numbers in EventPipe event headers. The default value is `0`.
 

docs/core/diagnostics/microsoft-diagnostics-netcore-client.md

@@ -1,10 +1,11 @@
 ---
 title: Microsoft.Diagnostics.NETCore.Client API
 description: In this article, you'll learn about the Microsoft.Diagnostics.NETCore.Client APIs.
-ms.date: 12/08/2025
+ms.date: 07/02/2026
 author: tommcdon
 ms.author: tommcdon
 ms.topic: reference
+ai-usage: ai-assisted
 ---
 
 # Microsoft.Diagnostics.NETCore.Client API
@@ -343,6 +344,13 @@ public sealed class EventPipeSessionConfiguration
         long rundownKeyword,
         bool requestStackwalk = true);
 
+    public EventPipeSessionConfiguration(
+        IEnumerable<EventPipeProvider> providers,
+        int circularBufferSizeMB,
+        long rundownKeyword,
+        bool requestStackwalk,
+        EventPipeBufferingMode bufferingMode);
+
     public bool RequestRundown { get; }
 
     public int CircularBufferSizeInMB { get; }
@@ -351,6 +359,8 @@ public sealed class EventPipeSessionConfiguration
 
     public long RundownKeyword { get; }
 
+    public EventPipeBufferingMode BufferingMode { get; }
+
     public IReadOnlyCollection<EventPipeProvider> Providers { get; }
 }
 ```
@@ -362,6 +372,9 @@ Represents the configuration for an `EventPipeSession`.
 * `requestRundown` : If `true`, request rundown events from the runtime.
 * `requestStackwalk` : If `true`, record a stack trace for every emitted event.
 * `rundownKeyword` : The keyword mask used for rundown events.
+* `bufferingMode` : The [`EventPipeBufferingMode`](#eventpipebufferingmode-enum) for the session. Use `Block` to request non-lossy collection. Passing `Block` requires a .NET 11+ target runtime; on an older runtime, `StartEventPipeSession` throws [`UnknownCommandException`](#unknowncommandexception).
+
+The `BufferingMode` property returns the buffering mode for the session. The default value, `Drop`, keeps the runtime's lossy circular buffer.
 
 ## EventPipeProvider class
 
@@ -374,6 +387,13 @@ public class EventPipeProvider
         long keywords = 0,
         IDictionary<string, string> arguments = null)
 
+    public EventPipeProvider(
+        string name,
+        EventLevel eventLevel,
+        long keywords,
+        IDictionary<string, string> arguments,
+        EventPipeProviderEventFilter eventFilter)
+
     public string Name { get; }
 
     public EventLevel EventLevel { get; }
@@ -382,6 +402,8 @@ public class EventPipeProvider
 
     public IDictionary<string, string> Arguments { get; }
 
+    public EventPipeProviderEventFilter EventFilter { get; }
+
     public override string ToString();
 
     public override bool Equals(object obj);
@@ -402,9 +424,16 @@ public EventPipeProvider(
     EventLevel eventLevel,
     long keywords = 0,
     IDictionary<string, string> arguments = null)
+
+public EventPipeProvider(
+    string name,
+    EventLevel eventLevel,
+    long keywords,
+    IDictionary<string, string> arguments,
+    EventPipeProviderEventFilter eventFilter)
 ```
 
-Creates a new instance of `EventPipeProvider` with the given provider name, <xref:System.Diagnostics.Tracing.EventLevel>, keywords, and arguments.
+Creates a new instance of `EventPipeProvider` with the given provider name, <xref:System.Diagnostics.Tracing.EventLevel>, keywords, and arguments. The second overload also takes an [`EventPipeProviderEventFilter`](#eventpipeprovidereventfilter-class) that filters which Event IDs the runtime enables for the provider. When you set an event filter, the session requires a .NET 10+ target runtime.
 
 ### Name property
 
@@ -438,10 +467,64 @@ public IDictionary<string, string> Arguments { get; }
 
 Gets an `IDictionary` of key-value pair strings representing optional arguments to be passed to `EventSource` representing the given `EventPipeProvider`.
 
+### EventFilter property
+
+```csharp
+public EventPipeProviderEventFilter EventFilter { get; }
+```
+
+Gets the optional [`EventPipeProviderEventFilter`](#eventpipeprovidereventfilter-class) that the runtime applies to this provider's Event IDs after the keyword and level filter. When the value is `null`, the runtime enables every Event ID that the keyword and level filter allows.
+
 ### Remarks
 
 This class is immutable, because EventPipe does not allow a provider's configuration to be modified during an EventPipe session as of .NET Core 3.1.
 
+## EventPipeProviderEventFilter class
+
+```csharp
+public sealed class EventPipeProviderEventFilter
+{
+    public EventPipeProviderEventFilter(
+        bool enable,
+        IReadOnlyList<uint> eventIds);
+
+    public bool Enable { get; }
+
+    public IReadOnlyList<uint> EventIds { get; }
+}
+```
+
+Represents an optional per-provider filter on Event IDs. The runtime applies the filter after the keyword and level filter of the associated [`EventPipeProvider`](#eventpipeprovider-class). Event filters require a .NET 10+ target runtime.
+
+### Constructor
+
+```csharp
+public EventPipeProviderEventFilter(
+    bool enable,
+    IReadOnlyList<uint> eventIds);
+```
+
+Creates a new instance of `EventPipeProviderEventFilter`.
+
+* `enable` : If `true`, `eventIds` is an allow-list and the runtime enables only those Event IDs. If `false`, `eventIds` is a deny-list and the runtime enables every Event ID except those listed. An empty deny-list therefore enables all events.
+* `eventIds` : The Event IDs to enable or disable, as determined by `enable`.
+
+### Enable property
+
+```csharp
+public bool Enable { get; }
+```
+
+Gets a value that indicates whether [`EventIds`](#eventids-property) is an allow-list (`true`) or a deny-list (`false`).
+
+### EventIds property
+
+```csharp
+public IReadOnlyList<uint> EventIds { get; }
+```
+
+Gets the list of Event IDs that the filter enables or disables.
+
 ## EventPipeSession class
 
 ```csharp
@@ -576,6 +659,21 @@ Represents the type of perf map behavior that can be enabled.
 * `JitDump` : Enable JIT dump perf map output.
 * `PerfMap` : Enable traditional perf map output.
 
+## EventPipeBufferingMode enum
+
+```csharp
+public enum EventPipeBufferingMode
+{
+    Drop = 0,
+    Block = 1
+}
+```
+
+Controls how the runtime's per-session event buffer behaves when it fills faster than the session drains it.
+
+* `Drop` : The runtime default. The session uses a circular buffer that drops events when it overflows, so collection is lossy.
+* `Block` : Non-lossy collection. The runtime blocks event producers until the reader frees buffer capacity instead of dropping events. Use it for collections that must be complete, such as a heap snapshot on a large heap. `Block` requires a .NET 11+ target runtime; on an older runtime, starting the session throws [`UnknownCommandException`](#unknowncommandexception).
+
 ## Exceptions
 
 Exceptions that are thrown from the library are of type `DiagnosticsClientException` or a derived type.
@@ -592,6 +690,22 @@ public class UnsupportedCommandException : DiagnosticsClientException
 
 This may be thrown when the command is not supported by either the library or the target process's runtime.
 
+### UnknownCommandException
+
+```csharp
+public class UnknownCommandException : UnsupportedCommandException
+```
+
+This is thrown when the target runtime doesn't recognize the requested command, typically because the runtime is too old to support it. For example, `StartEventPipeSession` throws it when you request [`EventPipeBufferingMode.Block`](#eventpipebufferingmode-enum) on a runtime older than .NET 11. Because it derives from `UnsupportedCommandException`, an existing `catch (UnsupportedCommandException)` still catches it.
+
+### InvalidCommandArgumentException
+
+```csharp
+public class InvalidCommandArgumentException : UnsupportedCommandException
+```
+
+This is thrown when the target runtime recognizes the command but rejects its payload argument.
+
 ### UnsupportedProtocolException
 
 ```csharp