EventPipe is a runtime component that can be used to collect tracing data, similar to ETW or LTTng. The goal of EventPipe is to allow .NET developers to easily trace their .NET applications without having to rely on platform-specific OS-native components such as ETW or LTTng.
EventPipe is the mechanism behind many of the diagnostic tools and can be used for consuming events emitted by the runtime as well as custom events written with EventSource.
This article is a high-level overview of EventPipe describing when and how to use EventPipe, and how to configure it to best suit your needs.
EventPipe aggregates events emitted by runtime components - for example, the Just-In-Time compiler or the garbage collector - and events written from EventSource instances in the libraries and user code.
The events are then serialized and can be written directly to a file or consumed through a Diagnostics Port from out-of-proces. On Windows, Diagnostic Ports are implemented as
NamedPipes. On non-Windows platforms, such as Linux or macOS, it is implemented using Unix Domain Sockets. For more information about the Diagnostics Port and how to interact with it via its custom inter-process communication protocol, see the diagnostics IPC protocol documentation.
EventPipe then writes the serialized events in the
.nettrace file format, either as a stream via Diagnostic Ports or directly to a file. To learn more about the EventPipe serialization format, refer to the EventPipe format documentation.
EventPipe vs. ETW/LTTng
EventPipe is part of the .NET runtime (CoreCLR) and is designed to work the same way across all the platforms .NET Core supports. This allows tracing tools based on EventPipe, such as
dotnet-trace, to work seamlessly across platforms.
However, because EventPipe is a runtime built-in component, its scope is limited to managed code and the runtime itself. EventPipe cannot be used for tracking some lower-level events, such as resolving native code stack or getting various kernel events. If you use C/C++ interop in your app or you want to trace the runtime itself (which is written in C++), or want deeper diagnostics into the behavior of the app that requires kernel events (that is, native-thread context-switching events) you should use ETW or perf/LTTng.
Another major difference between EventPipe and ETW/LTTng is admin/root privilege requirement. To trace an application using ETW or LTTng you need to be an admin/root. Using EventPipe, you can trace applications as long as the tracer (for example,
dotnet-trace) is run as the same user as the user that launched the application.
The following table is a summary of the differences between EventPipe and ETW/LTTng.
|Cross-platform||Yes||No (only on Windows)||No (only on supported Linux distros)|
|Require admin/root privilege||No||Yes||Yes|
|Can get OS/kernel events||No||Yes||Yes|
|Can resolve native callstacks||No||Yes||Yes|
Use EventPipe to trace your .NET application
You can use EventPipe to trace your .NET application in many ways:
Use one of the diagnostics tools that are built on top of EventPipe.
Use Microsoft.Diagnostics.NETCore.Client library to write your own tool to configure and start EventPipe sessions yourself.
Use environment variables to start EventPipe.
After you've produced a
nettrace file that contains your EventPipe events, you can view the file in
PerfView or Visual Studio. On non-Windows platforms, you can convert the
nettrace file to a
Chromium trace format by using
dotnet-trace convert command and view it with
speedscope or Chrome DevTools.
You can also analyze EventPipe traces programmatically with TraceEvent.
Tools that use EventPipe
This is the easiest way to use EventPipe to trace your application. To learn more about how to use each of these tools, refer to each tool's documentation.
dotnet-counters lets you monitor and collect various metrics emitted by the .NET runtime and core libraries, as well as custom metrics you can write.
dotnet-gcdump lets you collect GC heap dumps of live processes for analyzing an application's managed heap.
dotnet-trace lets you collect traces of applications to analyze for performance.
Trace using environment variables
The preferred mechanism for using EventPipe is to use
dotnet-trace or the
However, you can use the following environment variables to set up an EventPipe session on an app and have it write the trace directly to a file. To stop tracing, exit the application.
COMPlus_EnableEventPipe: Set this to
1to start an EventPipe session that writes directly to a file. The default value is
COMPlus_EventPipeOutputPath: The path to the output EventPipe trace file when it's configured to run via
COMPlus_EnableEventPipe. The default value is
trace.nettrace, which will be created in the same directory that the app is running from.
COMPlus_CircularBufferMB: The size of the internal buffer that is used by EventPipe when it's configured to run via
COMPlus_EventPipeConfig: Sets up the EventPipe session configuration when starting an EventPipe session with
The syntax is as follows:
You can also specify multiple providers by concatenating them with a comma:
If this environment variable is not set but EventPipe is enabled by
COMPlus_EnableEventPipe, it will start tracing by enabling the following providers with the following keywords and levels:
To learn more about some of the well-known providers in .NET, refer to Well-known Event Providers.