Add performance logging and suggestions to .NET MAUI rendering

[PureWeen]

Description

Based on this issue, it is challenging to determine exactly where most of the rendering time is consumed on a page.

Key considerations include:

• Adding hooks at specific points in the platform layout system to track the time spent during various rendering phases.
  • This idea is demonstrated in certain tests (see comment), but making it a first-class feature of the framework could provide additional insights.
• Allowing each layout to log how long it takes to render.
• Providing recommendations/warnings at runtime for optimizing less efficient execution paths.
  • Refer to this issue and this comment for further context.

Possible Points in time to measure

• SetVirtualView (this tells us how long it takes to create the control and run all the initial mappers)
• Measure
• Arrange
• InitializeComponent call to setup all bindings
• Count every time calls are marshalled back to the Dispatcher to see if users are building up lot of calls to the dispatcher

Alternative Ideas

• Don't provide fine grained performance details but possibly just general load times. Instead provide event hooks into areas of the app and users can log for themselves if they want to, or 3rd parties can create libraries.

[jsuarezruiz]

.NET MAUI Performance Monitoring Spec

Overview

This specification defines a comprehensive performance monitoring system for the .NET MAUI framework, focusing on performance metrics including layout engine performance, memory consumption, WebView performance, and Blazor Hybrid monitoring. The system will be integrated directly into the MAUI framework using EventCounters and extended through separate libraries like an OpenTelemetry-based library.

Architecture Overview

Core Design Principles

1. Zero-overhead when disabled - Performance tracking can be completely disabled at compile time
2. Configurable granularity - From high-level aggregates to per-element tracking
3. Production-ready - Built for both development debugging and production monitoring

Core Components

1. PerformanceProfiler - Central performance tracking class integrated into MAUI framework
2. Threshold Warning System - Configurable alerts for performance degradation
3. EventCounter Integration - Built-in performance counters for real-time monitoring
4. OpenTelemetry Extension Library - Separate library for advanced monitoring capabilities

1. Performance Metrics Specification

1.1 Layout Engine Performance Metrics

1.1.1 Measure Pass Tracking

• Counter Name: maui.perf.layout.measure.passes
• Type: IncrementingEventCounter
• Description: Total number of measure passes executed per layout cycle
• Granularity: Per-element and aggregate tracking
• Statistical Data:
  • Pass count per layout cycle
  • Time per pass (nanoseconds)
  • Average processing time per measure operation
  • Peak measure time within cycle
• Warning Thresholds:
  • Measure time > 5ms (configurable)
  • Measure passes > 10 per cycle (configurable)
  • Layout depth > 15 levels (configurable)

1.1.2 Arrange Pass Tracking

• Counter Name: maui.perf.layout.arrange.passes
• Type: IncrementingEventCounter
• Description: Total number of arrange passes executed per layout cycle
• Granularity: Per-element and aggregate tracking
• Statistical Data:
  • Pass count per layout cycle
  • Time per pass (nanoseconds)
  • Average processing time per arrange operation
  • Peak arrange time within cycle
• Warning Thresholds:
  • Arrange time > 5ms (configurable)
  • Arrange passes > 10 per cycle (configurable)

1.2 Memory Consumption Metrics

1.2.1 App Memory Usage

• Counter Name: maui.perf.memory.framework.usage
• Type: PollingCounter
• Description: MAUI framework-specific memory consumption
• Metrics:
  • Visual element memory footprint (bytes)
  • Binding infrastructure memory (bytes)
  • Event handler memory overhead (bytes)
• Warning Thresholds:
  • Framework memory > 400MB (configurable)

1.3 WebView Performance Tracking

1.3.1 WebView Lifecycle Metrics

• Counter Name: maui.perf.webview.lifecycle
• Type: EventCounter
• Description: WebView initialization and lifecycle performance
• Metrics:
  • WebView creation time (nanoseconds)
  • First content paint time (nanoseconds)
  • Navigation completion time (nanoseconds)
  • Resource loading duration (nanoseconds)
• Warning Thresholds:
  • WebView creation > 2000ms (configurable)
  • First content paint > 3000ms (configurable)
  • Navigation timeout > 10000ms (configurable)

1.4 Blazor Hybrid Monitoring

1.4.1 Blazor Component Performance

