telemetry

Author: KSemenenko

AGENTS.md

@@ -107,6 +107,8 @@ Rule format:
 - Do not add or raise CI timeout settings as a fix for browser-suite instability or slow runs; fix the underlying failure path cleanly instead of masking it with workflow or step timeouts.
 - For TUnit reporting in GitHub Actions, prefer TUnit's built-in HTML report and the documented `actions/github-script` runtime exposure step over repo-local custom summary scripts or ad-hoc log parsers.
 - Public web hosting is split by role: the standalone PrompterOne app in this repo must publish on `app.prompter.one`, while the marketing landing site for `prompter.one` lives in the separate `PrompterOne-LandingPage` repository.
+- Runtime telemetry providers such as Google Analytics, Clarity, and Sentry must not be described as connected or working unless the real production path is verified with actual outbound delivery or loaded vendor SDKs; local harness snapshots, init flags, or stubbed globals are not sufficient proof.
+- Runtime telemetry readiness must be proven against Release-built app artifacts in CI; do not sign off GA, Clarity, or Sentry from Debug-only local runs when the shipped Release pipeline has not validated that path.
 - For deploy-only, domain, CI, or static-site hosting tasks, do not spend time on unrelated app/browser test suites unless the user explicitly asks or the runtime behavior itself changes; prefer workflow, build, and publish-config validation only.
 - Repo-wide .NET SDK and test-runner selection belong in the root `global.json`; do not split `global.json` test-runner opt-ins per project or subfolder once the user asks for a global test-platform policy.
 - Browser and component tests must use one selector format only: `data-test`; do not mix in any alternate test-attribute naming variants.

Directory.Packages.props

@@ -19,6 +19,7 @@
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.5" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Configuration" Version="10.0.5" />
     <PackageVersion Include="Microsoft.Playwright" Version="1.58.0" />
+    <PackageVersion Include="Sentry.AspNetCore.Blazor.WebAssembly" Version="6.3.0" />
     <PackageVersion Include="Sentry" Version="6.3.0" />
     <PackageVersion Include="Shouldly" Version="4.3.0" />
     <PackageVersion Include="TUnit" Version="1.28.7" />

src/PrompterOne.Shared/AppShell/Services/RuntimeTelemetryOptions.cs

