Issue #1736: Add ExceptionDiagnoser (#2169)

Co-authored-by: Adam Sitnik <[email protected]>

Author: Serg046

docs/articles/configs/diagnosers.md

@@ -37,6 +37,7 @@ The current Diagnosers are:
   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.
+- Exception Diagnoser (`ExceptionDiagnoser`) - a diagnoser that reports the frequency of exceptions thrown during the operation.
 
 ## Usage
 
@@ -59,6 +60,7 @@ private class Config : ManualConfig
         Add(new InliningDiagnoser());
         Add(new EtwProfiler());
         Add(ThreadingDiagnoser.Default);
+        Add(ExceptionDiagnoser.Default);
     }
 }
 ```
@@ -72,6 +74,7 @@ You can also use one of the following attributes (apply it on a class that conta
 [ConcurrencyVisualizerProfiler]
 [NativeMemoryProfiler]
 [ThreadingDiagnoser]
+[ExceptionDiagnoser]
 ```
 
 In BenchmarkDotNet, 1kB = 1024B, 1MB = 1024kB, and so on. The column Gen X means number of GC collections per 1000 operations for that generation.
@@ -123,3 +126,5 @@ In BenchmarkDotNet, 1kB = 1024B, 1MB = 1024kB, and so on. The column Gen X means
 [!include[IntroNativeMemory](../samples/IntroNativeMemory.md)]
 
 [!include[IntroThreadingDiagnoser](../samples/IntroThreadingDiagnoser.md)]
+
+[!include[IntroExceptionDiagnoser](../samples/IntroExceptionDiagnoser.md)]

docs/articles/samples/IntroExceptionDiagnoser.md