• Counter Name: maui.perf.blazor.component.performance
• Type: EventCounter
• Description: Blazor component rendering and lifecycle performance
• Metrics:
  • Component render time (nanoseconds)
  • State change propagation time (nanoseconds)
  • Event handling latency (nanoseconds)
  • Component tree depth impact on performance
• Warning Thresholds:
  • Component render time > 16ms (configurable, based on 60fps target)
  • State change propagation > 5ms (configurable)
  • Component tree depth > 20 levels (configurable)

1.4.2 Blazor-MAUI Interop Performance

• Counter Name: maui.perf.blazor.interop.performance
• Type: EventCounter
• Description: Performance of Blazor-MAUI interoperability
• Metrics:
  • Interop call latency (nanoseconds)
  • Data serialization time (nanoseconds)
  • Native control binding performance (nanoseconds)
  • Event marshaling overhead (nanoseconds)
• Warning Thresholds:
  • Interop call latency > 10ms (configurable)
  • Data serialization > 5ms (configurable)
  • Event marshaling > 2ms (configurable)

1.5 Image Performance Tracking

1.5.1 Image Loading Metrics

• Counter Name: maui.perf.image.loading.performance
• Type: EventCounter
• Description: Image loading and processing performance tracking
• Metrics:
  • Image load time (nanoseconds)
  • Network download time for remote images (nanoseconds)
  • Image caching performance (cache hit/miss rates)
  • Memory allocation for image buffers (bytes)
• Warning Thresholds:
  • Image load time > 500ms (configurable)
  • Network download > 2000ms (configurable)

1.5.2 Image Memory Metrics

• Counter Name: maui.perf.image.memory.usage
• Type: PollingCounter
• Description: Memory consumption related to image handling
• Metrics:
  • Raw image data memory usage (bytes)
• Warning Thresholds:
  • Individual image size > 10MB (configurable)
  • Total image memory > 200MB (configurable)

2. Implementation Architecture

Core Performance Profiler Class

The PerformanceProfiler class will be the central hub for all performance tracking:

public interface IPerformanceProfiler
{
    // Configuration Interface
    void ConfigureLayoutTracking(bool enableMeasureTracking, bool enableArrangeTracking);
    void ConfigureMemoryTracking();
    void ConfigureWebViewTracking();
    void ConfigureBlazorTracking(bool enableComponent, bool enableInterop);
    void ConfigureImageTracking(bool enableLoading, bool enableMemory);
    void SetTrackingGranularity(TrackingGranularity granularity);
    void EnableStatisticalAnalysis(bool enableAverages, bool enablePeakDetection);
    
    // Data Access Interface
    PerformanceSnapshot GetCurrentStats();
    LayoutPerformanceStats GetLayoutStats();
    MemoryPerformanceStats GetMemoryStats();
    WebViewPerformanceStats GetWebViewStats();
    BlazorPerformanceStats GetBlazorStats();
    ImagePerformanceStats GetImageStats();
    
    // Real-time Data Streaming
    void SubscribeToLayoutUpdates(Action<LayoutUpdate> callback);
    void SubscribeToMemoryUpdates(Action<MemoryUpdate> callback);
    void SubscribeToImageUpdates(Action<ImageUpdate> callback);
    void SubscribeToRealTimeUpdates(Action<PerformanceUpdate> callback);

    void StartRealTimeMonitoring(TimeSpan interval);
    void StopRealTimeMonitoring();
    
    // Warnings
    void ConfigureThresholds(PerformanceThresholds thresholds);
    void EnableWarnings(bool enable);
    void SetWarningLevel(PerformanceWarningLevel minimumLevel);
    
    event PerformanceWarningHandler WarningRaised;

    IEnumerable<PerformanceWarning> GetRecentWarnings(TimeSpan timeWindow);
    void ClearWarningHistory();

    // Formatted Output
    void PrintCurrentStats(TextWriter writer = null);
    void PrintDetailedReport(TextWriter writer = null);
    void PrintWarnings(TextWriter writer = null);
    void ExportStats(PerformanceExportFormat format, Stream output);
}

public interface IPerformanceWarningManager
{
    event PerformanceWarningHandler WarningRaised;
    
    void ConfigureThresholds(PerformanceThresholds thresholds);
    void CheckThreshold<T>(string category, string metric, T currentValue, T thresholdValue, 
                          string recommendation = null) where T : IComparable<T>;
    void EnableWarnings(bool enable);
    void SetWarningLevel(PerformanceWarningLevel minimumLevel);
    
