Mobile App Insights: small slice (Mac Catalyst)

[davidortinau]

Ships the first-increment (~3 hour) mobile Application Insights slice per Captain's path 1 go approval. Wires Azure.Monitor.OpenTelemetry.Exporter into the existing MAUI OTel pipeline, subscribes to MauiExceptions.UnhandledException, and embeds the connection string in appsettings.Production.json (write-only ingestion key — embedding is the documented pattern; per the decisions memo wash-mobile-appinsights-answers).

In scope

• Azure resource sstudio-mobile-ai in rg-sstudio-prod, workspace-linked to law-3ovvqiybthkb6, daily cap 0.5 GB.
• Azure.Monitor.OpenTelemetry.Exporter 1.7.0 added to SentenceStudio.MauiServiceDefaults. Bumped OpenTelemetry.Extensions.Hosting / Exporter.OTLP / Instrumentation.Http to 1.15.x to satisfy Azure Monitor's transitive floor.
• cloud_RoleName set explicitly via ResourceBuilder.AddService("SentenceStudio.Mobile.<DeviceInfo.Platform>").
• SentenceStudioAppBuilder.InitializeApp subscribes once to MauiExceptions.UnhandledException → ILogger.LogCritical → best-effort ForceFlush(3000) on all three OTel providers before the process dies.
• appsettings.Production.json updated with AzureMonitor:ConnectionString.
• Fixed pre-existing Release-build break: MacCatalyst/MauiProgram.cs had unguarded using Microsoft.Maui.DevFlow.* even though those packages are Condition='$(Configuration)'=='Debug'. Wrapped the usings in #if DEBUG.

Out of scope (deferred to full plan)

• Blazor WebView JS error bridge (window.onerror, unhandledrejection)
• Android / iOS linker preserve directives for Release link-time trimming
• PrivacyInfo.xcprivacy (Captain confirmed no App Store submission planned)
• Windows head, marketing site
• Custom telemetry processors / sampling / session replay / live metrics

Validation

Built Release Mac Catalyst, launched with SENTENCESTUDIO_CRASH_TEST=1, temp thread threw InvalidOperationException 10s after launch. Waited 4 minutes. KQL query:

exceptions
| where timestamp > ago(15m)
| where cloud_RoleName contains "SentenceStudio"
| project timestamp, type, outerMessage, cloud_RoleName, operation_Id
| order by timestamp desc

Result (truncated):

timestamp	type	outerMessage	cloud_RoleName
2026-04-20T03:09:14Z	System.InvalidOperationException	AppInsights pipeline validation (wash: squad/mobile-appinsights-slice)	SentenceStudio.Mobile.MacCatalyst
2026-04-20T03:09:04Z	System.InvalidOperationException	Model building is not supported when publishing with NativeAOT…	SentenceStudio.Mobile.MacCatalyst
2026-04-20T03:09:04Z	System.InvalidOperationException	HelpKit could not select a presenter automatically…	SentenceStudio.Mobile.MacCatalyst

The forced exception (AppInsights pipeline validation…) is there, plus bonus evidence the pipeline is already catching caught-and-logged exceptions from startup code paths (EF NativeAOT model-build, HelpKit presenter). cloud_RoleName is correct. Temp validation code reverted before commit.

operation_Id is empty because we throw from a bare Thread, not inside an OTel-instrumented activity. Real crashes inside an HttpClient span will populate it and correlate to the API once the server-side companion ships.

Secret management

Committed the connection string to appsettings.Production.json (which is already a tracked file containing service-discovery endpoints). Rationale, per .squad/decisions.md wash-mobile-appinsights-answers:

• InstrumentationKey is write-only: it authorizes ingestion push; it cannot read telemetry or touch any other Azure resource.
• Microsoft's documented pattern for mobile/desktop/JS clients is to ship it in the bundle.
• Worst case is fake-telemetry spam, bounded by the 0.5 GB/day ingestion cap we set.
• All "secure" alternatives (fetch-at-startup, per-user keys, Key Vault) are strictly worse for mobile — chicken-and-egg if the API is down, or require an Azure identity the app doesn't have.