@@ -3,17 +3,20 @@ namespace PrompterOne.Shared.Services;
 public sealed record RuntimeTelemetryOptions(
     string GoogleAnalyticsMeasurementId,
     string ClarityProjectId,
-    bool HostEnabled,
-    bool SentryConfigured)
+    string SentryDsn,
+    bool HostEnabled)
 {
     public const string ClarityProjectIdKey = "ClarityProjectId";
     public const string ConfigurationSectionName = "RuntimeTelemetry";
     public const string GoogleAnalyticsMeasurementIdKey = "GoogleAnalyticsMeasurementId";
     public const string HostEnabledKey = "HostEnabled";
+    public const string SentryDsnKey = "SentryDsn";
     public const string SectionSeparator = ":";
 
     public static RuntimeTelemetryOptions Disabled { get; } =
-        new(string.Empty, string.Empty, HostEnabled: false, SentryConfigured: false);
+        new(string.Empty, string.Empty, string.Empty, HostEnabled: false);
+
+    public bool SentryConfigured => !string.IsNullOrWhiteSpace(SentryDsn);
 
     public static string ClarityProjectIdPath =>
         string.Concat(ConfigurationSectionName, SectionSeparator, ClarityProjectIdKey);
@@ -23,4 +26,7 @@ public sealed record RuntimeTelemetryOptions(
 
     public static string HostEnabledPath =>
         string.Concat(ConfigurationSectionName, SectionSeparator, HostEnabledKey);
+
+    public static string SentryDsnPath =>
+        string.Concat(ConfigurationSectionName, SectionSeparator, SentryDsnKey);
 }

src/PrompterOne.Shared/AppShell/Services/RuntimeTelemetryService.cs

@@ -36,6 +36,7 @@ await module.InvokeVoidAsync(
                     harnessGlobalName = AppRuntimeTelemetry.Harness.GlobalName,
                     initializationsCollection = AppRuntimeTelemetry.Harness.InitializationsCollection,
                     pageViewsCollection = AppRuntimeTelemetry.Harness.PageViewsCollection,
+                    runtimeAllowVendorLoadsProperty = AppRuntimeTelemetry.Harness.RuntimeAllowVendorLoadsProperty,
                     runtimeGlobalName = AppRuntimeTelemetry.Harness.RuntimeGlobalName,
                     runtimeHarnessEnabledProperty = AppRuntimeTelemetry.Harness.RuntimeHarnessEnabledProperty,
                     runtimeWasmDebugEnabledProperty = AppRuntimeTelemetry.Harness.RuntimeWasmDebugEnabledProperty,

src/PrompterOne.Shared/Contracts/AppRuntimeTelemetry.cs

@@ -8,6 +8,7 @@ public static class Harness
         public const string GlobalName = "__prompterOneTelemetryHarness";
         public const string InitializationsCollection = "initializations";
         public const string PageViewsCollection = "pageViews";
+        public const string RuntimeAllowVendorLoadsProperty = "telemetryAllowVendorLoads";
         public const string RuntimeGlobalName = "__prompterOneRuntime";
         public const string RuntimeHarnessEnabledProperty = "telemetryHarnessEnabled";
         public const string RuntimeWasmDebugEnabledProperty = "wasmDebugEnabled";

src/PrompterOne.Shared/wwwroot/app/runtime-telemetry.js

@@ -1,14 +1,19 @@
 const clarityFunctionName = "clarity";
 const clarityProviderName = "clarity";
+const clarityScriptElementId = "prompterone-runtime-clarity";
+const clarityScriptUrlPrefix = "https://www.clarity.ms/tag/";
 const googleAnalyticsFunctionName = "gtag";
 const googleAnalyticsProviderName = "google-analytics";
+const googleAnalyticsScriptElementId = "prompterone-runtime-google-analytics";
+const googleAnalyticsScriptUrlPrefix = "https://www.googletagmanager.com/gtag/js?id=";
 const googleDataLayerName = "dataLayer";
 
 const telemetryContract = {
     eventsCollection: "",
     harnessGlobalName: "",
     initializationsCollection: "",
     pageViewsCollection: "",
+    runtimeAllowVendorLoadsProperty: "",
     runtimeGlobalName: "",
     runtimeHarnessEnabledProperty: "",
     runtimeWasmDebugEnabledProperty: "",
@@ -18,8 +23,10 @@ const telemetryContract = {
 const telemetryState = {
     clarityConfigured: false,
     clarityProjectId: "",
+    clarityScriptLoadPromise: null,
     googleAnalyticsConfigured: false,
     googleAnalyticsMeasurementId: "",
+    googleAnalyticsScriptLoadPromise: null,
     initialized: false,
     runtimeEnabled: false
 };
@@ -29,6 +36,7 @@ function applyTelemetryContract(contract) {
     telemetryContract.harnessGlobalName = contract?.harnessGlobalName ?? "";
     telemetryContract.initializationsCollection = contract?.initializationsCollection ?? "";
     telemetryContract.pageViewsCollection = contract?.pageViewsCollection ?? "";
+    telemetryContract.runtimeAllowVendorLoadsProperty = contract?.runtimeAllowVendorLoadsProperty ?? "";
     telemetryContract.runtimeGlobalName = contract?.runtimeGlobalName ?? "";
     telemetryContract.runtimeHarnessEnabledProperty = contract?.runtimeHarnessEnabledProperty ?? "";
     telemetryContract.runtimeWasmDebugEnabledProperty = contract?.runtimeWasmDebugEnabledProperty ?? "";
@@ -48,6 +56,14 @@ function getRuntime() {
     return window[telemetryContract.runtimeGlobalName] ?? {};
 }
 
+function areVendorLoadsAllowed() {
+    return getRuntime()[telemetryContract.runtimeAllowVendorLoadsProperty] === true;
+}
+
+function shouldBlockVendorLoads() {
+    return getHarness() !== null && !areVendorLoadsAllowed();
+}
+
 function ensureHarnessCollection(name) {
     const harness = getHarness();
     if (harness === null) {
@@ -91,12 +107,70 @@ function installClarityStub() {
     window[clarityFunctionName] = clarityStub;
 }
 
-function recordBlockedVendorLoad(provider) {
+function recordVendorLoad(provider, blocked, url) {
     recordHarnessEntry(telemetryContract.vendorLoadsCollection, {
-        blocked: true,
+        blocked,
         provider,
-        url: ""
+        url
+    });
+}
+
+function buildGoogleAnalyticsScriptUrl(measurementId) {
+    return `${googleAnalyticsScriptUrlPrefix}${encodeURIComponent(measurementId)}`;
+}
+
+function buildClarityScriptUrl(projectId) {
+    return `${clarityScriptUrlPrefix}${encodeURIComponent(projectId)}`;
+}
+
+function loadExternalScript(provider, url, elementId, promisePropertyName) {
+    const existingPromise = telemetryState[promisePropertyName];
+    if (existingPromise !== null) {
+        return existingPromise;
+    }
+
+    const loadPromise = new Promise((resolve, reject) => {
+        const handleError = () => reject(new Error(`${provider} failed to load.`));
+
+        const existingElement = document.getElementById(elementId);
+        if (existingElement instanceof HTMLScriptElement) {
+            if (existingElement.dataset.prompterOneLoaded === "true") {
+                resolve();
+                return;
+            }
+
+            if (existingElement.dataset.prompterOneFailed === "true") {
+                handleError();
+                return;
+            }
+
+            existingElement.addEventListener("load", resolve, { once: true });
+            existingElement.addEventListener("error", handleError, { once: true });
+            return;
+        }
+
+        const scriptElement = document.createElement("script");
+        scriptElement.async = true;
+        scriptElement.id = elementId;
+        scriptElement.src = url;
+        scriptElement.addEventListener("load", () => {
+            scriptElement.dataset.prompterOneLoaded = "true";
+            resolve();
+        }, { once: true });
+        scriptElement.addEventListener("error", () => {
+            scriptElement.dataset.prompterOneFailed = "true";
+            handleError();
+        }, { once: true });
+
+        recordVendorLoad(provider, false, url);
+        (document.head ?? document.documentElement).appendChild(scriptElement);
+    }).catch(error => {
+        telemetryState[promisePropertyName] = null;
+        throw error;
     });
+
+    telemetryState[promisePropertyName] = loadPromise;
+    return loadPromise;
 }
 
 async function ensureGoogleAnalyticsConfigured() {
@@ -105,7 +179,22 @@ async function ensureGoogleAnalyticsConfigured() {
     }
 
     installGoogleAnalyticsStub();
-    recordBlockedVendorLoad(googleAnalyticsProviderName);
+
+    if (shouldBlockVendorLoads()) {
+        recordVendorLoad(googleAnalyticsProviderName, true, "");
+    }
+    else {
+        try {
+            await loadExternalScript(
+                googleAnalyticsProviderName,
+                buildGoogleAnalyticsScriptUrl(telemetryState.googleAnalyticsMeasurementId),
+                googleAnalyticsScriptElementId,
+                "googleAnalyticsScriptLoadPromise");
+        }
+        catch {
+            return;
+        }
+    }
 
     window[googleAnalyticsFunctionName]("js", new Date());
     window[googleAnalyticsFunctionName]("config", telemetryState.googleAnalyticsMeasurementId, { send_page_view: false });
@@ -118,7 +207,23 @@ async function ensureClarityConfigured() {
     }
 
     installClarityStub();
-    recordBlockedVendorLoad(clarityProviderName);
+
+    if (shouldBlockVendorLoads()) {
+        recordVendorLoad(clarityProviderName, true, "");
+        telemetryState.clarityConfigured = true;
+        return;
+    }
+
+    try {
+        await loadExternalScript(
+            clarityProviderName,
+            buildClarityScriptUrl(telemetryState.clarityProjectId),
+            clarityScriptElementId,
+            "clarityScriptLoadPromise");
+    }
+    catch {
+        return;
+    }
 
     telemetryState.clarityConfigured = true;
 }
@@ -128,9 +233,9 @@ function buildInitializationSnapshot(config) {
     const sentryConfigured = config?.sentryConfigured === true;
 
     return {
-        clarityConfigured: Boolean(config?.clarityProjectId),
+        clarityConfigured: telemetryState.clarityConfigured,
         debugEnabled: runtime[telemetryContract.runtimeWasmDebugEnabledProperty] === true,
-        googleAnalyticsConfigured: Boolean(config?.googleAnalyticsMeasurementId),
+        googleAnalyticsConfigured: telemetryState.googleAnalyticsConfigured,
         hostEnabled: config?.hostEnabled === true,
         runtimeEnabled: telemetryState.runtimeEnabled,
         sentryConfigured,
@@ -155,14 +260,14 @@ export async function initializeRuntimeTelemetry(config) {
         config?.hostEnabled === true
         && getRuntime()[telemetryContract.runtimeWasmDebugEnabledProperty] !== true;
 
-    recordHarnessEntry(telemetryContract.initializationsCollection, buildInitializationSnapshot(config));
-
     if (!telemetryState.runtimeEnabled) {
+        recordHarnessEntry(telemetryContract.initializationsCollection, buildInitializationSnapshot(config));
         return false;
     }
 
     await ensureGoogleAnalyticsConfigured();
     await ensureClarityConfigured();
+    recordHarnessEntry(telemetryContract.initializationsCollection, buildInitializationSnapshot(config));
     return true;
 }
 
@@ -183,6 +288,6 @@ async function trackRuntimeTelemetryEventInternal(eventName, payload, harnessCol
 
     const normalizedPayload = normalizePayload(eventName, payload);
     recordHarnessEntry(harnessCollectionName, normalizedPayload);
-    window[googleAnalyticsFunctionName]("event", eventName, payload ?? {});
+    window[googleAnalyticsFunctionName]("event", eventName, normalizedPayload);
     return true;
 }

src/PrompterOne.Web/Program.cs

@@ -23,15 +23,16 @@
 var runtimeTelemetryOptions = new RuntimeTelemetryOptions(
     builder.Configuration[RuntimeTelemetryOptions.GoogleAnalyticsMeasurementIdPath] ?? string.Empty,
     builder.Configuration[RuntimeTelemetryOptions.ClarityProjectIdPath] ?? string.Empty,
-    HostEnabled: runtimeTelemetryHostEnabled,
-    SentryConfigured: RuntimeSentryBootstrapper.IsConfigured);
+    builder.Configuration[RuntimeTelemetryOptions.SentryDsnPath] ?? string.Empty,
+    HostEnabled: runtimeTelemetryHostEnabled);
 
 builder.Services.AddLocalization();
 builder.Services.AddSingleton<IFormFactor, FormFactor>();
 builder.Services.AddSingleton<IAppVersionProvider>(_ => AppVersionProviderFactory.CreateFromAssembly(typeof(Program).Assembly));
 builder.Services.AddPrompterOneShared(runtimeTelemetryOptions);
+RuntimeSentryBootstrapper.Configure(builder, runtimeTelemetryOptions);
 
 var host = builder.Build();
-using var sentry = RuntimeSentryBootstrapper.Initialize(host.Services, runtimeTelemetryHostEnabled);
+RuntimeSentryBootstrapper.DisableForWasmDebug(host.Services);
 await host.Services.GetRequiredService<AppCulturePreferenceService>().InitializeAsync();
 await host.RunAsync();

src/PrompterOne.Web/PrompterOne.Web.csproj

@@ -10,7 +10,7 @@
     <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" PrivateAssets="all" />
     <PackageReference Include="Microsoft.Extensions.Localization" />
     <PackageReference Include="Microsoft.Extensions.Logging.Configuration" />
-    <PackageReference Include="Sentry" />
+    <PackageReference Include="Sentry.AspNetCore.Blazor.WebAssembly" />
   </ItemGroup>
 
   <ItemGroup>

src/PrompterOne.Web/Services/RuntimeSentryBootstrapper.cs

@@ -1,51 +1,59 @@
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
+using PrompterOne.Shared.Services;
 using PrompterOne.Shared.Settings.Services;
 
 namespace PrompterOne.Web.Services;
 
 internal static class RuntimeSentryBootstrapper
 {
-    private const string Dsn =
-        "https://cc172c8c1921c7a979dfbb12ca80379f@o4511168317030400.ingest.de.sentry.io/4511168321749072";
     private const char QueryPairSeparator = '&';
     private const char QueryPrefix = '?';
     private const char QueryValueSeparator = '=';
     private const string WasmDebugEnabledValue = "1";
     private const string WasmDebugQueryKey = "wasm-debug";
 
-    public static bool IsConfigured => !string.IsNullOrWhiteSpace(Dsn);
-
-    public static IDisposable? Initialize(IServiceProvider services, bool hostEnabled)
+    public static void Configure(WebAssemblyHostBuilder builder, RuntimeTelemetryOptions telemetryOptions)
     {
-        if (!hostEnabled || !IsConfigured)
-        {
-            return null;
-        }
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(telemetryOptions);
 
-        var hostEnvironment = services.GetRequiredService<IWebAssemblyHostEnvironment>();
-        if (hostEnvironment.IsDevelopment())
+        if (!ShouldEnable(builder.HostEnvironment, telemetryOptions))
         {
-            return null;
+            return;
         }
 
-        var navigationManager = services.GetRequiredService<NavigationManager>();
-        if (IsWasmDebugEnabled(navigationManager.Uri))
-        {
-            return null;
-        }
+        var release = AppVersionProviderFactory
+            .CreateFromAssembly(typeof(RuntimeSentryBootstrapper).Assembly)
+            .Current
+            .Version;
 
-        var appVersionProvider = services.GetRequiredService<IAppVersionProvider>();
-        return SentrySdk.Init(options =>
+        builder.UseSentry(options =>
         {
-            options.Dsn = Dsn;
+            options.Dsn = telemetryOptions.SentryDsn;
             options.Debug = false;
             options.AutoSessionTracking = true;
-            options.Environment = hostEnvironment.Environment;
-            options.Release = appVersionProvider.Current.Version;
+            options.Environment = builder.HostEnvironment.Environment;
+            options.Release = release;
         });
     }
 
+    public static void DisableForWasmDebug(IServiceProvider services)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+
+        var navigationManager = services.GetRequiredService<NavigationManager>();
+        if (IsWasmDebugEnabled(navigationManager.Uri))
+        {
+            SentrySdk.Close();
+        }
+    }
+
+    private static bool ShouldEnable(IWebAssemblyHostEnvironment hostEnvironment, RuntimeTelemetryOptions telemetryOptions) =>
+        telemetryOptions.HostEnabled
+        && telemetryOptions.SentryConfigured
+        && !hostEnvironment.IsDevelopment();
+
     private static bool IsWasmDebugEnabled(string uri) =>
         string.Equals(ResolveQueryValue(uri, WasmDebugQueryKey), WasmDebugEnabledValue, StringComparison.Ordinal);
 

src/PrompterOne.Web/wwwroot/appsettings.Development.json

@@ -8,6 +8,7 @@
   "RuntimeTelemetry": {
     "HostEnabled": false,
     "GoogleAnalyticsMeasurementId": "",
-    "ClarityProjectId": ""
+    "ClarityProjectId": "",
+    "SentryDsn": ""
   }
 }