    IEnumerable<PerformanceWarning> GetRecentWarnings(TimeSpan timeWindow);
    void ClearWarningHistory();
}

Layout Tracking Implementation

The layout tracking is integrated at the layout engine level:

Layout.MeasureOverride()
    ↓
[Timing with Stopwatch]
    ↓
PerformanceProfiler.RecordMeasurePass()
    └── Records to EventSource (for dotnet-counters)

Example implementation in StackLayout:

public class StackLayout : Layout
{
    static readonly Stopwatch _stopwatch = new Stopwatch();
    readonly IPerformanceProfiler _profiler;

    public StackLayout(IPerformanceProfiler profiler = null)
    {
        _profiler = profiler ?? ServiceHelper.GetService<IPerformanceProfiler>();
    }

    protected override Size MeasureOverride(double widthConstraint, double heightConstraint)
    {
        _stopwatch.Restart();
        
        try
        {
            return base.MeasureOverride(widthConstraint, heightConstraint);
        }
        finally
        {
            _stopwatch.Stop();
            var durationNs = _stopwatch.ElapsedTicks * 1_000_000_000L / Stopwatch.Frequency;
            _profiler?.RecordMeasurePass(durationNs);
        }
    }
}

Performance Profiler Implementation

public class PerformanceProfiler : IPerformanceProfiler
{
    readonly IPerformanceWarningManager _warningManager;
    PerformanceThresholds _thresholds;

    ...

    public void RecordMeasurePass(long duration)
    {
        MauiLayoutEventSource.Instance.RecordMeasurePass(duration);
    }

    public void RecordArrangePass(long duration)
    {
        MauiLayoutEventSource.Instance.RecordArrangePass(duration);

        CheckLayoutMeasureTimeThreshold(duration);
    }

    public void RecordImageLoad(long loadTime, long imageSize, int width, int height, string source)
    {
        MauiImageEventSource.Instance.RecordImageLoad(loadTime, imageSize);
        
        // Check multiple thresholds
        CheckImageSizeThreshold(imageSize);
        CheckImageLoadTimeThreshold(loadTime);
    }

    void CheckLayoutMeasureTimeThreshold(long duration)
    {
        var thresholdNs = (long)_thresholds.Layout.MaxMeasureTime.TotalNanoseconds;
        if (duration > thresholdNs)
        {
            _warningManager.CheckThreshold("Layout", "MeasureTime", duration, thresholdNs,
                "Consider reducing layout complexity or using more efficient layout containers");
        }
    }

    void CheckImageSizeThreshold(long imageSize)
    {
        if (imageSize > _thresholds.Image.MaxIndividualImageSize)
        {
            _warningManager.CheckThreshold("Image", "Size", imageSize, _thresholds.Image.MaxIndividualImageSize,
                "Consider compressing the image or using a more efficient format");
        }
    }

    void CheckImageLoadTimeThreshold(long loadTime)
    {
        var thresholdNs = (long)_thresholds.Image.MaxImageLoadTime.TotalNanoseconds;
        if (loadTime > thresholdNs)
        {
            _warningManager.CheckThreshold("Image", "LoadTime", loadTime, thresholdNs,
                "Consider implementing image caching or loading smaller resolution images");
        }
    }

    ...
}

EventSource Implementation

[EventSource(Name = "Microsoft.Maui.Layout")]
public sealed class MauiLayoutEventSource : EventSource
{
    public static readonly MauiLayoutEventSource Instance = new MauiLayoutEventSource();

    readonly IncrementingEventCounter _measurePassCounter;
    readonly IncrementingEventCounter _arrangePassCounter;
    readonly EventCounter _measureDurationCounter;
    readonly EventCounter _arrangeDurationCounter;

    private MauiLayoutEventSource()
    {
        _measurePassCounter = new IncrementingEventCounter("maui.perf.layout.measure.passes", this)
        {
            DisplayName = "Layout Measure Passes"
        };

        _arrangePassCounter = new IncrementingEventCounter("maui.perf.layout.arrange.passes", this)
        {
            DisplayName = "Layout Arrange Passes"
        };

        _measureDurationCounter = new EventCounter("maui.perf.layout.measure.duration", this)
        {
            DisplayName = "Layout Measure Duration",
            DisplayUnits = "nanoseconds"
        };

        _arrangeDurationCounter = new EventCounter("maui.perf.layout.arrange.duration", this)
        {
            DisplayName = "Layout Arrange Duration",
            DisplayUnits = "nanoseconds"
        };
    }

