GitHub Issue (If applicable): #

PR Type

• Feature

What is the current behavior?

ITelemetry only tracks events with string properties and double measurements. No support for exception telemetry, contextual scoping, or severity levels.

What is the new behavior?

Breaking API Changes

Added exception tracking and exception severity enum to ITelemetry, plus CreateScope as an extension method:

public enum ExceptionSeverity
{
    Critical, Error, Warning, Info, Debug
}

// Extension method in TelemetryExtensions class
public static ITelemetry CreateScope(
    this ITelemetry telemetry,
    IReadOnlyDictionary<string, string>? properties = null,
    IReadOnlyDictionary<string, double>? measurements = null);

// New interface method
public interface ITelemetry
{
    // Existing members...
    
    void TrackException(
        Exception exception,
        IReadOnlyDictionary<string, string>? properties = null,
        IReadOnlyDictionary<string, double>? measurements = null,
        ExceptionSeverity severity = ExceptionSeverity.Error);
}

Architecture

Scope Implementation:

• CreateScope is an extension method (in TelemetryExtensions) that works with any ITelemetry implementation
• Returns a ScopedTelemetry wrapper - an implementation-agnostic class that handles scope merging
• Scope wrapper does not dispose the inner telemetry instance (only disposes the scope itself)
• Eliminates code duplication across implementations
• Avoids fragile object initializer patterns

Scope Semantics:

• Scopes nest and merge: child properties override parent on key conflicts
• Event-specific properties override scope properties
• Applies to both TrackEvent and TrackException
• All scope logic centralized in ScopedTelemetry wrapper

Backend Implementations

Application Insights (Telemetry):

• Maps ExceptionSeverity → SeverityLevel
• Uses TelemetryClient.TrackException(ExceptionTelemetry)
• No implementation-specific scope handling needed (uses wrapper)
• Thread-safe lock-free chaining works correctly on single-threaded WASM (CompareExchange succeeds immediately, Thread.Yield() is a no-op)
• Helper methods use Core pattern to eliminate code duplication

File-based (FileTelemetry):

{
  "Type": "exception",
  "Timestamp": "...",
  "Severity": "Error",
  "Exception": {
    "Type": "System.InvalidOperationException",
    "Message": "...",
    "StackTrace": "..."
  },
  "Properties": { "scopeKey": "scopeValue" },
  "Measurements": { "duration": 123.45 }
}

Example Usage

var telemetry = new Telemetry(key, prefix, assembly);

// Scoped context automatically enriches all events/exceptions via extension method
using var scope = telemetry.CreateScope(
    properties: new Dictionary<string, string> { ["component"] = "DataService" });

scope.TrackException(
    new TimeoutException("Query timeout"),
    properties: new Dictionary<string, string> { ["query"] = "SELECT *" },
    measurements: new Dictionary<string, double> { ["duration_ms"] = 5000 },
    severity: ExceptionSeverity.Warning);
// Result includes both "component" (from scope) and "query" (from call)

Code Quality

All duplicate code has been eliminated through refactoring:

• GetEventProperties and GetEventMeasures overloads consolidated using shared Core helper methods
• Both IDictionary and IReadOnlyDictionary overloads delegate to GetEventPropertiesCore and GetEventMeasuresCore that accept IEnumerable<KeyValuePair<T>>
• Similar consolidation pattern used in ScopedTelemetry for merge operations

OTel-Ready

Contract carries structured exception data, severity, and scoped context sufficient for future OpenTelemetry backend without API changes.

PR Checklist

• Tested code with current supported SDKs
• Docs have been added/updated which fit documentation template (N/A - internal library)
• Unit Tests and/or UI Tests for the changes have been added
• Wasm UI Tests are not showing unexpected any differences (N/A)
• Contains NO breaking changes
• Updated the Release Notes
• Associated with an issue (GitHub or internal)

Breaking Changes: This PR introduces breaking changes to ITelemetry interface - implementations must add TrackException method. The ExceptionSeverity enum is new. CreateScope is provided as an extension method, so no implementation changes required for scope support.

Other information

Testing: 33 tests pass (14 existing + 19 new). New tests cover exception tracking, severity mapping, nested scope merging, and override behavior.

Security: CodeQL analysis shows 0 vulnerabilities. All telemetry operations maintain no-throw guarantees.

Architecture: Scope implementation uses extension method + wrapper pattern per code review feedback, eliminating duplication and avoiding fragile patterns in concrete implementations. The scope wrapper correctly does not dispose the inner telemetry instance, which may be shared across multiple scopes or used directly. All helper methods follow the Core pattern to consolidate duplicate implementations and reduce code duplication.

Platform Compatibility: Thread-safe lock-free chaining pattern (using Interlocked.CompareExchange with Thread.Yield) works correctly on all platforms including single-threaded WASM, where concurrent access doesn't occur and the exchange succeeds immediately.

Internal Issue (If applicable):

• Fixes unoplatform/uno-private#1678

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.