Add profiling examples and README snippets

Author: rogeralsing

README.md

@@ -166,6 +166,104 @@ Outputs are written to `profile-output/` in the current working directory.
 - `--input <path>` render existing `nettrace`, `speedscope.json`, `etlx`, or `gcdump` files
 - `--tfm <tfm>` target framework when profiling a `.csproj` or `.sln`
 
+## Profiler flags
+
+### --cpu
+Sampled CPU profiling with a call tree and top‑function table.
+Use this to find the hottest methods by time.
+
+Example (examples/cpu):
+```bash
+dotnet build -c Release examples/cpu/CpuDemo.csproj
+asynkron-profiler --cpu -- ./examples/cpu/bin/Release/net10.0/CpuDemo
+```
+
+Sample output (top of call tree):
+```
+Call Tree (Total Time)
+327.41 ms 100.0% 1x Total
+└─ 299.66 ms 91.5% 1x Program.Main
+   └─ 298.22 ms 91.1% 1x Program.RunWork
+      └─ 281.02 ms 85.8% 1x Program.CpuWork
+         └─ 276.10 ms 84.3% 3x Program.Fib
+```
+
+### --memory
+Allocation profiling using GC allocation tick events, plus a per‑type call tree.
+Use this to find the biggest allocation sources.
+
+Example (examples/memory):
+```bash
+dotnet build -c Release examples/memory/MemoryDemo.csproj
+asynkron-profiler --memory -- ./examples/memory/bin/Release/net10.0/MemoryDemo
+```
+
+Sample output (top of call tree):
+```
+Allocation Call Tree (Sampled)
+Byte[] (20.06 MB, 69.4%, 198x)
+20.06 MB 100.0% 198x Byte[]
+└─ 19.95 MB 99.5% 197x Program.Main lambda
+```
+
+### --exception
+Exception profiling with thrown counts, throw‑site call tree, and optional catch‑site table/tree.
+Use `--exception-type` to focus on a specific exception.
+
+Example (examples/exception):
+```bash
+dotnet build -c Release examples/exception/ExceptionDemo.csproj
+asynkron-profiler --exception --exception-type "InvalidOperation" -- ./examples/exception/bin/Release/net10.0/ExceptionDemo
+```
+
+Sample output (top of call tree):
+```
+Call Tree (Thrown Exceptions)
+6,667x 100.0% InvalidOperationException
+└─ 6,667x 100.0% Program.Main lambda
+   └─ 6,667x 100.0% EH.DispatchEx
+```
+
+### --contention
+Lock contention profiling with wait‑time call tree and top contended methods.
+Use this to find where threads are blocking on locks.
+
+Example (examples/contention):
+```bash
+dotnet build -c Release examples/contention/ContentionDemo.csproj
+asynkron-profiler --contention -- ./examples/contention/bin/Release/net10.0/ContentionDemo
+```
+
+Sample output (top of call tree):
+```
+Call Tree (Wait Time)
+49563.89 ms 100.0% 96x Total
+└─ 49563.89 ms 100.0% 96x Program.RunWorkers lambda
+   └─ 49563.89 ms 100.0% 96x Program.WorkWithLock
+```
+
+### --heap
+Heap snapshot using `dotnet-gcdump`, with a summary of top types.
+Use this to inspect retained memory after the run.
+
+Example (examples/heap):
+```bash
+dotnet build -c Release examples/heap/HeapDemo.csproj
+asynkron-profiler --heap -- ./examples/heap/bin/Release/net8.0/HeapDemo
+```
+
+Sample output (top types):
+```
+HEAP SNAPSHOT: HeapDemo
+14,595,494  GC Heap bytes
+50,375  GC Heap objects
+
+Object Bytes  Count  Type
+  524,312     1    System.Byte[][] (Bytes > 100K)
+   30,168     1    System.String (Bytes > 10K)
+       24  50,003  System.Byte[]
+```
+
 ## Troubleshooting
 
 - `dotnet-trace` not found: install with `dotnet tool install -g dotnet-trace` and ensure your global tool path is on `PATH`.

examples/contention/Program.cs

@@ -1,33 +1,54 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
 