    public void RecordMeasurePass(long duration)
    {
        _measurePassCounter.Increment();
        _measureDurationCounter.WriteMetric(duration);
    }

    public void RecordArrangePass(long duration)
    {
        _arrangePassCounter.Increment();
        _arrangeDurationCounter.WriteMetric(duration);
    }
}

EventCounter Integration Strategy

Counter Categories

1. Layout Counters (Microsoft.Maui.Layout)
2. Memory Counters (Microsoft.Maui.Memory)
3. WebView Counters (Microsoft.Maui.WebView)
4. Blazor Counters (Microsoft.Maui.Blazor)
5. Image Counters (Microsoft.Maui.Image)

Counter Implementation Pattern

Each counter will follow a consistent pattern:

• Nanosecond precision for timing measurements
• Statistical aggregation (min, max, average, percentiles)
• Configurable sampling rates
• Thread-safe implementation
• Minimal performance overhead

HostBuilder Integration

Extension Method Specification

// Extension method signature
public static MauiAppBuilder ConfigurePerformanceMonitoring(
    this MauiAppBuilder builder,
    Action<PerformanceMonitoringOptions> configure = null)

// Configuration options structure
public class PerformanceMonitoringOptions
{
    public LayoutTrackingOptions Layout { get; set; } = new();
    public MemoryTrackingOptions Memory { get; set; } = new();
    public WebViewTrackingOptions WebView { get; set; } = new();
    public BlazorTrackingOptions Blazor { get; set; } = new();
    public ImageTrackingOptions Image { get; set; } = new();
    public StatisticalOptions Statistics { get; set; } = new();
    public SamplingOptions Sampling { get; set; } = new();
    public WarningOptions Warnings { get; set; } = new();
}

public class WarningOptions
{
    public bool EnableWarnings { get; set; } = true;
    public PerformanceWarningLevel MinimumLevel { get; set; } = PerformanceWarningLevel.Warning;
    public bool LogToDebugOutput { get; set; } = true;
}

Configuration Parameters

Layout Tracking Options:

• EnableMeasurePassTracking (default: true)
• EnableArrangePassTracking (default: true)
• TrackPerElementMetrics (default: false)
• MaxTrackingDepth (default: 10)

Memory Tracking Options:

• EnableAppMemoryTracking (default: true)
• MemorySamplingInterval (default: 1000ms)

WebView Tracking Options:

• EnableLifecycleTracking (default: true)
• EnableInteractionTracking (default: false)
• TrackJavaScriptBridge (default: false)

Blazor Tracking Options:

• EnableComponentTracking (default: true)
• EnableInteropTracking (default: false)
• TrackRenderingPipeline (default: false)

Image Tracking Options:

• EnableLoadingTracking (default: true)
• EnableMemoryTracking (default: true)

3. Usage Guidelines

Startup Configuration

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        
        builder.ConfigurePerformanceMonitoring(options =>
        { 
            // Enable tracking
            options.Layout.EnableMeasurePassTracking = true;
            options.Layout.EnableArrangePassTracking = true;
            options.Memory.EnableFrameworkMemoryTracking = true;
            options.Image.EnableLoadingTracking = true;
            options.Image.EnableMemoryTracking = true;

            // Configure custom thresholds
            options.Thresholds.Image.MaxIndividualImageSize = 10L * 1024 * 1024; // 10MB
            options.Thresholds.Layout.MaxMeasureTime = TimeSpan.FromMilliseconds(15);
            
            // Configure warnings
            options.Warnings.EnableWarnings = true;
            options.Warnings.MinimumLevel = PerformanceWarningLevel.Warning;
        });
                
        return builder.Build();
    }
}

Accessing Performance Data

1. Getting Current Statistics

Direct API Access

// Resolve the performance profiler from dependency service
var profiler = ServiceProvider.GetService<IPerformanceProfiler>();

// Get comprehensive snapshot
var snapshot = profiler.GetCurrentStats();
Console.WriteLine($"Layout Cycles: {snapshot.LayoutStats.TotalCycles}");
Console.WriteLine($"Average Measure Time: {snapshot.LayoutStats.AverageMeasureTime}ns");
Console.WriteLine($"Memory Usage: {snapshot.MemoryStats.FrameworkMemoryUsage} bytes");