@@ -0,0 +1,26 @@
+---
+uid: BenchmarkDotNet.Samples.IntroExceptionDiagnoser
+---
+
+## Sample: IntroExceptionDiagnoser
+
+The `ExceptionDiagnoser` uses [AppDomain.FirstChanceException](https://learn.microsoft.com/en-us/dotnet/api/system.appdomain.firstchanceexception) API to report:
+
+* Exception frequency: The number of exceptions thrown during the operations divided by the number of operations.
+
+### Source code
+
+[!code-csharp[IntroExceptionDiagnoser.cs](../../../samples/BenchmarkDotNet.Samples/IntroExceptionDiagnoser.cs)]
+
+### Output
+
+|                 Method |     Mean |     Error |    StdDev | Exception frequency |
+|----------------------- |---------:|----------:|----------:|--------------------:|
+| ThrowExceptionRandomly | 4.936 us | 0.1542 us | 0.4499 us |              0.1381 |
+
+### Links
+
+* @docs.diagnosers
+* The permanent link to this sample: @BenchmarkDotNet.Samples.IntroExceptionDiagnoser
+
+---

samples/BenchmarkDotNet.Samples/IntroExceptionDiagnoser.cs

@@ -0,0 +1,22 @@
+using BenchmarkDotNet.Attributes;
+using System;
+
+namespace BenchmarkDotNet.Samples
+{
+    [ExceptionDiagnoser]
+    public class IntroExceptionDiagnoser
+    {
+        [Benchmark]
+        public void ThrowExceptionRandomly()
+        {
+            try
+            {
+                if (new Random().Next(0, 5) > 1)
+                {
+                    throw new Exception();
+                }
+            }
+            catch { }
+        }
+    }
+}

src/BenchmarkDotNet/Attributes/ExceptionDiagnoserAttribute.cs

@@ -0,0 +1,14 @@
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Diagnosers;
+using System;
+
+namespace BenchmarkDotNet.Attributes
+{
+    [AttributeUsage(AttributeTargets.Class)]
+    public class ExceptionDiagnoserAttribute : Attribute, IConfigSource
+    {
+        public IConfig Config { get; }
+
+        public ExceptionDiagnoserAttribute() => Config = ManualConfig.CreateEmpty().AddDiagnoser(ExceptionDiagnoser.Default);
+    }
+}

src/BenchmarkDotNet/Columns/Column.cs

@@ -55,6 +55,7 @@ public static class Column
         public const string CompletedWorkItems = "Completed Work Items";
         public const string LockContentions = "Lock Contentions";
         public const string CodeSize = "Code Size";
+        public const string Exceptions = "Exceptions";
 
         //Characteristics:
         public const string Id = "Id";

src/BenchmarkDotNet/Configs/ImmutableConfig.cs

@@ -106,9 +106,11 @@ internal ImmutableConfig(
 
         public bool HasThreadingDiagnoser() => diagnosers.Contains(ThreadingDiagnoser.Default);
 
+        public bool HasExceptionDiagnoser() => diagnosers.Contains(ExceptionDiagnoser.Default);
+
         internal bool HasPerfCollectProfiler() => diagnosers.OfType<PerfCollectProfiler>().Any();
 
-        public bool HasExtraStatsDiagnoser() => HasMemoryDiagnoser() || HasThreadingDiagnoser();
+        public bool HasExtraStatsDiagnoser() => HasMemoryDiagnoser() || HasThreadingDiagnoser() || HasExceptionDiagnoser();
 
         public IDiagnoser GetCompositeDiagnoser(BenchmarkCase benchmarkCase, RunMode runMode)
         {

src/BenchmarkDotNet/ConsoleArguments/CommandLineOptions.cs

@@ -37,6 +37,9 @@ public class CommandLineOptions
         [Option('t', "threading", Required = false, Default = false, HelpText = "Prints threading statistics")]
         public bool UseThreadingDiagnoser { get; set; }
 
+        [Option("exceptions", Required = false, Default = false, HelpText = "Prints exception statistics")]
+        public bool UseExceptionDiagnoser { get; set; }
+
         [Option('d', "disasm", Required = false, Default = false, HelpText = "Gets disassembly of benchmarked code")]
         public bool UseDisassemblyDiagnoser
         {

src/BenchmarkDotNet/ConsoleArguments/ConfigParser.cs

@@ -213,6 +213,8 @@ private static IConfig CreateConfig(CommandLineOptions options, IConfig globalCo
                 config.AddDiagnoser(MemoryDiagnoser.Default);
             if (options.UseThreadingDiagnoser)
                 config.AddDiagnoser(ThreadingDiagnoser.Default);
+            if (options.UseExceptionDiagnoser)
+                config.AddDiagnoser(ExceptionDiagnoser.Default);
             if (options.UseDisassemblyDiagnoser)
                 config.AddDiagnoser(new DisassemblyDiagnoser(new DisassemblyDiagnoserConfig(
                     maxDepth: options.DisassemblerRecursiveDepth,

src/BenchmarkDotNet/Diagnosers/DiagnoserResults.cs

@@ -15,6 +15,7 @@ public DiagnoserResults(BenchmarkCase benchmarkCase, ExecuteResult executeResult
             GcStats = executeResult.GcStats;
             ThreadingStats = executeResult.ThreadingStats;
             BuildResult = buildResult;
+            ExceptionFrequency = executeResult.ExceptionFrequency;
         }
 
         public BenchmarkCase BenchmarkCase { get; }
@@ -25,6 +26,8 @@ public DiagnoserResults(BenchmarkCase benchmarkCase, ExecuteResult executeResult
 
         public ThreadingStats ThreadingStats { get; }
 
+        public double ExceptionFrequency { get; }
+
         public BuildResult BuildResult { get; }
     }
 }

src/BenchmarkDotNet/Diagnosers/ExceptionDiagnoser.cs

@@ -0,0 +1,54 @@
+using BenchmarkDotNet.Analysers;
+using BenchmarkDotNet.Columns;
+using BenchmarkDotNet.Engines;
+using BenchmarkDotNet.Exporters;
+using BenchmarkDotNet.Loggers;
+using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
+using BenchmarkDotNet.Validators;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace BenchmarkDotNet.Diagnosers
+{
+    public class ExceptionDiagnoser : IDiagnoser
+    {
+        public static readonly ExceptionDiagnoser Default = new ExceptionDiagnoser();
+
+        private ExceptionDiagnoser() { }
+
+        public IEnumerable<string> Ids => new[] { nameof(ExceptionDiagnoser) };
+
+        public IEnumerable<IExporter> Exporters => Array.Empty<IExporter>();
+
+        public IEnumerable<IAnalyser> Analysers => Array.Empty<IAnalyser>();
+
+        public void DisplayResults(ILogger logger) { }
+
+        public RunMode GetRunMode(BenchmarkCase benchmarkCase) => RunMode.NoOverhead;
+
+        public void Handle(HostSignal signal, DiagnoserActionParameters parameters) { }
+
+        public IEnumerable<Metric> ProcessResults(DiagnoserResults results)
+        {
+            yield return new Metric(ExceptionsFrequencyMetricDescriptor.Instance, results.ExceptionFrequency);
+        }
+
+        public IEnumerable<ValidationError> Validate(ValidationParameters validationParameters) => Enumerable.Empty<ValidationError>();
+
+        private class ExceptionsFrequencyMetricDescriptor : IMetricDescriptor
+        {
+            internal static readonly IMetricDescriptor Instance = new ExceptionsFrequencyMetricDescriptor();
+
+            public string Id => "ExceptionFrequency";
+            public string DisplayName => Column.Exceptions;
+            public string Legend => "Exceptions thrown per single operation";
+            public string NumberFormat => "#0.0000";
+            public UnitType UnitType => UnitType.Dimensionless;
+            public string Unit => "Count";
+            public bool TheGreaterTheBetter => false;
+            public int PriorityInCategory => 0;
+        }
+    }
+}