Documentation for EventPipe

[brianrob]

We should have a walk through and some documentation on how to use EventPipe.

[mattwarren]

This would be useful, the whole concept of 'Event Pipes' seems like a really nice idea.

I came across them whilst research for Monitoring and Observability in the .NET Runtime (hopefully what I've written is accurate?) but it would be nice to see some more 'official' docs.

Am I right in thinking that going forward 'Event Pipes' are the cross-plat way for the Core CLR to expose Diagnostics? (i.e. is what's written in this design doc still up-to date?)

[brianrob]

@mattwarren, yes, what you've written about EventPipe is accurate. The goal is for it to be the one system that takes events and sends them to where they need to go (based on configuration). That can be platform loggers, EventListeners (it's now possible to get the runtime ETW events like GC and JIT events via EventListeners), or even a platform-agnostic file format that TraceEvent knows how to consume.

As you say above, EventPipe is the cross platform way that CoreCLR will expose diagnostics, and it works today on all platforms.

[Wraith2]

If eventpipe is the unified mechanism for Coreclr to deal with event data are EventSource and EventCounter still the suggested way to put ETW-like data into it? And if this is so is there a suggested way to do performance counters other than pulling in the windows compat nuget package?

[brianrob]

@Wraith2, yes, EventSource and EventCounter are the right ways to be a producer of event data from managed code. They are both hooked up to EventPipe.

Our belief is that the right way to implement performance counters (should you wish to create your own counters) is to use EventCounter. We are talking about doing this as as well for framework and runtime-level counters.

The Windows Compatibility Pack that you're referring to has support for Windows Performance Counters (aka perfmon), which will allow you to produce your own counters and consume any existing counters, but this is of course Windows-only, and we don't intend to have CoreCLR or any of the .NET Core platform produce data for Windows Performance Counters.

[mattwarren]

@brianrob thanks for taking a look at my post! (it's always nice to know what I've written is accurate)

[josalem]

Per some offline chatter: this work should include some updates to the EventSource documentation as this is the primary API we expect customers to be using for eventing in .NET regardless of the underlying implementation, i.e., LTTng, EventPipe, or ETW. This should include:

• current preferred patterns
• Increased detail on use cases of and differences between the various ctors on EventSource
• Discussion on the differences between the various types of EventSources, e.g., Self Describing vs TraceLogging, etc.
• Centralizing documentation that is dispersed across the ETW docs under Windows development and the various flavors of EventSource docs under .NET
• Increased documentation on features such as custom keywords
• Clarification on differences between consumption channels, i.e., nuget package, BCL, redist nuget package

If I have missed any points here, please feel free to add more bullet points or contest what I have here 😃 .

CC - @sywhang @tommcdon @noahfalk @brianrob

[sywhang]

dotnet/docs#21515 added the documentation on EventPipe.

@josalem has some really good suggestions on things that need to be added, but since the original issue is on EventPipe I will close this one and move the suggestions from @josalem to #515.