// Get specific category stats
var layoutStats = profiler.GetLayoutStats();
var memoryStats = profiler.GetMemoryStats();
var webViewStats = profiler.GetWebViewStats();
var blazorStats = profiler.GetBlazorStats();

Quick Print Methods

// Resolve profiler and print to console (default)
var profiler = ServiceProvider.GetService<IPerformanceProfiler>();
profiler.PrintCurrentStats();

// Print to specific writer
using var writer = new StringWriter();
profiler.PrintCurrentStats(writer);
string statsOutput = writer.ToString();

// Print detailed report with historical data
profiler.PrintDetailedReport();

2. Real-Time Data Monitoring

Event-Based Real-Time Updates

var profiler = ServiceProvider.GetService<IPerformanceProfiler>();

// Subscribe to all performance updates
profiler.SubscribeToRealTimeUpdates(update => 
{
    Console.WriteLine($"[{update.Timestamp}] {update.Category}: {update.Metric} = {update.Value}");
});

// Subscribe to specific category updates
profiler.SubscribeToLayoutUpdates(layoutUpdate => 
{
    Console.WriteLine($"Layout Update - Measure: {layoutUpdate.MeasurePasses}, " +
                     $"Arrange: {layoutUpdate.ArrangePasses}, " +
                     $"Total Time: {layoutUpdate.TotalTime}ns");
});

profiler.SubscribeToMemoryUpdates(memoryUpdate => 
{
    Console.WriteLine($"Memory Update - Framework: {memoryUpdate.FrameworkMemory}MB, " +
                     $"GC Pressure: {memoryUpdate.GcPressure}");
});

profiler.SubscribeToImageUpdates(imageUpdate => 
{
    Console.WriteLine($"Image Update - {imageUpdate.ImageFormat} " +
                     $"({imageUpdate.Width}x{imageUpdate.Height}) " +
                     $"loaded in {imageUpdate.LoadTime / 1_000_000.0:F2}ms " +
                     $"from {imageUpdate.SourceType}");
});

Page-Level Monitoring

public partial class MainPage : ContentPage
{
    readonly IPerformanceProfiler _profiler;
    
    public MainPage()
    {
        InitializeComponent();
        
        // Resolve profiler from dependency service
        _profiler = ServiceProvider.GetService<IPerformanceProfiler>();
        
        // Subscribe to layout updates for this page
        _profiler.SubscribeToLayoutUpdates(OnLayoutUpdate);
    }
    
    void OnLayoutUpdate(LayoutUpdate update)
    {
        // Update UI with performance info (debug mode only)
        #if DEBUG
        DisplayAlert("Performance", 
            $"Layout: {update.TotalTime / 1_000_000.0:F2}ms", 
            "OK");
        #endif
    }
    
    void OnPerformanceButtonClicked(object sender, EventArgs e)
    {
        // Print current stats to debug output
        _profiler.PrintCurrentStats();
    }
}

Page-Level Performance Monitoring with Warnings

public partial class MainPage : ContentPage
{
    readonly IPerformanceProfiler _profiler;
    readonly List<PerformanceWarning> _pageWarnings = new();
    
    public MainPage()
    {
        InitializeComponent();
        
        _profiler = ServiceProvider.GetService<IPerformanceProfiler>();
        
        // Subscribe to performance events
        _profiler.WarningRaised += OnPerformanceWarning;
        _profiler.SubscribeToLayoutUpdates(OnLayoutUpdate);
        _profiler.SubscribeToImageUpdates(OnImageUpdate);
    }
    
    void OnPerformanceWarning(PerformanceWarning warning)
    {
        _pageWarnings.Add(warning);
        
        // Update performance indicator in UI
        UpdatePerformanceIndicator(warning);
    }
    
    void OnLayoutUpdate(LayoutUpdate update)
    {
        // Real-time performance feedback
        if (update.TotalTime > TimeSpan.FromMilliseconds(16).Ticks * 100) // 16ms in nanoseconds
        {
            PerformanceIndicator.BackgroundColor = Colors.Orange;
            PerformanceLabel.Text = $"Layout: {update.TotalTime / 1_000_000.0:F1}ms";
        }
        else
        {
            PerformanceIndicator.BackgroundColor = Colors.Green;
            PerformanceLabel.Text = "Layout: OK";
        }
    }
    
