feat(Telemetry): implement no-op telemetry client and runtime gate for mobile

BAKAOLC · BAKAOLC · commit 0eb9e504e4b8 · 2026-05-20T19:20:51.000+08:00
- Introduced NoOpTelemetryClient to handle telemetry requests when telemetry is disabled on mobile.
- Added TelemetryRuntimeGate to manage telemetry functionality based on mobile host status.
- Updated various telemetry methods to return early if telemetry is disabled, improving performance and preventing unnecessary operations.
- Enhanced existing telemetry methods to respect the new runtime gate, ensuring consistent behavior across the telemetry system.
diff --git a/Telemetry/Consent/TelemetryConsentStore.cs b/Telemetry/Consent/TelemetryConsentStore.cs
@@ -10,6 +10,9 @@ internal static class TelemetryConsentStore
 
         internal static TelemetryConsentDocument Snapshot()
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return new();
+
             lock (Sync)
             {
                 EnsureLoaded();
@@ -19,6 +22,9 @@ internal static TelemetryConsentDocument Snapshot()
 
         internal static TelemetryApplicantConsent GetApplicantConsent(string applicantId)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return new() { Consent = TelemetryConsentState.Denied };
+
             lock (Sync)
             {
                 EnsureLoaded();
@@ -28,6 +34,9 @@ internal static TelemetryApplicantConsent GetApplicantConsent(string applicantId
 
         internal static bool IsRequestGranted(TelemetryApplicant applicant, TelemetryRequest request)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return false;
+
             lock (Sync)
             {
                 EnsureLoaded();
@@ -42,6 +51,9 @@ internal static bool IsSharedContributionGranted(
             string contributorModId,
             string contributionId)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return false;
+
             lock (Sync)
             {
                 EnsureLoaded();
@@ -57,6 +69,9 @@ public static void SetApplicantConsent(
             TelemetryConsentState state,
             IEnumerable<string>? grantedRequests = null)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             lock (Sync)
             {
                 EnsureLoaded();
@@ -85,6 +100,9 @@ public static void SetSharedContributionConsent(
             string contributionId,
             bool granted)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             lock (Sync)
             {
                 EnsureLoaded();
diff --git a/Telemetry/Core/NoOpTelemetryClient.cs b/Telemetry/Core/NoOpTelemetryClient.cs
@@ -0,0 +1,35 @@
+using System.Text.Json.Nodes;
+
+namespace STS2RitsuLib.Telemetry
+{
+    internal sealed class NoOpTelemetryClient(string applicantId) : ITelemetryClient
+    {
+        public string ApplicantId { get; } = applicantId;
+
+        public bool IsEnabled(string requestId)
+        {
+            return false;
+        }
+
+        public void Capture(
+            string eventName,
+            string requestId,
+            IReadOnlyDictionary<string, object?>? properties = null)
+        {
+        }
+
+        public void CapturePayload(
+            string eventName,
+            string requestId,
+            JsonNode payload,
+            IReadOnlyDictionary<string, object?>? properties = null)
+        {
+        }
+
+        public void CaptureException(
+            Exception exception,
+            IReadOnlyDictionary<string, object?>? properties = null)
+        {
+        }
+    }
+}
diff --git a/Telemetry/Core/TelemetryApi.cs b/Telemetry/Core/TelemetryApi.cs
@@ -16,6 +16,9 @@ public static class TelemetryApi
         public static ITelemetryClient GetClient(string applicantId)
         {
             ArgumentException.ThrowIfNullOrWhiteSpace(applicantId);
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return new NoOpTelemetryClient(applicantId);
+
             return new TelemetryClient(applicantId);
         }
 
@@ -29,6 +32,9 @@ public static void CaptureVanillaRunHistory(
             JsonNode? applicantPayload = null,
             IReadOnlyDictionary<string, object?>? properties = null)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             RunHistoryTelemetryCollector.CaptureVanillaRunHistory(
                 applicantId,
                 runHistory,
diff --git a/Telemetry/Core/TelemetryRegistry.cs b/Telemetry/Core/TelemetryRegistry.cs
@@ -23,6 +23,9 @@ public static class TelemetryRegistry
         public static void RegisterApplicant(TelemetryApplicant applicant)
         {
             ArgumentNullException.ThrowIfNull(applicant);
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             ArgumentException.ThrowIfNullOrWhiteSpace(applicant.ApplicantId);
             ArgumentException.ThrowIfNullOrWhiteSpace(applicant.OwnerModId);
             ArgumentException.ThrowIfNullOrWhiteSpace(applicant.DisplayName);
@@ -45,6 +48,9 @@ public static void RegisterApplicant(TelemetryApplicant applicant)
         public static void RegisterContributionProvider(ITelemetryContributionProvider provider)
         {
             ArgumentNullException.ThrowIfNull(provider);
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             ArgumentException.ThrowIfNullOrWhiteSpace(provider.ContributorModId);
             ArgumentException.ThrowIfNullOrWhiteSpace(provider.ContributionId);
             lock (Sync)
diff --git a/Telemetry/Core/TelemetryRuntime.cs b/Telemetry/Core/TelemetryRuntime.cs
@@ -20,6 +20,9 @@ internal static class TelemetryRuntime
         /// </summary>
         internal static void CaptureStartupSnapshot()
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             lock (Sync)
             {
                 if (_startupSnapshot != null)
@@ -42,6 +45,9 @@ internal static void CaptureStartupSnapshot()
         /// </summary>
         internal static void ReplayStartupSnapshotToAuthorizedApplicants()
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
+
             foreach (var applicant in TelemetryRegistry.GetApplicants())
                 ReplayStartupSnapshotToApplicant(applicant.ApplicantId);
         }
@@ -52,6 +58,9 @@ internal static void ReplayStartupSnapshotToAuthorizedApplicants()
         /// </summary>
         internal static void RefreshStartupModInventorySnapshot(string reason)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
+
             lock (Sync)
             {
                 if (_startupSnapshot == null)
@@ -72,6 +81,9 @@ internal static void RefreshStartupModInventorySnapshot(string reason)
         /// </summary>
         internal static void ReplayStartupSnapshotToApplicant(string applicantId)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
+
             StartupTelemetrySnapshot snapshot;
 
             lock (Sync)
@@ -105,6 +117,9 @@ internal static void ReplayStartupSnapshotToApplicant(string applicantId)
         /// </summary>
         internal static void ResetStartupDeliveryForDiscardedEvents(IEnumerable<TelemetryEnvelope> events)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
+
             var discardedKeys = events
                 .Select(BuildStartupDeliveryKey)
                 .Where(key => key != null)
@@ -126,6 +141,9 @@ internal static void ResetStartupDeliveryForDiscardedEvents(IEnumerable<Telemetr
         /// </summary>
         internal static void MarkStartupDeliveryConfirmed(IEnumerable<TelemetryEnvelope> events)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
+
             var confirmedKeys = events
                 .Select(BuildStartupDeliveryKey)
                 .Where(key => key != null)
diff --git a/Telemetry/Core/TelemetryRuntimeGate.cs b/Telemetry/Core/TelemetryRuntimeGate.cs
@@ -0,0 +1,40 @@
+using STS2RitsuLib.Platform;
+
+namespace STS2RitsuLib.Telemetry
+{
+    internal static class TelemetryRuntimeGate
+    {
+        internal const string MobileDisabledReason = "Telemetry is disabled on mobile hosts.";
+
+        private static readonly Lock Sync = new();
+        private static bool _loggedMobileDisabled;
+
+        internal static bool IsDisabled => RitsuLibMobileSteamRuntime.SuppressNativeSteamIntegration;
+
+        internal static bool TryNoOpForDisabledMobile()
+        {
+            if (!IsDisabled)
+                return false;
+
+            LogDisabledOnce();
+            return true;
+        }
+
+        internal static void LogDisabledOnce()
+        {
+            if (!IsDisabled)
+                return;
+
+            lock (Sync)
+            {
+                if (_loggedMobileDisabled)
+                    return;
+
+                _loggedMobileDisabled = true;
+            }
+
+            RitsuLibFramework.Logger.Info(
+                "[Telemetry] Telemetry is disabled on mobile hosts; telemetry APIs will run as no-op.");
+        }
+    }
+}
diff --git a/Telemetry/Diagnostics/DiagnosticsTelemetryCollector.cs b/Telemetry/Diagnostics/DiagnosticsTelemetryCollector.cs
@@ -62,6 +62,8 @@ internal static void CaptureExceptionForAuthorizedApplicants(Exception exception
         {
             ArgumentNullException.ThrowIfNull(exception);
             ArgumentException.ThrowIfNullOrWhiteSpace(source);
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
 
             try
             {
@@ -100,6 +102,9 @@ internal static void CaptureExceptionForAuthorizedApplicants(Exception exception
 
         internal static void InitializeGlobalExceptionHandlers()
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             lock (Sync)
             {
                 if (_globalHandlersInitialized)
diff --git a/Telemetry/Integration/RitsuLibTelemetryBootstrap.cs b/Telemetry/Integration/RitsuLibTelemetryBootstrap.cs
@@ -24,6 +24,9 @@ internal static void Initialize()
                 return;
 
             _initialized = true;
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             DiagnosticsTelemetryCollector.InitializeGlobalExceptionHandlers();
             RitsuLibFramework.SubscribeLifecycle<RunEndedEvent>(RunHistoryTelemetryCollector.CaptureEndedRun);
             RitsuLibFramework.SubscribeLifecycleOnce<MainMenuReadyEvent>(_ => InitializeMainMenuTelemetry());
diff --git a/Telemetry/Integration/RitsuLibTelemetryConfiguration.cs b/Telemetry/Integration/RitsuLibTelemetryConfiguration.cs
@@ -6,6 +6,9 @@ internal static class RitsuLibTelemetryConfiguration
 
         internal static ITelemetryAdapter CreateAdapter()
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return new DisabledTelemetryAdapter(TelemetryRuntimeGate.MobileDisabledReason);
+
             return new HttpJsonTelemetryAdapter(DefaultIngestEndpoint);
         }
     }
diff --git a/Telemetry/Queue/TelemetryQueue.cs b/Telemetry/Queue/TelemetryQueue.cs
@@ -11,6 +11,9 @@ internal static class TelemetryQueue
 
         internal static void Enqueue(TelemetryEnvelope envelope)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             lock (Sync)
             {
                 var doc = ReadQueue(envelope.ApplicantId);
@@ -25,6 +28,9 @@ internal static void Enqueue(TelemetryEnvelope envelope)
 
         public static async Task FlushApplicantAsync(string applicantId, CancellationToken cancellationToken = default)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             TelemetryApplicant applicant;
 
             lock (Sync)
@@ -133,12 +139,18 @@ public static async Task FlushApplicantAsync(string applicantId, CancellationTok
 
         public static async Task FlushAllAsync(CancellationToken cancellationToken = default)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             foreach (var applicant in TelemetryRegistry.GetApplicants())
                 await FlushApplicantAsync(applicant.ApplicantId, cancellationToken);
         }
 
         public static void ClearApplicant(string applicantId)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             lock (Sync)
             {
                 var doc = ReadQueue(applicantId);
@@ -150,6 +162,9 @@ public static void ClearApplicant(string applicantId)
 
         public static int GetQueuedEventCount(string applicantId)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return 0;
+
             lock (Sync)
             {
                 return ReadQueue(applicantId).Events.Count;
diff --git a/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs b/Telemetry/RunHistory/RunHistoryTelemetryCollector.cs
@@ -164,6 +164,9 @@ public static void CaptureVanillaRunHistory(
             JsonNode? applicantPayload = null,
             IReadOnlyDictionary<string, object?>? properties = null)
         {
+            if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())
+                return;
+
             ArgumentException.ThrowIfNullOrWhiteSpace(applicantId);
             ArgumentNullException.ThrowIfNull(runHistory);
 
@@ -190,6 +193,9 @@ public static void CaptureVanillaRunHistory(
 
         internal static void CaptureEndedRun(RunEndedEvent evt)
         {
+            if (TelemetryRuntimeGate.IsDisabled)
+                return;
+
             JsonNode? runHistory;
             try
             {

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,9 @@ internal static class TelemetryConsentStore`
`10`	`10`
`11`	`11`	`internal static TelemetryConsentDocument Snapshot()`
`12`	`12`	`{`
	`13`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`14`	`+ return new();`
	`15`	`+`
`13`	`16`	`lock (Sync)`
`14`	`17`	`{`
`15`	`18`	`EnsureLoaded();`
`@@ -19,6 +22,9 @@ internal static TelemetryConsentDocument Snapshot()`
`19`	`22`
`20`	`23`	`internal static TelemetryApplicantConsent GetApplicantConsent(string applicantId)`
`21`	`24`	`{`
	`25`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`26`	`+ return new() { Consent = TelemetryConsentState.Denied };`
	`27`	`+`
`22`	`28`	`lock (Sync)`
`23`	`29`	`{`
`24`	`30`	`EnsureLoaded();`
`@@ -28,6 +34,9 @@ internal static TelemetryApplicantConsent GetApplicantConsent(string applicantId`
`28`	`34`
`29`	`35`	`internal static bool IsRequestGranted(TelemetryApplicant applicant, TelemetryRequest request)`
`30`	`36`	`{`
	`37`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`38`	`+ return false;`
	`39`	`+`
`31`	`40`	`lock (Sync)`
`32`	`41`	`{`
`33`	`42`	`EnsureLoaded();`
`@@ -42,6 +51,9 @@ internal static bool IsSharedContributionGranted(`
`42`	`51`	`string contributorModId,`
`43`	`52`	`string contributionId)`
`44`	`53`	`{`
	`54`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`55`	`+ return false;`
	`56`	`+`
`45`	`57`	`lock (Sync)`
`46`	`58`	`{`
`47`	`59`	`EnsureLoaded();`
`@@ -57,6 +69,9 @@ public static void SetApplicantConsent(`
`57`	`69`	`TelemetryConsentState state,`
`58`	`70`	`IEnumerable<string>? grantedRequests = null)`
`59`	`71`	`{`
	`72`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`73`	`+ return;`
	`74`	`+`
`60`	`75`	`lock (Sync)`
`61`	`76`	`{`
`62`	`77`	`EnsureLoaded();`
`@@ -85,6 +100,9 @@ public static void SetSharedContributionConsent(`
`85`	`100`	`string contributionId,`
`86`	`101`	`bool granted)`
`87`	`102`	`{`
	`103`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`104`	`+ return;`
	`105`	`+`
`88`	`106`	`lock (Sync)`
`89`	`107`	`{`
`90`	`108`	`EnsureLoaded();`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,9 @@ public static class TelemetryApi`
`16`	`16`	`public static ITelemetryClient GetClient(string applicantId)`
`17`	`17`	`{`
`18`	`18`	`ArgumentException.ThrowIfNullOrWhiteSpace(applicantId);`
	`19`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`20`	`+ return new NoOpTelemetryClient(applicantId);`
	`21`	`+`
`19`	`22`	`return new TelemetryClient(applicantId);`
`20`	`23`	`}`
`21`	`24`
`@@ -29,6 +32,9 @@ public static void CaptureVanillaRunHistory(`
`29`	`32`	`JsonNode? applicantPayload = null,`
`30`	`33`	`IReadOnlyDictionary<string, object?>? properties = null)`
`31`	`34`	`{`
	`35`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`36`	`+ return;`
	`37`	`+`
`32`	`38`	`RunHistoryTelemetryCollector.CaptureVanillaRunHistory(`
`33`	`39`	`applicantId,`
`34`	`40`	`runHistory,`
Original file line number	Diff line number	Diff line change
`@@ -62,6 +62,8 @@ internal static void CaptureExceptionForAuthorizedApplicants(Exception exception`
`62`	`62`	`{`
`63`	`63`	`ArgumentNullException.ThrowIfNull(exception);`
`64`	`64`	`ArgumentException.ThrowIfNullOrWhiteSpace(source);`
	`65`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`66`	`+ return;`
`65`	`67`
`66`	`68`	`try`
`67`	`69`	`{`
`@@ -100,6 +102,9 @@ internal static void CaptureExceptionForAuthorizedApplicants(Exception exception`
`100`	`102`
`101`	`103`	`internal static void InitializeGlobalExceptionHandlers()`
`102`	`104`	`{`
	`105`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`106`	`+ return;`
	`107`	`+`
`103`	`108`	`lock (Sync)`
`104`	`109`	`{`
`105`	`110`	`if (_globalHandlersInitialized)`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,9 @@ internal static class RitsuLibTelemetryConfiguration`
`6`	`6`
`7`	`7`	`internal static ITelemetryAdapter CreateAdapter()`
`8`	`8`	`{`
	`9`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`10`	`+ return new DisabledTelemetryAdapter(TelemetryRuntimeGate.MobileDisabledReason);`
	`11`	`+`
`9`	`12`	`return new HttpJsonTelemetryAdapter(DefaultIngestEndpoint);`
`10`	`13`	`}`
`11`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,9 @@ internal static class TelemetryQueue`
`11`	`11`
`12`	`12`	`internal static void Enqueue(TelemetryEnvelope envelope)`
`13`	`13`	`{`
	`14`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`15`	`+ return;`
	`16`	`+`
`14`	`17`	`lock (Sync)`
`15`	`18`	`{`
`16`	`19`	`var doc = ReadQueue(envelope.ApplicantId);`
`@@ -25,6 +28,9 @@ internal static void Enqueue(TelemetryEnvelope envelope)`
`25`	`28`
`26`	`29`	`public static async Task FlushApplicantAsync(string applicantId, CancellationToken cancellationToken = default)`
`27`	`30`	`{`
	`31`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`32`	`+ return;`
	`33`	`+`
`28`	`34`	`TelemetryApplicant applicant;`
`29`	`35`
`30`	`36`	`lock (Sync)`
`@@ -133,12 +139,18 @@ public static async Task FlushApplicantAsync(string applicantId, CancellationTok`
`133`	`139`
`134`	`140`	`public static async Task FlushAllAsync(CancellationToken cancellationToken = default)`
`135`	`141`	`{`
	`142`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`143`	`+ return;`
	`144`	`+`
`136`	`145`	`foreach (var applicant in TelemetryRegistry.GetApplicants())`
`137`	`146`	`await FlushApplicantAsync(applicant.ApplicantId, cancellationToken);`
`138`	`147`	`}`
`139`	`148`
`140`	`149`	`public static void ClearApplicant(string applicantId)`
`141`	`150`	`{`
	`151`	`+ if (TelemetryRuntimeGate.TryNoOpForDisabledMobile())`
	`152`	`+ return;`
	`153`	`+`
`142`	`154`	`lock (Sync)`
`143`	`155`	`{`
`144`	`156`	`var doc = ReadQueue(applicantId);`
`@@ -150,6 +162,9 @@ public static void ClearApplicant(string applicantId)`
`150`	`162`
`151`	`163`	`public static int GetQueuedEventCount(string applicantId)`
`152`	`164`	`{`
	`165`	`+ if (TelemetryRuntimeGate.IsDisabled)`
	`166`	`+ return 0;`
	`167`	`+`
`153`	`168`	`lock (Sync)`
`154`	`169`	`{`
`155`	`170`	`return ReadQueue(applicantId).Events.Count;`