EventPipe

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 basics

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-counters, dotnet-gcdump, and 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.

Feature EventPipe 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:

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 speedscope or 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 Microsoft.Diagnostics.NETCore.Client library.

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 1 to start an EventPipe session that writes directly to a file. The default value is 0.

  • 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_EnableEventPipe.

  • COMPlus_EventPipeConfig: Sets up the EventPipe session configuration when starting an EventPipe session with COMPlus_EnableEventPipe.

    The syntax is as follows:

    <provider>:<keyword>:<level>

    You can also specify multiple providers by concatenating them with a comma:

    <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

    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:

    • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
    • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
    • Microsoft-DotNETCore-SampleProfiler:0:5

    To learn more about some of the well-known providers in .NET, refer to Well-known Event Providers.