    void OnImageUpdate(ImageUpdate update)
    {
        // Check for large images
        if (update.FileSize > 10 * 1024 * 1024) // 10MB
        {
            DisplayAlert("Large Image Detected", 
                $"Image {update.FileName} is {update.FileSize / (1024.0 * 1024.0):F1}MB. " +
                "Consider using a compressed format.", 
                "OK");
        }
    }
    
    void OnPerformanceButtonClicked(object sender, EventArgs e)
    {
        // Show performance summary with warnings
        var recentWarnings = _profiler.GetRecentWarnings(TimeSpan.FromMinutes(5));
        var warningCount = recentWarnings.Count();
        
        if (warningCount > 0)
        {
            var criticalCount = recentWarnings.Count(w => w.Level == PerformanceWarningLevel.Critical);
            var warningCountNormal = recentWarnings.Count(w => w.Level == PerformanceWarningLevel.Warning);
            
            DisplayAlert("Performance Summary", 
                $"Recent issues: {criticalCount} critical, {warningCountNormal} warnings\n\n" +
                $"Most recent: {recentWarnings.First().Message}", 
                "OK");
        }
        else
        {
            DisplayAlert("Performance Summary", "No recent performance issues detected.", "OK");
        }
        
        // Print detailed report to debug output
        _profiler.PrintCurrentStats();
        _profiler.PrintWarnings();
    }
}

Output Format Examples

Console Output Format

Layout Performance:
  Total Cycles: 1,247
  Measure Passes: 3,891 (avg: 3.1 per cycle)
  Arrange Passes: 2,134 (avg: 1.7 per cycle)
  Average Times:
    - Measure: 245,678 ns (0.25 ms)
    - Arrange: 123,456 ns (0.12 ms)
  Peak Times:
    - Measure: 1,234,567 ns (1.23 ms)
    - Arrange: 678,901 ns (0.68 ms)

Memory Performance:
  App Memory Usage: 315.2 MB
  Peak App Memory Usage: 328.7 MB

WebView Performance:
  Active WebViews: 2
  Average Load Time: 1,456,789 ns (1.46 ms)
  JS Bridge Calls: 45 (avg: 12,345 ns)

Blazor Performance:
  Active Components: 23
  Average Render Time: 345,678 ns (0.35 ms)
  Interop Calls: 8 (avg: 56,789 ns)

Image Performance:
  Average Load Time: 2,345,678 ns (2.35 ms)
  Total Image Memory: 45.2 MB

PERFORMANCE WARNINGS:
CRITICAL [14:23:45] Image Size: hero-image.jpg (12.4 MB > 10.0 MB)
   → Consider compressing the image or using a more efficient format
   
WARNING [14:24:31] Layout Measure Time: 6.2ms > 5.0ms
   → Consider reducing layout complexity or using more efficient layout containers

Data Reading Strategies

Using dotnet-counters

# Monitor all MAUI performance counters
dotnet-counters monitor --process-id <pid> Microsoft.Maui.Layout Microsoft.Maui.Memory Microsoft.Maui.WebView Microsoft.Maui.Blazor Microsoft.Maui.Image

# Monitor specific counter categories
dotnet-counters monitor --process-id <pid> --counters Microsoft.Maui.Layout,Microsoft.Maui.Image

# Export data for analysis
dotnet-counters collect --process-id <pid> --format json --output maui-perf-data.json

4. OpenTelemetry Extension Library

Library Architecture

The separate OpenTelemetry library (Microsoft.Maui.Performance.OpenTelemetry) will provide:

Enhanced Monitoring Capabilities

• Custom Metrics: Extended metric collection beyond EventCounters
• Alerting Integration: Threshold-based alerting

EventCounter Bridge

• Automatic discovery and consumption of MAUI EventCounters
• Conversion to OpenTelemetry metrics format
• Enhanced metadata and labeling
• Correlation with application traces

EventCounter Bridge Integration

Automatically discovers MAUI-related EventCounters by listening to any EventSource whose name starts with "Microsoft.Maui". When such an EventSource is created, it subscribes to its EventCounters with a specified interval and creates corresponding OpenTelemetry instruments (counters, histograms, etc.) to bridge the EventCounter data. When an EventCounter event is received (with the event name "EventCounters"), it extracts the metric value (using either the Mean or Increment value) and records it using the matched OpenTelemetry instrument.

