JulPas.MauiPerformance.Telemetry 1.0.1

MauiPerformance.Telemetry

Zero-config layout performance telemetry for .NET MAUI apps. Automatically instruments every page to capture:

• Time to Pixels (TTP) — full duration from page creation to first native draw
• Layout cascade batches — grouped Measure/Arrange passes with frame budget analysis
• Dropped frame detection — hardware-aware frame budget violations
• Lifecycle timeline — Constructor → OnAppearing → Native Draw with gap detection

Output Example

╔════════════════════════════════════════════════════════════════════════
║ SESSION START: [MainPage]
║ Hardware Detected: 120 Hz Refresh Rate (1 Frame = 8.33 ms)
╚════════════════════════════════════════════════════════════════════════

  ┌─── LIFECYCLE ────────────────────────────────────────────────────────
[T +    0.0 ms]  │  ⚡ [Constructor / XAML Inflation]
[T +   12.3 ms]  │     └─ Completed in 12.30 ms
[T +   12.3 ms]  │  🛑 [Thread Blocked] gap of 25.00 ms (3.0 frames)
  │
[T +   37.3 ms]  │  👁️ [OnAppearing]
  │
[T +   85.0 ms]  │  🎨 [Native Draw Complete]
  └─────────────────────────────────────────────────────────────────────

  ┌─── LAYOUT CASCADES (2 batches) ──────────────────────────────────────
[T +   37.5 ms]  │  ┌─ Frame Batch #0
[T +   37.5 ms]  │  │  [██████░░] 75% Frame Budget (6.25 ms Layout / 2.08 ms Idle)
[T +   37.5 ms]  │  │  📐 Measure ×12  📍 Arrange ×12  VerticalStackLayout (3.200 ms)
[T +   37.5 ms]  │  │  📐 Measure ×4   Label (1.100 ms)
[T +   43.8 ms]  │  └─ Σ Measure: 16  Arrange: 12  Duration: 6.250 ms
  │
[T +   60.0 ms]  │  ┌─ Frame Batch #1  ⚠️ OVER BUDGET
[T +   60.0 ms]  │  │  [████████] 100% Frame Budget (10.50 ms Layout / 0.00 ms Idle)
[T +   70.5 ms]  │  └─ Σ Measure: 8  Arrange: 8  Duration: 10.500 ms
  └─────────────────────────────────────────────────────────────────────

  ┌───────────────────────────────────────────────────────────────────────┐
  │ PERFORMANCE BUDGET SUMMARY                                           │
  ├────────────────────────────────────┬──────────────────────────────────┤
  │ Total Time to Pixels (TTP):       │ 85.00 ms                         │
  │ Layout Math (Measure/Arrange):    │ 16.75 ms  (19.7%)                │
  │ Main Thread Gaps / Inflation:     │ 68.25 ms  (80.3%)  ⚠️ HIGH RISK │
  │ Target Frame Budget Status:       │ 10 Frames Dropped during Inflation│
  ├────────────────────────────────────┼──────────────────────────────────┤
  │ Constructor Duration:             │ 12.30 ms                         │
  │ Constructor → OnAppearing:        │ 25.00 ms                         │
  │ OnAppearing → Native Draw:        │ 47.70 ms                         │
  │ Total Measure Passes:             │ 24                               │
  │ Total Arrange Passes:             │ 20                               │
  └────────────────────────────────────┴──────────────────────────────────┘

Getting Started

1. Install the package

dotnet add package MauiPerformance.Telemetry

2. Register in MauiProgram.cs

using MauiPerformance.Telemetry;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .AddLayoutTelemetry(); // ← one line, that's it

        return builder.Build();
    }
}

3. Run your app

Navigate to any page — telemetry reports are automatically printed to the Debug output window. No per-page code changes needed.

Requirements

• .NET 10+
• .NET MAUI (Android, iOS, Mac Catalyst)

How It Works

1. Auto-attaches a behavior to every page via Application.PageAppearing
2. Listens to .NET 10 MAUI's built-in layout metrics (maui.layout.measure_duration, maui.layout.arrange_duration)
3. Groups rapid-fire layout events into frame-budget-aware batches using the device's actual refresh rate
4. Detects native first draw using platform-specific APIs (Android ViewTreeObserver.OnDraw, iOS/Mac CATransaction completion)
5. Renders a full timeline report to Debug.Write as a single atomic block (no OS log prefix interleaving)

Configuration

No configuration needed — the library auto-detects your device's refresh rate and adjusts frame budgets accordingly. It runs in DEBUG builds by default since output goes through System.Diagnostics.Debug.

Platform Support

License

MIT