EventPipeProfiler documentation (#1418)

* EventPipeProfiler documentation

* Update url to blog post.

* Fix review

Author: WojciechNagorski

docs/articles/configs/diagnosers.md

@@ -33,6 +33,9 @@ The current Diagnosers are:
 - Native Memory Profiler (`NativeMemoryProfiler`)
   It uses `EtwProfiler` to profile the code using ETW and adds the extra columns `Allocated native memory` and `Native memory leak`.
   Please see Wojciech Nagórski's [blog post](https://wojciechnagorski.com/2019/08/analyzing-native-memory-allocation-with-benchmarkdotnet/) for all the details.
+- Event Pipe Profiler (`EventPipeProfiler`).
+  It is a cross-platform profiler that allows profile .NET code on every platform - Windows, Linux, macOS.
+  Please see Wojciech Nagórski's [blog post](https://wojciechnagorski.com/2020/04/cross-platform-profiling-.net-code-with-benchmarkdotnet/) for all the details.
 - Threading Diagnoser (`ThreadingDiagnoser`) - .NET Core 3.0+ diagnoser that reports some Threading statistics.
 
 ## Usage

docs/articles/features/event-pipe-profiler.md

@@ -0,0 +1,21 @@
+---
+uid: docs.event-pipe-profiler
+name: EventPipeProfiler
+---
+
+# EventPipeProfiler
+
+`EventPipeProfiler` is a cross-platform profiler that allows profile .NET code on every platform - Windows, Linux, macOS. Collected data are exported to trace files (`.speedscope.json` and `.nettrace`) which can be analyzed using [SpeedScope](https://www.speedscope.app/), [PerfView](https://github.com/Microsoft/perfview), and [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer). This new profiler is available from the 0.12.1 version.
+
+![](https://wojciechnagorski.com/images/EventPipeProfiler/SpeedScopeAdvance.png)
+
+# Configuration
+
+`EventPipeProfiler` can be enabled in three ways:
+
+1. Using parameter `-p EP` or `--profiler EP` from the console line.
+2. Marking the benchmarked class with `[EventPipeProfiler(...)]` attribute. You can find an example below.
+3. Using a custom configuration. You can find an example below.
+
+[!include[IntroEventPipeProfiler](../samples/IntroEventPipeProfiler.md)]
+[!include[IntroEventPipeProfilerAdvanced](../samples/IntroEventPipeProfilerAdvanced.md)]

docs/articles/features/toc.yml

@@ -9,4 +9,6 @@
 - name: Disassembler
   href: disassembler.md
 - name: EtwProfiler
-  href: etwprofiler.md
+  href: etwprofiler.md
+- name: EventPipeProfiler
+  href: event-pipe-profiler.md

docs/articles/samples/IntroEventPipeProfiler.md

@@ -0,0 +1,25 @@
+---
+uid: BenchmarkDotNet.Samples.IntroEventPipeProfiler
+---
+
+## Sample: EventPipeProfiler
+
+The `EventPipeProfiler` can be enabled using the `[EventPipeProfiler(...)]` attribute. This attribute takes the following profiles:
+ - `CpuSampling` - Useful for tracking CPU usage and general .NET runtime information. This is the default option.
+ - `GcVerbose` - Tracks GC collections and samples object allocations.
+ - `GcCollect` - Tracks GC collections only at very low overhead.
+ - `Jit` - Logging when Just in time (JIT) compilation occurs. Logging of the internal workings of the Just In Time compiler. This is fairly verbose. It details decisions about interesting optimization (like inlining and tail call)
+
+### Source code
+
+[!code-csharp[EventPipeProfiler.cs](../../../samples/BenchmarkDotNet.Samples/IntroEventPipeProfiler.cs)]
+
+### Output
+
+The output should contain information about the exported trace file which can be analyzed using [SpeedScope](https://www.speedscope.app/).
+
+```markdown
+// * Diagnostic Output - EventPipeProfiler *
+Exported 1 trace file(s). Example:
+C:\Work\BenchmarkDotNet\samples\BenchmarkDotNet.Samples\BenchmarkDotNet.Artifacts\BenchmarkDotNet.Samples.IntroEventPipeProfiler.Sleep-20200406-090113.speedscope.json
+```

docs/articles/samples/IntroEventPipeProfilerAdvanced.md

@@ -0,0 +1,22 @@
+---
+uid: BenchmarkDotNet.Samples.IntroEventPipeProfilerAdvanced
+---
+
+## Sample: EventPipeProfilerAdvanced
+
+The most advanced and powerful way to use `EventPipeProfiler` is a custom configuration. As you can see the below configuration adds `EventPipeProfiler` that constructor can take the profile and/or a list of providers. 
+Both `EventPipeProfiler` and `dotnet trace` use the `Microsoft.Diagnostics.NETCore.Client` package internally. So before you start using the custom configuration of this profiler, it is worth reading the documentation [here](https://github.com/dotnet/diagnostics/blob/master/documentation/dotnet-trace-instructions.md) and [here](https://docs.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace#dotnet-trace-collect) where you can fine more information about how to configure provider list.
+
+### Source code
+
+[!code-csharp[EventPipeProfilerAdvanced.cs](../../../samples/BenchmarkDotNet.Samples/IntroEventPipeProfilerAdvanced.cs)]
+
+### Output
+
+The output should contain information about the exported trace file which can be analyzed using [SpeedScope](https://www.speedscope.app/).
+
+```markdown
+// * Diagnostic Output - EventPipeProfiler *
+Exported 1 trace file(s). Example:
+C:\Work\BenchmarkDotNet\samples\BenchmarkDotNet.Samples\BenchmarkDotNet.Artifacts\BenchmarkDotNet.Samples.IntroEventPipeProfilerAdvanced.RentAndReturn_Shared-20200406-090136.speedscope.json
+```

docs/articles/samples/toc.yml

@@ -34,6 +34,10 @@
   href: IntroDisassemblyRyuJit.md
 - name: IntroEnvVars
   href: IntroEnvVars.md
+- name: IntroEventPipeProfiler
+  href: IntroEventPipeProfiler.md
+- name: IntroEventPipeProfilerAdvanced
+  href: IntroEventPipeProfilerAdvanced.md
 - name: IntroExport
   href: IntroExport.md
 - name: IntroExportJson