If Captain prefers an env-var / non-committed override path later, that is easy to add (the config system reads env vars already).

Follow-ups before full rollout

• Server-side Azure Monitor exporter in SentenceStudio.Api so W3C traceparent correlates mobile → API spans.
• Blazor WebView JS bridge.
• Android/iOS linker preserve + Android Release smoke test.
• iOS device smoke test on DX24 (Release).
• Windows head.

Resource

• App Insights: /subscriptions/a25bc5f2-e641-47b9-89a8-5e5fd428d9d6/resourceGroups/rg-sstudio-prod/providers/microsoft.insights/components/sstudio-mobile-ai
• AppId: 74e94530-d17f-404a-8726-b7266724b70f
• Daily cap: 0.5 GB, notifications on cap

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[davidortinau]

Review fixes applied (commit 656556b)

All three issues from review are addressed. PR stays in draft.

Fix 1 (HIGH) — DeviceInfo.Platform read too early

ConfigureOpenTelemetry was calling DeviceInfo.Platform while the host builder was still configuring — pre-MauiApp.Build(). MAUI Essentials aren't guaranteed to be ready there; cloud_RoleName could have landed as Unknown and defeated the whole tag.

Threaded the platform string through from each platform head where the per-TFM context is unambiguous:

• AddMauiServiceDefaults and ConfigureOpenTelemetry now take string platformName = "Unknown".
• src/SentenceStudio.MacCatalyst/MauiProgram.cs → AddMauiServiceDefaults("MacCatalyst")
• src/SentenceStudio.iOS/MauiProgram.cs → AddMauiServiceDefaults("iOS")
• src/SentenceStudio.Android/MauiProgram.cs → AddMauiServiceDefaults("Android")
• Windows head doesn't call AddMauiServiceDefaults today — left alone.

Deterministic, zero-runtime-surface, works even pre-Essentials.

Fix 2 (MEDIUM) — Serial ForceFlush risked iOS watchdog kill

Previous code flushed logger → tracer → meter serially at 3000ms each = 9s worst case. iOS watchdog is ~5–10s. Now: three Task.Run flushes (each with their own 2500ms internal ceiling) wrapped in one Task.WaitAll(..., TimeSpan.FromMilliseconds(3000)). Hard 3s wall-time cap regardless of per-provider stalls. All exceptions swallowed — exception-in-handler is worse than missed telemetry.

Fix 3 (MEDIUM) — UnhandledException subscription now idempotent

Gated behind Interlocked.Exchange(ref _unhandledExceptionWired, 1) == 0 on a static int (not a plain bool) so hot-reload / double-init paths can't race or double-wire the handler.

---

Validation

SENTENCESTUDIO_CRASH_TEST=1 rerun on a clean Mac Catalyst Release build. Forced InvalidOperationException landed in sstudio-mobile-ai:

timestamp                  type                                outerMessage                                                   cloud_RoleName
2026-04-21T20:22:36.560Z   System.InvalidOperationException    AppInsights pipeline validation — PR #165 review fixes (wash) SentenceStudio.Mobile.MacCatalyst

KQL used:

union exceptions, traces
| where timestamp > datetime(2026-04-21T20:22:00Z)
| project timestamp, itemType, type, msg=coalesce(outerMessage, message), cloud_RoleName, severityLevel
| order by timestamp desc

cloud_RoleName is the threaded-in literal, confirming Fix 1 is live. Temp validation hook reverted before commit.

Incidental learnings (captured in .squad/skills/maui-azure-monitor/SKILL.md)

• Parallel-bounded flush pattern is now documented in the skill with double-timeout rationale.
• Launch Mac Catalyst Release bundles via open --env VAR=VAL app.app, NOT by invoking the binary in Contents/MacOS/ directly — MAUI aborts in load_aot_module when launched outside LaunchServices.
• Stale obj/Release after OTel package bumps can produce ghost Failed to load AOT module 'Azure.Core' crashes. Clean src/*/obj/Release + rebuild fixes it.

PR remains in draft per the task.