This bridging allows MAUI EventCounters to be consumed and converted into OpenTelemetry metrics automatically for further analysis and export.

// Automatic discovery and consumption of MAUI EventCounters
public class EventCounterBridge : EventListener
{
    readonly MeterProvider _meterProvider;
    readonly Dictionary<string, Instrument> _bridgedInstruments;
    
    public EventCounterBridge(MeterProvider meterProvider)
    {
        _meterProvider = meterProvider;
        _bridgedInstruments = new Dictionary<string, Instrument>();
    }
    
    protected override void OnEventSourceCreated(EventSource eventSource)
    {
        if (eventSource.Name.StartsWith("Microsoft.Maui"))
        {
            // Enable EventCounter consumption
            EnableEvents(eventSource, EventLevel.Informational, 
                        EventKeywords.All, new Dictionary<string, string>()
                        {
                            ["EventCounterIntervalSec"] = "1"
                        });
                        
            // Create corresponding OpenTelemetry instruments
            CreateBridgedInstruments(eventSource);
        }
    }
    
    protected override void OnEventWritten(EventWrittenEventArgs eventData)
    {
        if (eventData.EventName == "EventCounters")
        {
            var payload = (IDictionary<string, object>)eventData.Payload[0];
            var counterName = (string)payload["Name"];
            var counterValue = Convert.ToDouble(payload["Mean"] ?? payload["Increment"]);
            
            // Bridge to OpenTelemetry metrics
            if (_bridgedInstruments.TryGetValue(counterName, out var instrument))
            {
                RecordBridgedMetric(instrument, counterValue, eventData);
            }
        }
    }
    
    void CreateBridgedInstruments(EventSource eventSource)
    {
        // Create OpenTelemetry instruments for each EventCounter
        var meter = new Meter($"Microsoft.Maui.Bridge.{eventSource.Name}");
        
        // Layout counters
        if (eventSource.Name.Contains("Layout"))
        {
            _bridgedInstruments["maui.perf.layout.measure.passes"] = 
                meter.CreateCounter<long>("maui_layout_measure_passes_total");
            _bridgedInstruments["maui.perf.layout.arrange.passes"] = 
                meter.CreateCounter<long>("maui_layout_arrange_passes_total");
        }
        
        // Image counters
        if (eventSource.Name.Contains("Image"))
        {
            _bridgedInstruments["maui.perf.image.loading.performance"] = 
                meter.CreateHistogram<double>("maui_image_load_duration_seconds");
            _bridgedInstruments["maui.perf.image.memory.usage"] = 
                meter.CreateUpDownCounter<long>("maui_image_memory_bytes");
        }
    }

    ...
}

Host Builder Registration

public class OpenTelemetryPerformanceMonitoringOptions
{
    public bool EnableTracingInstrumentation { get; set; } = true;
    public bool EnableMetricsInstrumentation { get; set; } = true;
}

public static MauiAppBuilder AddOpenTelemetryMonitoring(
     this MauiAppBuilder builder,
     Action<OpenTelemetryPerformanceMonitoringOptions> openTelemetryConfigure = null)
{
    var otelOptions = new OpenTelemetryPerformanceMonitoringOptions();
    openTelemetryConfigure?.Invoke(otelOptions);

    builder.Services.AddOpenTelemetry()
        .WithTracing(tracingBuilder =>
        {
            if (otelOptions.EnableTracingInstrumentation)
                tracingBuilder.AddMauiInstrumentation();
        })
        .WithMetrics(metricsBuilder =>
        {
            if (otelOptions.EnableMetricsInstrumentation)
                metricsBuilder.AddMauiMetrics();
        });

    return builder;
}

OpenTelemetry Usage

Startup Configuration

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        
        builder.ConfigurePerformanceMonitoring(options =>
        {
            options.Layout.EnableMeasurePassTracking = true;
            options.Layout.EnableArrangePassTracking = true;
            options.Memory.EnableFrameworkMemoryTracking = true;
            options.Image.EnableLoadingTracking = true;
            options.Image.EnableMemoryTracking = true;
        });
        
        builder.AddOpenTelemetryMonitoring(otelOptions =>
        {
            otelOptions.EnableTracingInstrumentation = true;
            otelOptions.EnableMetricsInstrumentation = true;
        });
                
        return builder.Build();
    }
}