-const int Seconds = 3;
-var workers = Math.Max(4, Environment.ProcessorCount * 2);
-var gate = new object();
-var start = new ManualResetEventSlim(false);
-var tasks = new List<Task>(workers);
-
-for (var i = 0; i < workers; i++)
+internal static class Program
 {
-    tasks.Add(Task.Run(() =>
+    private const int Seconds = 3;
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static void WorkWithLock(object gate, TimeSpan duration)
     {
-        start.Wait();
         var sw = Stopwatch.StartNew();
-        while (sw.Elapsed < TimeSpan.FromSeconds(Seconds))
+        while (sw.Elapsed < duration)
         {
             lock (gate)
             {
                 Thread.Sleep(2);
             }
         }
-    }));
-}
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static void RunWorkers(int workers, int seconds)
+    {
+        var gate = new object();
+        var start = new ManualResetEventSlim(false);
+        var tasks = new List<Task>(workers);
+        var duration = TimeSpan.FromSeconds(seconds);
+
+        for (var i = 0; i < workers; i++)
+        {
+            tasks.Add(Task.Run(() =>
+            {
+                start.Wait();
+                WorkWithLock(gate, duration);
+            }));
+        }
 
-start.Set();
-Task.WaitAll(tasks.ToArray());
+        start.Set();
+        Task.WaitAll(tasks.ToArray());
+    }
 
-Console.WriteLine($"Completed {workers} workers with contention.");
-Console.WriteLine($"Lock contention count: {Monitor.LockContentionCount}");
+    public static void Main()
+    {
+        var workerCount = Math.Max(4, Environment.ProcessorCount * 2);
+        RunWorkers(workerCount, Seconds);
+
+        Console.WriteLine($"Completed {workerCount} workers with contention.");
+        Console.WriteLine($"Lock contention count: {Monitor.LockContentionCount}");
+    }
+}

examples/cpu/CpuDemo.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+</Project>

examples/cpu/Program.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Runtime.CompilerServices;
+
+internal static class Program
+{
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static int Fib(int n)
+    {
+        var a = 0;
+        var b = 1;
+        for (var i = 0; i < n; i++)
+        {
+            var tmp = a + b;
+            a = b;
+            b = tmp;
+        }
+
+        return a;
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static long CpuWork(int iterations)
+    {
+        long sum = 0;
+        for (var i = 0; i < iterations; i++)
+        {
+            var n = (i % 30) + 1;
+            sum += Fib(n);
+        }
+
+        return sum;
+    }
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static void RunWork()
+    {
+        var total = CpuWork(1_000_000);
+        Console.WriteLine(total.ToString());
+    }
+
+    public static void Main()
+    {
+        RunWork();
+    }
+}

examples/cpu/README.md

@@ -0,0 +1,19 @@
+# CPU demo
+
+Build:
+
+```bash
+dotnet build -c Release
+```
+
+Profile:
+
+```bash
+asynkron-profiler --cpu -- ./bin/Release/net10.0/CpuDemo
+```
+
+Or (framework-dependent):
+
+```bash
+asynkron-profiler --cpu -- dotnet ./bin/Release/net10.0/CpuDemo.dll
+```

examples/exception/ExceptionDemo.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+</Project>

examples/exception/Program.cs

@@ -0,0 +1,29 @@
+using System;
+
+var handled = 0;
+
+for (var i = 0; i < 20_000; i++)
+{
+    try
+    {
+        if (i % 3 == 0)
+        {
+            throw new InvalidOperationException("boom");
+        }
+
+        if (i % 7 == 0)
+        {
+            throw new ArgumentException("bad");
+        }
+    }
+    catch (InvalidOperationException)
+    {
+        handled += 1;
+    }
+    catch (ArgumentException)
+    {
+        handled += 2;
+    }
+}
+
+Console.WriteLine(handled.ToString());

examples/exception/README.md

@@ -0,0 +1,19 @@
+# Exception demo
+
+Build:
+
+```bash
+dotnet build -c Release
+```
+
+Profile:
+
+```bash
+asynkron-profiler --exception -- ./bin/Release/net10.0/ExceptionDemo
+```
+
+Filter to a specific exception type:
+
+```bash
+asynkron-profiler --exception --exception-type "InvalidOperation" -- ./bin/Release/net10.0/ExceptionDemo
+```

examples/heap/HeapDemo.csproj

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+</Project>

examples/heap/Program.cs

@@ -0,0 +1,14 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+
+var payloads = new List<byte[]>();
+
+for (var i = 0; i < 50_000; i++)
+{
+    payloads.Add(new byte[256]);
+}
+
+Console.WriteLine(payloads.Count.ToString());
+Thread.Sleep(15000);
+GC.KeepAlive(payloads);