diff --git a/docs/core/diagnostics/dotnet-gcdump.md b/docs/core/diagnostics/dotnet-gcdump.md index 1cdf928238476..2fd291959cd36 100644 --- a/docs/core/diagnostics/dotnet-gcdump.md +++ b/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: 08/24/2026 ms.topic: reference +ai-usage: ai-assisted --- # Heap analysis tool (dotnet-gcdump) @@ -253,7 +254,7 @@ dotnet-gcdump report [-h|--help] [-p|--process-id ] [-t|--report-type ] [--buffersize ] [--clreventlevel ] [--clrevents ] @@ -108,6 +110,13 @@ dotnet-trace collect ### Options +- **`--buffering-mode `** + + Sets how the runtime buffers events. Accepts `Drop` or `Block` (case-insensitive), and defaults to `Drop`. + + - `Drop` (default): Events are dropped when the buffer overflows. + - `Block`: Threads emitting events wait until there is room in the buffer to store them. Events may still be dropped under uncommon error conditions such as memory exhaustion. `Block` requires a .NET 11+ target runtime and can make the traced application slower because event-emitting threads pause while the buffer stays full. + - **`--buffersize `** Sets the size of the in-memory buffer, in megabytes. Default 256 MB. @@ -290,9 +299,6 @@ dotnet-trace collect ## dotnet-trace collect-linux -> [!NOTE] -> The `collect-linux` verb is a new preview feature and relies on an updated version of the .nettrace file format. The latest PerfView release supports these trace files, but other ways of using the trace file, such as [`convert`](#dotnet-trace-convert) and [`report`](#dotnet-trace-report), might not work yet. - Collects diagnostic traces using perf_events, a Linux OS technology. `collect-linux` enables the following additional features over [`collect`](#dotnet-trace-collect). | Feature | `collect` | `collect-linux` | @@ -731,12 +737,6 @@ This example captures CPU samples for all processes on the machine. Any processe ```output $ sudo dotnet-trace collect-linux - ========================================================================================== - The collect-linux verb is a new preview feature and relies on an updated version of the - .nettrace file format. The latest PerfView release supports these trace files but other - ways of using the trace file may not work yet. For more details, see the docs at - https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace. - ========================================================================================== No providers, profiles, ClrEvents, or PerfEvents were specified, defaulting to trace profiles 'dotnet-common' + 'cpu-sampling'. Provider Name Keywords Level Enabled By @@ -760,12 +760,6 @@ For environments with multiple .NET versions installed, running `collect-linux` ```output $ dotnet-trace collect-linux --probe - ========================================================================================== - The collect-linux verb is a new preview feature and relies on an updated version of the - .nettrace file format. The latest PerfView release supports these trace files but other - ways of using the trace file may not work yet. For more details, see the docs at - https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace. - ========================================================================================== Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later. .NET processes that support the command: 3802935 MyApp diff --git a/docs/core/diagnostics/eventpipe.md b/docs/core/diagnostics/eventpipe.md index 7e4b8ce8434c2..deb0f8c504a37 100644 --- a/docs/core/diagnostics/eventpipe.md +++ b/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: 08/24/2026 ms.topic: overview +ai-usage: ai-assisted --- # EventPipe @@ -80,7 +81,11 @@ However, you can use the following environment variables to set up an EventPipe * `DOTNET_EventPipeCircularMB`: A hexadecimal value that represents the size of EventPipe's internal buffer in megabytes. This configuration value is only used when EventPipe is configured to run via `DOTNET_EnableEventPipe`. The default buffer size is 1024MB which translates to this environment variable being set to `400`, since `0x400` == `1024`. > [!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. + > If the target process writes events too frequently, it can overflow this buffer, and some events might be dropped. If the runtime drops too many events, set `DOTNET_EventPipeBufferingMode=1` or increase the buffer size to see if the number of dropped events decreases. If the number of dropped events does not decrease with a larger buffer size, a slow reader might prevent the target process's buffers from being flushed. + +* `DOTNET_EventPipeBufferingMode`: Available in .NET 11 and later. This setting controls how the startup EventPipe session handles recording an event when the in-memory buffer is full. Set it to `0` (default) to drop events that would overflow the buffer, or `1` to pause event-writing threads until buffer space becomes available. `1` requires a streaming session (see `DOTNET_EventPipeOutputStreaming`). + +* `DOTNET_EventPipeOutputStreaming`: Set this to `1` to stream the startup EventPipe session's events to disk as quickly as possible after they occur. By default, events are stored in memory and not written to disk until the application is exiting. A streaming session is required for `DOTNET_EventPipeBufferingMode=1` to take effect. * `DOTNET_EventPipeProcNumbers`: Set this to `1` to enable capturing processor numbers in EventPipe event headers. The default value is `0`. diff --git a/docs/core/diagnostics/microsoft-diagnostics-netcore-client.md b/docs/core/diagnostics/microsoft-diagnostics-netcore-client.md index 01c03a8f71f60..4e47836ccd378 100644 --- a/docs/core/diagnostics/microsoft-diagnostics-netcore-client.md +++ b/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: 08/24/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 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 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 [`UnsupportedCommandException`](#unsupportedcommandexception). + +The `BufferingMode` property returns the buffering mode for the session. The default value, `Drop`, keeps the runtime's lossy buffer. ## EventPipeProvider class @@ -374,6 +387,13 @@ public class EventPipeProvider long keywords = 0, IDictionary arguments = null) + public EventPipeProvider( + string name, + EventLevel eventLevel, + long keywords, + IDictionary arguments, + EventPipeProviderEventFilter eventFilter) + public string Name { get; } public EventLevel EventLevel { get; } @@ -382,6 +402,8 @@ public class EventPipeProvider public IDictionary 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 arguments = null) + +public EventPipeProvider( + string name, + EventLevel eventLevel, + long keywords, + IDictionary arguments, + EventPipeProviderEventFilter eventFilter) ``` -Creates a new instance of `EventPipeProvider` with the given provider name, , keywords, and arguments. +Creates a new instance of `EventPipeProvider` with the given provider name, , 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 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 eventIds); + + public bool Enable { get; } + + public IReadOnlyList 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 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 EventIds { get; } +``` + +Gets the list of Event IDs that the filter enables or disables. + ## EventPipeSession class ```csharp @@ -576,22 +659,29 @@ Represents the type of perf map behavior that can be enabled. * `JitDump` : Enable JIT dump perf map output. * `PerfMap` : Enable traditional perf map output. -## Exceptions - -Exceptions that are thrown from the library are of type `DiagnosticsClientException` or a derived type. +## EventPipeBufferingMode enum ```csharp -public class DiagnosticsClientException : Exception +public enum EventPipeBufferingMode +{ + Drop = 0, + Block = 1 +} ``` -### UnsupportedCommandException +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 buffer that drops events when it overflows, so collection is lossy. +* `Block` : Non-lossy collection. The runtime blocks event producers when the buffer is full instead of dropping events. Use it for collections that must be complete, such as a heap snapshot on a large heap. `Block` is non-lossy only up to the buffer's capacity, not against host memory exhaustion: if the runtime can't allocate the memory it needs to reserve buffer space, or during session shutdown, it drops the event instead of blocking. `Block` requires a .NET 11+ target runtime; on an older runtime, starting the session throws [`UnsupportedCommandException`](#unsupportedcommandexception). + +## Exceptions + +Exceptions that are thrown from the library are of type `DiagnosticsClientException` or a derived type. ```csharp -public class UnsupportedCommandException : DiagnosticsClientException +public class DiagnosticsClientException : Exception ``` -This may be thrown when the command is not supported by either the library or the target process's runtime. - ### UnsupportedProtocolException ```csharp @@ -616,6 +706,14 @@ public class ServerErrorException : DiagnosticsClientException This may be thrown when the runtime responds with an error to a given command. +### UnsupportedCommandException + +```csharp +public class UnsupportedCommandException : ServerErrorException +``` + +This exception is thrown when the command is not supported by either the library or the target process's runtime. + ### ProfilerAlreadyActiveException ```csharp @@ -623,3 +721,11 @@ public class ProfilerAlreadyActiveException : ServerErrorException ``` This exception is thrown when a profiler is already loaded into the target runtime and another attach is attempted. + +### BadEncodingException + +```csharp +public class BadEncodingException : ServerErrorException +``` + +This exception is thrown when the target runtime can't decode the command payload and rejects it. From a well-formed client, it usually means the runtime is too old to understand a newer configured option value, so it rejects the request while parsing.