diff --git a/CHANGELOG.md b/CHANGELOG.md index 35a786754..8678c2e19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## Unreleased + +### Features + +- Experimental session replay on Android ([#2948](https://github.com/getsentry/sentry-unity/pull/2948)): + - Set `options.Experimental.SessionReplay.SessionSampleRate` or `OnErrorSampleRate` in code, + in the options used both at build time and at runtime. + - The Android SDK records the game, and errors captured in C# send the replay of the moments before them, + like native errors do. + - Session replay requires runtime initialization of the Android SDK and adds the Kotlin standard library to the build. + - By default, the Android SDK captures the frames; with `Capture = SessionReplayCapture.Unity`, + Unity captures them instead. + ## 4.13.0 ### Behavioral Changes diff --git a/build/native-sdks.targets b/build/native-sdks.targets index f15748bd4..bf9aea0f5 100644 --- a/build/native-sdks.targets +++ b/build/native-sdks.targets @@ -294,6 +294,7 @@ + @@ -302,16 +303,18 @@ - + + + diff --git a/docs/agent-guides/platform-android.md b/docs/agent-guides/platform-android.md index 02c4dda75..54fb565ed 100644 --- a/docs/agent-guides/platform-android.md +++ b/docs/agent-guides/platform-android.md @@ -20,6 +20,60 @@ The Java layer disables duplicate screenshots, auto-session tracking, activity lifecycle breadcrumbs, and user-interaction breadcrumbs/tracing because Unity/.NET owns them. +## Session Replay (Experimental) + +- `options.Experimental.SessionReplay` is set from code, with no editor UI. + Replay is enabled when `SessionSampleRate` or `OnErrorSampleRate` is above 0. +- Packaging: + - `sentry-android-replay-release.aar` ships in `Sentry~` next to the other artifacts. + - `GradleSetup` adds it to `unityLibrary/build.gradle` only when replay is enabled in the build-time options, + together with `org.jetbrains.kotlin:kotlin-stdlib` from Maven, at the version sentry-android-replay builds with. + - Without replay, the Sentry dependency block is unchanged. + - Adding and clearing recognize both variants of the block, + so a persisted Gradle project follows replay and native support being toggled. +- Replay is runtime-init only: + - `SentryJava.Init` configures the replay options: sample rates, quality, + and SurfaceView capture when sentry-java captures the frames, since Unity renders into a SurfaceView. + - Build-time and external initialization log that replay is ignored. + - A missing replay library logs an error asking to enable replay in the build-time options. +- Unity capture (`Capture = SessionReplayCapture.Unity`): + - Without `SystemInfo.supportsAsyncGPUReadback`, `SentryJava.Init` logs a warning and sentry-java captures instead. + - `UnityReplayRecorder` replaces the `ReplayIntegration` sentry-java added with one built through JNI + around a custom `Recorder`: a Unity `AndroidJavaProxy`, returned by a `kotlin.jvm.functions.Function0` proxy. + - sentry-java calls the recorder on Android's UI thread, which only updates flags and the frame config. + - sentry-java never sends a custom recorder a frame config. After each start or reset, + and when Unity's screen size changes, Unity's main thread asks the UI thread to call `onWindowSizeChanged` + with the activity window's size, and sentry-java computes the config from it. + Before the window is laid out, Unity's screen size stands in once, and a later frame asks again. + - It gets the window's size, not `Screen.width/height`, which can be a lower render resolution: + sentry-java scales recorded touches, which are in window pixels, by that config. + - At the config's frame rate, Unity's main thread captures the screen at end of frame, + blits it top-down into an RGBA render texture at the recording size (`SentryScreenshot.BlitScreen`) + and reads it back with `AsyncGPUReadback`. + - A worker thread attached to the JVM copies each frame into a new `ARGB_8888` bitmap + and calls `onScreenshotRecorded`. + - A started recorder captures until it's paused: sentry-java only resumes a paused one. +- `proguard-sentry-unity.pro` keeps the replay classes Unity reaches through JNI and proxies, + and the classes in the JNI signatures it looks up (`ICurrentDateProvider`, `Integration`, `Function0`, `Function1`): + keeping a method doesn't keep the classes in its signature, so minified builds would rename them. +- Replays for C# errors: + - sentry-java samples and starts the replay itself. + - `AndroidReplaySession` is the .NET SDK's replay session: the replay id of the dynamic sampling context + comes from the Java scope. + - The .NET client calls `captureReplay` for each error event + and puts the returned replay id on that event's dynamic sampling context. + Other events get the Java scope's current replay id. +- Background and foreground: + - Unity builds don't start androidx's process lifecycle (the `lifecycle-process` startup provider isn't in the + manifest), so the Java SDK doesn't see the app go to the background. + When it isn't running, Unity's pause and resume drive the replay instead. + - A pause is the replay's manual pause. sentry-java resumes a replay paused for the background + when the device reconnects, which happens in the background too, but not a manually paused one. + - Resuming moves the replay's timeline to the return, so no segment covers the time away. + - After a background longer than `AutoSessionTrackingInterval`, the replay is resumed and then ended right away + (`onAppForegrounded(true)`), so it ends at the pause without a segment for the time away, and a new one starts. + - Unity capture drops frames read back or handed over after the pause, so none lands after the pause segment. + ## Constraints - Android native ANR and C# ANR monitor different threads; both can report one full hang. diff --git a/package-dev/Plugins/Android/proguard-sentry-unity.pro b/package-dev/Plugins/Android/proguard-sentry-unity.pro index 38aa01486..773aa803e 100644 --- a/package-dev/Plugins/Android/proguard-sentry-unity.pro +++ b/package-dev/Plugins/Android/proguard-sentry-unity.pro @@ -20,4 +20,22 @@ -keep class io.sentry.protocol.** { *; } -keep class io.sentry.android.core.internal.util.AndroidConnectionStatusProvider { *; } -keep class io.sentry.android.core.internal.util.NetworkConnection { *; } +# Experimental session replay: options, the replay controller and the recorder Unity can provide. +-keep class io.sentry.SentryReplayOptions { *; } +-keep class io.sentry.SentryReplayOptions$SentryReplayQuality { *; } +-keep interface io.sentry.ReplayController { *; } +-keep class io.sentry.transport.CurrentDateProvider { *; } +-keep class io.sentry.android.replay.ReplayIntegration { *; } +-keep interface io.sentry.android.replay.Recorder { *; } +-keep class io.sentry.android.replay.ScreenshotRecorderConfig { *; } +-keep interface kotlin.jvm.functions.Function0 { *; } +# The classes in the JNI signatures of the ReplayIntegration constructor and SentryOptions.addIntegration. +-keep interface io.sentry.transport.ICurrentDateProvider { *; } +-keep interface io.sentry.Integration { *; } +-keep interface kotlin.jvm.functions.Function1 { *; } +# Unity checks whether androidx's process lifecycle runs, to pause the replay itself when it doesn't. +-keep class androidx.lifecycle.ProcessLifecycleOwner { *; } +-keep class androidx.lifecycle.Lifecycle { *; } +-keep class androidx.lifecycle.Lifecycle$State { *; } +-dontwarn androidx.lifecycle.** -dontwarn io.sentry.** diff --git a/samples/unity-of-bugs-local/ProjectSettings/ProjectSettings.asset b/samples/unity-of-bugs-local/ProjectSettings/ProjectSettings.asset index 51541be21..c6bfdd556 100644 --- a/samples/unity-of-bugs-local/ProjectSettings/ProjectSettings.asset +++ b/samples/unity-of-bugs-local/ProjectSettings/ProjectSettings.asset @@ -147,7 +147,7 @@ PlayerSettings: vrSettings: enable360StereoCapture: 0 isWsaHolographicRemotingEnabled: 0 - enableFrameTimingStats: 0 + enableFrameTimingStats: 1 enableOpenGLProfilerGPURecorders: 1 useHDRDisplay: 0 D3DHDRBitDepth: 0 diff --git a/samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs b/samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs new file mode 100644 index 000000000..42c8f4de8 --- /dev/null +++ b/samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs @@ -0,0 +1,151 @@ +#if UNITY_ANDROID && !UNITY_EDITOR +using System.Collections.Generic; +using UnityEngine; +using UnityEngine.UI; + +// Spins a cube above the sample's UI, so session replays show motion, and logs frame timings to logcat under the +// 'ReplayBenchmark' tag, to compare session replay's capture modes (see SentryOptionConfiguration). +// Android players only. The GPU and per-thread timings need 'Frame Timing Stats' in the player settings. +public class ReplayBenchmark : MonoBehaviour +{ + private const string LogTag = "ReplayBenchmark"; + private const float WarmUpSeconds = 5f; + private const float ReportSeconds = 10f; + // A layer of its own, so the cube's camera and light leave the sample's scenes alone. + private const int CubeLayer = 31; + + private readonly List _frameTimes = new(); + private readonly FrameTiming[] _timings = new FrameTiming[1]; + private double _cpuMainMs; + private double _cpuRenderMs; + private double _gpuMs; + private int _timingCount; + private float _collectFrom; + private float _nextReport; + private Transform _cube; + private string _mode; + private AndroidJavaClass _log; + + [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterSceneLoad)] + private static void Spawn() + { + var benchmark = new GameObject("ReplayBenchmark"); + DontDestroyOnLoad(benchmark); + benchmark.AddComponent(); + } + + private void Start() + { + Application.targetFrameRate = 60; + _mode = $"replay={SentryOptionConfiguration.GetLaunchExtra("sentry_replay") ?? "error"} " + + $"capture={SentryOptionConfiguration.GetLaunchExtra("sentry_replay_capture") ?? "java"}"; + _log = new AndroidJavaClass("android.util.Log"); + _collectFrom = Time.realtimeSinceStartup + WarmUpSeconds; + _nextReport = _collectFrom + ReportSeconds; + + var texture = new RenderTexture(256, 256, 16); + + var cube = GameObject.CreatePrimitive(PrimitiveType.Cube); + cube.layer = CubeLayer; + cube.transform.SetParent(transform); + cube.transform.position = new Vector3(0, -1000, 0); + // A shader that builds always include. The primitive's default material doesn't make it into the player. + var shader = Shader.Find("Legacy Shaders/Diffuse"); + var cubeRenderer = cube.GetComponent(); + if (shader != null) + { + cubeRenderer.material = new Material(shader); + } + cubeRenderer.material.color = new Color(1f, 0.45f, 0.1f); + _cube = cube.transform; + + var cubeCamera = new GameObject("ReplayBenchmarkCamera").AddComponent(); + cubeCamera.transform.SetParent(transform); + cubeCamera.transform.position = _cube.position + new Vector3(0, 0, -2.5f); + cubeCamera.cullingMask = 1 << CubeLayer; + cubeCamera.clearFlags = CameraClearFlags.SolidColor; + cubeCamera.backgroundColor = new Color(0.1f, 0.5f, 0.9f); + cubeCamera.targetTexture = texture; + + var cubeLight = new GameObject("ReplayBenchmarkLight").AddComponent(); + cubeLight.transform.SetParent(transform); + cubeLight.type = LightType.Directional; + cubeLight.cullingMask = 1 << CubeLayer; + cubeLight.transform.rotation = Quaternion.Euler(40, -30, 0); + + // Above the sample's UI, in the top right corner. + var canvas = new GameObject("ReplayBenchmarkCanvas").AddComponent(); + canvas.transform.SetParent(transform); + canvas.renderMode = RenderMode.ScreenSpaceOverlay; + canvas.sortingOrder = 1000; + var image = new GameObject("ReplayBenchmarkCube").AddComponent(); + image.texture = texture; + image.raycastTarget = false; + var rect = image.rectTransform; + rect.SetParent(canvas.transform, false); + rect.anchorMin = rect.anchorMax = rect.pivot = new Vector2(1, 1); + rect.anchoredPosition = new Vector2(-16, -16); + rect.sizeDelta = new Vector2(220, 220); + } + + private void Update() + { + _cube.Rotate(new Vector3(30, 60, 15) * Time.deltaTime); + + var now = Time.realtimeSinceStartup; + if (now < _collectFrom) + { + return; + } + + _frameTimes.Add(Time.unscaledDeltaTime * 1000f); + FrameTimingManager.CaptureFrameTimings(); + if (FrameTimingManager.GetLatestTimings(1, _timings) > 0) + { +#if UNITY_2022_1_OR_NEWER + _cpuMainMs += _timings[0].cpuMainThreadFrameTime; + _cpuRenderMs += _timings[0].cpuRenderThreadFrameTime; +#else + _cpuMainMs += _timings[0].cpuFrameTime; +#endif + _gpuMs += _timings[0].gpuFrameTime; + _timingCount++; + } + + if (now >= _nextReport) + { + Report(); + _nextReport = now + ReportSeconds; + } + } + + private void Report() + { + if (_frameTimes.Count == 0) + { + return; + } + + var sum = 0f; + foreach (var frameTime in _frameTimes) + { + sum += frameTime; + } + + _frameTimes.Sort(); + var p95 = _frameTimes[Mathf.Min(_frameTimes.Count - 1, (int)(_frameTimes.Count * 0.95f))]; + var timings = _timingCount == 0 + ? "frame timing stats off" + : $"cpu main {_cpuMainMs / _timingCount:F2} ms, " + + $"cpu render {_cpuRenderMs / _timingCount:F2} ms, " + + $"gpu {_gpuMs / _timingCount:F2} ms"; + _log.CallStatic("i", LogTag, + $"{_mode} frames {_frameTimes.Count}, frame avg {sum / _frameTimes.Count:F2} ms, " + + $"p95 {p95:F2} ms, {timings}"); + + _frameTimes.Clear(); + _cpuMainMs = _cpuRenderMs = _gpuMs = 0; + _timingCount = 0; + } +} +#endif diff --git a/samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs.meta b/samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs.meta new file mode 100644 index 000000000..0e4d14d45 --- /dev/null +++ b/samples/unity-of-bugs/Assets/Scripts/ReplayBenchmark.cs.meta @@ -0,0 +1,11 @@ +fileFormatVersion: 2 +guid: 1736f9dc4e6143ae9e6c30818883b8eb +MonoImporter: + externalObjects: {} + serializedVersion: 2 + defaultReferences: [] + executionOrder: 0 + icon: {instanceID: 0} + userData: + assetBundleName: + assetBundleVariant: diff --git a/samples/unity-of-bugs/Assets/Scripts/SentryOptionConfiguration.cs b/samples/unity-of-bugs/Assets/Scripts/SentryOptionConfiguration.cs index c38dbffae..109ebcc1a 100644 --- a/samples/unity-of-bugs/Assets/Scripts/SentryOptionConfiguration.cs +++ b/samples/unity-of-bugs/Assets/Scripts/SentryOptionConfiguration.cs @@ -52,10 +52,55 @@ public override void Configure(SentryUnityOptions options) // - Miss some early errors that happen before the SDK initialized #if UNITY_ANDROID options.AndroidNativeInitializationType = NativeInitializationType.Runtime; + ConfigureSessionReplay(options); #elif UNITY_IOS options.IosNativeInitializationType = NativeInitializationType.Runtime; #endif Debug.Log("SentryOptionConfigure finished."); } + +#if UNITY_ANDROID + // Experimental session replay. Enabled at build time, so the build carries the replay library. At runtime, launch + // extras pick the mode: `adb shell am start -n /com.unity3d.player.UnityPlayerActivity + // --es sentry_replay off|session|error --es sentry_replay_capture java|unity`. Without them, replays are sent for + // errors, with frames the Android SDK captures. + private static void ConfigureSessionReplay(SentryUnityOptions options) + { + var mode = Application.isEditor ? null : GetLaunchExtra("sentry_replay"); + var capture = Application.isEditor ? null : GetLaunchExtra("sentry_replay_capture"); + var replay = options.Experimental.SessionReplay; + switch (mode) + { + case "off": + break; + case "session": + replay.SessionSampleRate = 1.0; + break; + default: + replay.OnErrorSampleRate = 1.0; + break; + } + + replay.Capture = capture == "unity" ? SessionReplayCapture.Unity : SessionReplayCapture.SentryJava; + + Debug.Log($"Session replay mode: {mode ?? "error"}, capture: {replay.Capture}"); + } + + internal static string GetLaunchExtra(string name) + { + try + { + using var player = new AndroidJavaClass("com.unity3d.player.UnityPlayer"); + using var activity = player.GetStatic("currentActivity"); + using var intent = activity.Call("getIntent"); + return intent.Call("getStringExtra", name); + } + catch (Exception e) + { + Debug.LogWarning($"Failed to read the launch extra '{name}': {e.Message}"); + return null; + } + } +#endif } diff --git a/src/Sentry.Unity.Android/AndroidReplaySession.cs b/src/Sentry.Unity.Android/AndroidReplaySession.cs new file mode 100644 index 000000000..d1e3c32f7 --- /dev/null +++ b/src/Sentry.Unity.Android/AndroidReplaySession.cs @@ -0,0 +1,31 @@ +using System; +using Sentry.Internal; + +namespace Sentry.Unity.Android; + +/// +/// The replay that the Android SDK records, for the events captured in C#. +/// +internal sealed class AndroidReplaySession : IReplaySession +{ + private readonly ISentryJava _sentryJava; + + public AndroidReplaySession(ISentryJava sentryJava) => _sentryJava = sentryJava; + + // The replay id on the native scope, not the recording's: a replay buffered for errors only gets one once an + // error captured it. + public SentryId? ActiveReplayId => ToReplayId(_sentryJava.GetReplayId()); + + public SentryId? CaptureReplay(SentryEvent @event) => ToReplayId(_sentryJava.CaptureReplay()); + + // The native SDK's empty id (all zeros) means no replay. + private static SentryId? ToReplayId(string? replayId) + { + if (replayId is null || !Guid.TryParse(replayId, out var guid) || guid == Guid.Empty) + { + return null; + } + + return new SentryId(guid); + } +} diff --git a/src/Sentry.Unity.Android/SentryJava.cs b/src/Sentry.Unity.Android/SentryJava.cs index a5a9fa8ee..99aa2f6aa 100644 --- a/src/Sentry.Unity.Android/SentryJava.cs +++ b/src/Sentry.Unity.Android/SentryJava.cs @@ -22,6 +22,11 @@ internal interface ISentryJava public bool TryGetMainProcessUser(out SentryUser? user); public string? GetInstallationId(); public bool? CrashedLastRun(); + public string? GetReplayId(); + public string? CaptureReplay(); + public bool? IsProcessLifecycleObserved(); + public void PauseReplay(); + public void ResumeReplay(bool startNewSession); public (string? Type, string? EffectiveType) GetConnection(); public void Close(); public void WriteScope( @@ -77,6 +82,7 @@ internal class SentryJava : ISentryJava private readonly ConcurrentQueue<(Action action, string actionName)> _scopeSyncItems = new(); private static readonly TimeSpan JniResultTimeout = TimeSpan.FromMilliseconds(500); private volatile bool _closed; + private UnityReplayRecorder? _unityReplayRecorder; private static AndroidJavaObject GetInternalSentryJava() => new AndroidJavaClass("io.sentry.android.core.InternalSentrySdk"); private static AndroidJavaObject GetSentryJava() => new AndroidJavaClass("io.sentry.Sentry"); @@ -269,7 +275,15 @@ public void Init(SentryUnityOptions options) // Disable user interaction tracking to prevent conflicts with VR platforms (e.g., Oculus InputHooks) androidOptions.Call("setEnableUserInteractionBreadcrumbs", false); androidOptions.Call("setEnableUserInteractionTracing", false); + + // With external initialization, the app's SDK owns session replay. + if (!isExternal) + { + ConfigureSessionReplay(androidOptions, context, options.Experimental.SessionReplay); + } }, options.DiagnosticLogger)); + + StartUnityReplayRecorder(); } catch (Exception e) { @@ -277,6 +291,180 @@ public void Init(SentryUnityOptions options) } } + // Runs in its own try/catch, so a failure can't skip the options Unity relies on. + private void ConfigureSessionReplay(AndroidJavaObject androidOptions, AndroidJavaObject context, + ExperimentalSessionReplayOptions replay) + { + if (!replay.IsEnabled) + { + return; + } + + var capture = replay.Capture; + if (capture is SessionReplayCapture.Unity && !SystemInfo.supportsAsyncGPUReadback) + { + _logger?.LogWarning( + "Session replay capture by Unity needs async GPU readback, which this device's graphics API doesn't " + + "support. The Android SDK captures the frames instead."); + capture = SessionReplayCapture.SentryJava; + } + + try + { + try + { + using var _ = new AndroidJavaClass("io.sentry.android.replay.ReplayIntegration"); + } + catch (AndroidJavaException) + { + _logger?.LogError( + "Session replay is enabled but the Android replay library is missing from the build. " + + "Enable 'Experimental.SessionReplay' in the options used at build time and rebuild."); + return; + } + + using var replayOptions = androidOptions.Call("getSessionReplay"); + using var sessionSampleRate = new AndroidJavaObject("java.lang.Double", replay.SessionSampleRate); + replayOptions.Call("setSessionSampleRate", sessionSampleRate); + using var onErrorSampleRate = new AndroidJavaObject("java.lang.Double", replay.OnErrorSampleRate); + replayOptions.Call("setOnErrorSampleRate", onErrorSampleRate); + // Unity renders into a SurfaceView, which the Android SDK only captures when asked to. + replayOptions.Call("setCaptureSurfaceViews", capture is SessionReplayCapture.SentryJava); + using var qualityClass = new AndroidJavaClass("io.sentry.SentryReplayOptions$SentryReplayQuality"); + using var quality = qualityClass.GetStatic(GetReplayQualityString(replay.Quality)); + replayOptions.Call("setQuality", quality); + + _logger?.LogDebug( + $"Session replay configured: session sample rate {replay.SessionSampleRate}, " + + $"on-error sample rate {replay.OnErrorSampleRate}, " + + $"quality {replay.Quality}, capture {capture}."); + } + catch (Exception e) + { + _logger?.LogError(e, "Failed to configure session replay."); + return; + } + + if (capture is not SessionReplayCapture.Unity) + { + return; + } + + // On failure, the replay the Android SDK added stays: it records nothing without SurfaceView capture. + try + { + var recorder = new UnityReplayRecorder(_logger); + recorder.Install(androidOptions, context); + _unityReplayRecorder = recorder; + } + catch (Exception e) + { + _logger?.LogError(e, "Failed to set up session replay capture by Unity."); + } + } + + private void StartUnityReplayRecorder() + { + try + { + _unityReplayRecorder?.Start(); + } + catch (Exception e) + { + _logger?.LogError(e, "Failed to start session replay capture by Unity."); + } + } + + internal static string GetReplayQualityString(SessionReplayQuality quality) => quality switch + { + SessionReplayQuality.Low => "LOW", + SessionReplayQuality.High => "HIGH", + _ => "MEDIUM" + }; + + // The replay id on the native SDK's scope: set while a session is recorded, or once an error captured its replay. + public string? GetReplayId() => RunJniSafeAndWait(() => + { + using var sentry = GetInternalSentryJava(); + using var scope = sentry.CallStatic("getCurrentScope"); + using var replayId = scope?.Call("getReplayId"); + return replayId?.Call("toString"); + }); + + // Captures the replay for an error, like the native SDK does for its own errors. Returns the replay's id, empty + // when the error has no replay (none recorded, or not sampled for errors). + public string? CaptureReplay() => RunJniSafeAndWait(() => + { + using var replayController = GetReplayController(); + // `captureReplay(Boolean isTerminating)` takes a boxed Boolean. + using var isTerminating = new AndroidJavaObject("java.lang.Boolean", false); + using var replayId = replayController?.Call("captureReplay", isTerminating); + return replayId?.Call("toString"); + }); + + // Whether androidx's process lifecycle runs, which tells the native SDK that the app went to the background and + // back. It needs the startup provider of `androidx.lifecycle:lifecycle-process`, which Unity builds don't have. + public bool? IsProcessLifecycleObserved() + { + if (!MainThreadData.IsMainThread()) + { + _logger?.LogError("Calling IsProcessLifecycleObserved() on Android SDK requires running on MainThread"); + return null; + } + + try + { + using var processLifecycleOwner = new AndroidJavaClass("androidx.lifecycle.ProcessLifecycleOwner"); + using var owner = processLifecycleOwner.CallStatic("get"); + using var lifecycle = owner.Call("getLifecycle"); + using var state = lifecycle.Call("getCurrentState"); + using var stateClass = new AndroidJavaClass("androidx.lifecycle.Lifecycle$State"); + using var created = stateClass.GetStatic("CREATED"); + return state.Call("isAtLeast", created); + } + catch (AndroidJavaException) + { + // Not in the app. + return false; + } + catch (Exception e) + { + _logger?.LogError(e, "Calling 'SentryJava.IsProcessLifecycleObserved' failed."); + } + + return null; + } + + // Pauses the replay, ending its current segment. It's the replay's manual pause, so nothing but `ResumeReplay` + // resumes it: the replay resumes itself when the device reconnects, which happens in the background too. + public void PauseReplay() => RunJniSafe(() => + { + using var replayController = GetReplayController(); + replayController?.Call("pause"); + }); + + // Resumes the replay. Its next segment starts now, so none covers the time away. With `startNewSession`, the + // replay then ends and a new one starts, sampled as the replay samples sessions. Ending a replay sends a segment + // from its last one to now; with the timeline moved to now and no frames since the pause, it sends none. Both + // calls are queued in order on Android's UI thread. + public void ResumeReplay(bool startNewSession) => RunJniSafe(() => + { + using var replayController = GetReplayController(); + replayController?.Call("resume"); + if (startNewSession) + { + replayController?.Call("onAppForegrounded", true); + } + }); + + private static AndroidJavaObject? GetReplayController() + { + using var sentry = GetSentryJava(); + using var scopes = sentry.CallStatic("getCurrentScopes"); + using var options = scopes?.Call("getOptions"); + return options?.Call("getReplayController"); + } + // A string option of the native SDK, e.g. `getRelease` or `getEnvironment`. public string? GetOption(string getter) => ReadOptions(nameof(GetOption), options => options.Call(getter)); diff --git a/src/Sentry.Unity.Android/SentryNativeAndroid.cs b/src/Sentry.Unity.Android/SentryNativeAndroid.cs index b77d081ee..7b973c662 100644 --- a/src/Sentry.Unity.Android/SentryNativeAndroid.cs +++ b/src/Sentry.Unity.Android/SentryNativeAndroid.cs @@ -97,6 +97,26 @@ public static void Configure(SentryUnityOptions options) options.NativeDebugImageProvider = new Native.NativeDebugImageProvider(); options.NativeConnection = SentryJava.GetConnection; + if (options.Experimental.SessionReplay.IsEnabled) + { + if (options.AndroidNativeInitializationType is NativeInitializationType.Runtime) + { + Logger?.LogDebug("Capturing the session replay for C# errors."); + options.ReplaySession = new AndroidReplaySession(SentryJava); + if (SentryJava.IsProcessLifecycleObserved() is false) + { + PauseReplayWithUnity(options, SentryJava); + } + } + else + { + Logger?.LogWarning( + "Session replay requires the Android SDK to be initialized at runtime. " + + "Ignoring it with initialization type '{0}'.", + options.AndroidNativeInitializationType); + } + } + if (isExternal) { // In its own process, the game's SDK took them from the app's SDK when it initialized. @@ -190,6 +210,38 @@ public static void Configure(SentryUnityOptions options) Logger?.LogInfo("Successfully configured the Android SDK"); } + // Without androidx's process lifecycle, the native SDK doesn't see the app go to the background: Unity tells it, + // so the replay pauses there and no segment covers the time away. Like the native SDK, a background longer than + // the session interval ends the replay at the pause and starts a new one. + private static void PauseReplayWithUnity(SentryUnityOptions options, ISentryJava sentryJava) + { + Logger?.LogDebug("Pausing and resuming session replay with the Unity application's lifecycle."); + + DateTime? pausedAt = null; + void Pause() + { + pausedAt = DateTime.UtcNow; + sentryJava.PauseReplay(); + } + + void Resume() + { + var startNewSession = pausedAt is { } paused + && DateTime.UtcNow - paused >= options.AutoSessionTrackingInterval; + pausedAt = null; + sentryJava.ResumeReplay(startNewSession); + } + + var monoBehaviour = SentryMonoBehaviour.Instance; + monoBehaviour.ApplicationPausing += Pause; + monoBehaviour.ApplicationResuming += Resume; + options.NativeSupportCloseCallback += () => + { + monoBehaviour.ApplicationPausing -= Pause; + monoBehaviour.ApplicationResuming -= Resume; + }; + } + // The game runs in its own process and continues the trace the app was in when it showed the game, with its user. private static void UseMainProcessScope(SentryUnityOptions options, ISentryJava sentryJava) { diff --git a/src/Sentry.Unity.Android/UnityReplayRecorder.cs b/src/Sentry.Unity.Android/UnityReplayRecorder.cs new file mode 100644 index 000000000..0b9cefddf --- /dev/null +++ b/src/Sentry.Unity.Android/UnityReplayRecorder.cs @@ -0,0 +1,719 @@ +using System; +using System.Collections; +using System.Diagnostics; +using System.Threading; +using Sentry.Extensibility; +using UnityEngine; +using UnityEngine.Experimental.Rendering; +using UnityEngine.Rendering; + +namespace Sentry.Unity.Android; + +/// +/// Session replay's recorder when Unity captures the frames: the Android SDK's replay drives it through its +/// Recorder interface, and Unity hands it each frame as a bitmap. +/// +/// +/// The Android SDK calls the recorder on Android's UI thread. Those calls only update the state below; Unity's main +/// thread reads it and captures the frames, and a worker thread turns them into bitmaps and hands them over. No +/// thread waits on another: closing the SDK blocks Unity's main thread while the UI thread stops and closes the +/// recorder. +/// +internal sealed class UnityReplayRecorder +{ + private const string ReplayIntegrationClass = "io.sentry.android.replay.ReplayIntegration"; + private static readonly TimeSpan StatsInterval = TimeSpan.FromSeconds(10); + + private sealed class FrameConfig + { + public FrameConfig(int width, int height, int frameRate) + { + Width = width; + Height = height; + FrameRate = Math.Max(1, frameRate); + } + + public int Width { get; } + public int Height { get; } + public int FrameRate { get; } + } + + private readonly IDiagnosticLogger? _logger; + private readonly RecorderProxy _recorder; + private readonly RecorderProvider _provider; + + // Written on Android's UI thread. + private volatile bool _recording; + private volatile bool _resumed; + private volatile bool _closed; + private volatile FrameConfig? _config; + // 1 when the replay needs a frame config: every (re)started replay starts without one. + private int _configNeeded; + // The window size of the current config. Android's UI thread only. + private int _configuredWidth; + private int _configuredHeight; + + // Set on Unity's main thread before the recorder starts. + private volatile AndroidJavaObject? _replayIntegration; + private AndroidJavaObject? _mainHandler; + + // The frame the worker hands over next: filled on Unity's main thread while no frame is queued. + private readonly AutoResetEvent _frameQueuedEvent = new(false); + private volatile bool _frameQueued; + private sbyte[] _pixels = Array.Empty(); + private int _pixelsWidth; + private int _pixelsHeight; + private Thread? _worker; + + // Unity's main thread only. + private RenderTexture? _screen; + private RenderTexture? _frame; + private bool _readbackPending; + private float _nextCaptureTime; + private int _screenWidth; + private int _screenHeight; + private AndroidJavaClass? _bitmapClass; + private AndroidJavaClass? _byteBufferClass; + private AndroidJavaObject? _argb8888; + + private readonly Stopwatch _statsWatch = new(); + private int _statsFrames; + private int _statsDropped; + private double _statsCaptureMs; + private double _statsCopyMs; + // Written by the worker. + private double _statsHandOverMs; + private int _statsHandedOver; + + public UnityReplayRecorder(IDiagnosticLogger? logger) + { + _logger = logger; + _recorder = new RecorderProxy(this); + _provider = new RecorderProvider(_recorder); + } + + /// + /// Replaces the replay integration the Android SDK added with one that records through this recorder. + /// Runs in the options callback of the Android SDK's initialization, before the integrations register. + /// + public void Install(AndroidJavaObject androidOptions, AndroidJavaObject context) + { + using var appContext = context.Call("getApplicationContext"); + using var dateProviderClass = new AndroidJavaClass("io.sentry.transport.CurrentDateProvider"); + using var dateProvider = dateProviderClass.CallStatic("getInstance"); + using var replayClass = new AndroidJavaClass(ReplayIntegrationClass); + + // `ReplayIntegration(Context, ICurrentDateProvider, (() -> Recorder)?, ((SentryId) -> ReplayCache)?)`. Called + // through JNI, as Unity can't pick a constructor for a null argument. + var constructor = AndroidJNI.GetMethodID(replayClass.GetRawClass(), "", + "(Landroid/content/Context;" + + "Lio/sentry/transport/ICurrentDateProvider;" + + "Lkotlin/jvm/functions/Function0;" + + "Lkotlin/jvm/functions/Function1;)V"); + ThrowOnJavaException("finding the ReplayIntegration constructor"); + + var provider = IntPtr.Zero; + var replayIntegration = IntPtr.Zero; + try + { + provider = AndroidJNIHelper.CreateJavaProxy(_provider); + var args = new jvalue[4]; + args[0].l = appContext.GetRawObject(); + args[1].l = dateProvider.GetRawObject(); + args[2].l = provider; + args[3].l = IntPtr.Zero; + replayIntegration = AndroidJNI.NewObject(replayClass.GetRawClass(), constructor, args); + ThrowOnJavaException("creating the ReplayIntegration"); + + RemoveReplayIntegrations(androidOptions); + CallVoid(androidOptions, "addIntegration", "(Lio/sentry/Integration;)V", replayIntegration); + CallVoid(androidOptions, "setReplayController", "(Lio/sentry/ReplayController;)V", replayIntegration); + } + finally + { + if (replayIntegration != IntPtr.Zero) + { + AndroidJNI.DeleteLocalRef(replayIntegration); + } + + if (provider != IntPtr.Zero) + { + AndroidJNI.DeleteLocalRef(provider); + } + } + + _replayIntegration = androidOptions.Call("getReplayController"); + _logger?.LogDebug("Session replay records the frames Unity captures."); + } + + /// + /// Starts capturing on Unity's main thread, once the Android SDK is initialized. + /// + public void Start() + { + if (_replayIntegration is null) + { + return; + } + + using var looperClass = new AndroidJavaClass("android.os.Looper"); + using var mainLooper = looperClass.CallStatic("getMainLooper"); + _mainHandler = new AndroidJavaObject("android.os.Handler", mainLooper); + _statsWatch.Start(); + _worker = new Thread(HandOverFrames) { IsBackground = true, Name = "SentryReplayFrames" }; + _worker.Start(); + SentryMonoBehaviour.Instance.StartCoroutine(Run()); + } + + private static void RemoveReplayIntegrations(AndroidJavaObject androidOptions) + { + using var integrations = androidOptions.Call("getIntegrations"); + for (var i = integrations.Call("size") - 1; i >= 0; i--) + { + using var integration = integrations.Call("get", i); + using var integrationClass = integration.Call("getClass"); + if (integrationClass.Call("getName") == ReplayIntegrationClass) + { + integrations.Call("remove", i)?.Dispose(); + } + } + } + + private static void CallVoid(AndroidJavaObject target, string method, string signature, IntPtr argument) + { + var methodId = AndroidJNI.GetMethodID(target.GetRawClass(), method, signature); + ThrowOnJavaException($"finding '{method}'"); + var args = new jvalue[1]; + args[0].l = argument; + AndroidJNI.CallVoidMethod(target.GetRawObject(), methodId, args); + ThrowOnJavaException($"calling '{method}'"); + } + + private static void ThrowOnJavaException(string action) + { + var throwable = AndroidJNI.ExceptionOccurred(); + if (throwable == IntPtr.Zero) + { + return; + } + + AndroidJNI.ExceptionDescribe(); + AndroidJNI.ExceptionClear(); + AndroidJNI.DeleteLocalRef(throwable); + throw new InvalidOperationException($"A Java exception was thrown {action}. See logcat for details."); + } + + // The recorder's calls, on Android's UI thread. + + // A started recorder captures until it's paused: the replay only resumes a paused one. + private void OnStart() + { + _config = null; + _resumed = true; + _recording = true; + Interlocked.Exchange(ref _configNeeded, 1); + } + + private void OnConfigurationChanged(AndroidJavaObject config) + { + var frameConfig = new FrameConfig( + config.Call("getRecordingWidth"), + config.Call("getRecordingHeight"), + config.Call("getFrameRate")); + _config = frameConfig; + _logger?.LogDebug("Session replay records {0}x{1} at {2} fps.", + frameConfig.Width, frameConfig.Height, frameConfig.FrameRate); + } + + private void OnReset() + { + _config = null; + Interlocked.Exchange(ref _configNeeded, 1); + } + + private void OnStop() + { + _recording = false; + _resumed = false; + _config = null; + } + + private void OnClose() + { + OnStop(); + _closed = true; + _frameQueuedEvent.Set(); + } + + // Unity's main thread. + + private IEnumerator Run() + { + var endOfFrame = new WaitForEndOfFrame(); + while (!_closed) + { + yield return null; + + try + { + if (!_recording) + { + ReleaseTextures(); + continue; + } + + RequestConfig(); + if (!IsCaptureDue()) + { + continue; + } + } + catch (Exception e) + { + _logger?.LogError(e, "Session replay failed to prepare a frame."); + continue; + } + + yield return endOfFrame; + + try + { + Capture(); + } + catch (Exception e) + { + _readbackPending = false; + _logger?.LogError(e, "Session replay failed to capture a frame."); + } + } + + ReleaseTextures(); + } + + // The replay computes the frame config from the window size. It doesn't send one to a recorder of its own. + // A change of Unity's screen size, e.g. on rotation, asks for a new one. + private void RequestConfig() + { + var width = Screen.width; + var height = Screen.height; + var needed = Interlocked.Exchange(ref _configNeeded, 0) == 1; + if (!needed && width == _screenWidth && height == _screenHeight) + { + return; + } + + _screenWidth = width; + _screenHeight = height; + _mainHandler?.Call("post", new AndroidJavaRunnable(() => OnWindowSizeChanged(width, height))); + } + + // On Android's UI thread, where the replay's own recorder reports the window size. Unity's screen size can be a + // lower render resolution than the window. The replay scales recorded touches, which are in window pixels, by the + // config it computes from the window size, so it gets the window's. + private void OnWindowSizeChanged(int screenWidth, int screenHeight) + { + try + { + var replayIntegration = _replayIntegration; + if (replayIntegration is null || _closed) + { + return; + } + + // Starting or resetting the replay clears the config on this thread, so a config for this size is current. + if (_config is not null && screenWidth == _configuredWidth && screenHeight == _configuredHeight) + { + return; + } + + if (replayIntegration.Call("isRecording")) + { + var windowSize = GetWindowSize(); + if (windowSize is null) + { + // Before the window is laid out, Unity's screen size stands in, so recording can start. A later + // frame asks again for the window's. A new size starts a new segment, so it's sent only once. + _configuredWidth = 0; + _configuredHeight = 0; + Interlocked.Exchange(ref _configNeeded, 1); + if (_config is null) + { + replayIntegration.Call("onWindowSizeChanged", screenWidth, screenHeight); + } + + return; + } + + var (width, height) = windowSize.Value; + _configuredWidth = screenWidth; + _configuredHeight = screenHeight; + replayIntegration.Call("onWindowSizeChanged", width, height); + } + else if (_recording) + { + Interlocked.Exchange(ref _configNeeded, 1); + } + } + catch (Exception e) + { + _logger?.LogError(e, "Session replay failed to update the frame size."); + } + } + + // The size of the activity's window, in pixels. Null before it's laid out. + private static (int Width, int Height)? GetWindowSize() + { + using var unityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer"); + using var activity = unityPlayer.GetStatic("currentActivity"); + using var window = activity?.Call("getWindow"); + using var decorView = window?.Call("getDecorView"); + if (decorView is null) + { + return null; + } + + var width = decorView.Call("getWidth"); + var height = decorView.Call("getHeight"); + return width > 0 && height > 0 ? (width, height) : null; + } + + private bool IsCaptureDue() + { + if (!_resumed || _readbackPending || _config is not { } config) + { + return false; + } + + var now = Time.realtimeSinceStartup; + if (now < _nextCaptureTime) + { + return false; + } + + var interval = 1f / config.FrameRate; + _nextCaptureTime += interval; + if (_nextCaptureTime < now) + { + _nextCaptureTime = now + interval; + } + + return true; + } + + private void Capture() + { + if (_closed || !_recording || !_resumed || _config is not { } config) + { + return; + } + + var stopwatch = Stopwatch.StartNew(); + EnsureTextures(config); + + var previous = RenderTexture.active; + try + { + ScreenCapture.CaptureScreenshotIntoRenderTexture(_screen); + SentryScreenshot.BlitScreen(_screen!, _frame!, topDown: true); + } + finally + { + RenderTexture.active = previous; + } + + _readbackPending = true; + AsyncGPUReadback.Request(_frame, 0, OnReadback); + _statsCaptureMs += stopwatch.Elapsed.TotalMilliseconds; + } + + private void EnsureTextures(FrameConfig config) + { + if (_screen is null || _screen.width != Screen.width || _screen.height != Screen.height) + { + ReleaseTexture(ref _screen); + _screen = new RenderTexture(Screen.width, Screen.height, 0, RenderTextureFormat.Default); + _screen.Create(); + } + + if (_frame is null || _frame.width != config.Width || _frame.height != config.Height) + { + ReleaseTexture(ref _frame); + // RGBA bytes, as Android's ARGB_8888 bitmaps hold them. In a linear color space, sRGB keeps the colors. + var format = QualitySettings.activeColorSpace == ColorSpace.Linear + ? GraphicsFormat.R8G8B8A8_SRGB + : GraphicsFormat.R8G8B8A8_UNorm; + _frame = new RenderTexture(config.Width, config.Height, 0, format); + _frame.Create(); + } + } + + private void OnReadback(AsyncGPUReadbackRequest readback) + { + _readbackPending = false; + try + { + // Run has already ended and left the textures to the readback that was still reading them. + if (_closed) + { + ReleaseTextures(); + return; + } + + if (readback.hasError) + { + Drop("the GPU readback failed"); + return; + } + + // The config can change while the frame is read back, e.g. on rotation. A frame read back after the replay + // paused would land after the segment that ended at the pause, so it's dropped. + if (_closed || !_recording || !_resumed || _config is not { } config) + { + return; + } + + var width = config.Width; + var height = config.Height; + var pixels = readback.GetData(); + if (readback.width != width || readback.height != height || pixels.Length != width * height * 4) + { + Drop("its size doesn't match the replay's"); + return; + } + + if (_frameQueued) + { + Drop("the previous frame is still being handed over"); + return; + } + + var stopwatch = Stopwatch.StartNew(); + if (_pixels.Length != pixels.Length) + { + _pixels = new sbyte[pixels.Length]; + } + + pixels.CopyTo(_pixels); + _pixelsWidth = width; + _pixelsHeight = height; + _frameQueued = true; + _frameQueuedEvent.Set(); + _statsCopyMs += stopwatch.Elapsed.TotalMilliseconds; + _statsFrames++; + LogStats(); + } + catch (Exception e) + { + _logger?.LogError(e, "Session replay failed to read back a frame."); + } + } + + // On the worker, attached to the JVM: handing a frame to Java takes several milliseconds, too long for Unity's + // main thread. + private void HandOverFrames() + { + AndroidJNI.AttachCurrentThread(); + try + { + while (true) + { + _frameQueuedEvent.WaitOne(); + if (_closed) + { + return; + } + + if (!_frameQueued) + { + continue; + } + + var stopwatch = Stopwatch.StartNew(); + try + { + PushFrame(_pixels, _pixelsWidth, _pixelsHeight); + } + catch (Exception e) + { + _logger?.LogError(e, "Session replay failed to hand over a frame."); + } + finally + { + _statsHandOverMs += stopwatch.Elapsed.TotalMilliseconds; + _statsHandedOver++; + _frameQueued = false; + } + } + } + finally + { + AndroidJNI.DetachCurrentThread(); + } + } + + // A new bitmap for every frame: the replay compresses it on its own thread, after this returns. + private void PushFrame(sbyte[] pixels, int width, int height) + { + _bitmapClass ??= new AndroidJavaClass("android.graphics.Bitmap"); + _byteBufferClass ??= new AndroidJavaClass("java.nio.ByteBuffer"); + if (_argb8888 is null) + { + using var configClass = new AndroidJavaClass("android.graphics.Bitmap$Config"); + _argb8888 = configClass.GetStatic("ARGB_8888"); + } + + using var bitmap = _bitmapClass.CallStatic("createBitmap", width, height, _argb8888); + using var buffer = _byteBufferClass.CallStatic("wrap", pixels); + bitmap.Call("copyPixelsFromBuffer", buffer); + // The screen's alpha channel isn't meant to be seen. + bitmap.Call("setHasAlpha", false); + // The replay may have paused while the frame was handed over. + if (_recording && _resumed) + { + _replayIntegration?.Call("onScreenshotRecorded", bitmap); + } + } + + private void Drop(string reason) + { + _statsDropped++; + _logger?.LogDebug("Session replay dropped a frame: {0}.", reason); + } + + private void LogStats() + { + if (_statsWatch.Elapsed < StatsInterval) + { + return; + } + + if (_statsFrames > 0) + { + var capture = _statsCaptureMs / _statsFrames; + var copy = _statsCopyMs / _statsFrames; + var handOver = _statsHandedOver == 0 ? 0 : _statsHandOverMs / _statsHandedOver; + var seconds = _statsWatch.Elapsed.TotalSeconds; + _logger?.LogDebug( + FormattableString.Invariant( + $"Session replay captured {_statsFrames} frames in {seconds:F0}s ({_statsDropped} dropped). ") + + FormattableString.Invariant( + $"Main thread per frame: {capture + copy:F2} ms (capture {capture:F2} ms, copy {copy:F2} ms). ") + + FormattableString.Invariant( + $"Worker per frame: {handOver:F2} ms.")); + } + + _statsWatch.Restart(); + _statsFrames = 0; + _statsDropped = 0; + _statsCaptureMs = 0; + _statsCopyMs = 0; + _statsHandOverMs = 0; + _statsHandedOver = 0; + } + + private void ReleaseTextures() + { + // A pending readback still reads the frame texture. + if (_readbackPending) + { + return; + } + + ReleaseTexture(ref _screen); + ReleaseTexture(ref _frame); + } + + private static void ReleaseTexture(ref RenderTexture? texture) + { + if (texture is null) + { + return; + } + + texture.Release(); + UnityEngine.Object.Destroy(texture); + texture = null; + } + + /// + /// Implements io.sentry.android.replay.Recorder. Called on Android's UI thread. + /// + private sealed class RecorderProxy : AndroidJavaProxy + { + private readonly UnityReplayRecorder _owner; + + public RecorderProxy(UnityReplayRecorder owner) : base("io.sentry.android.replay.Recorder") => _owner = owner; + + // Overriding Invoke, as Unity doesn't find proxy methods defined by name. + public override AndroidJavaObject? Invoke(string methodName, AndroidJavaObject[] args) + { + try + { + if (methodName is not "onConfigurationChanged" and not "equals" and not "hashCode" and not "toString") + { + _owner._logger?.LogDebug("Session replay recorder: {0}.", methodName); + } + + switch (methodName) + { + case "start": + _owner.OnStart(); + return null; + case "onConfigurationChanged" when args.Length == 1 && args[0] is not null: + using (args[0]) + { + _owner.OnConfigurationChanged(args[0]); + } + return null; + case "resume": + _owner._resumed = true; + return null; + case "pause": + _owner._resumed = false; + return null; + case "reset": + _owner.OnReset(); + return null; + case "stop": + _owner.OnStop(); + return null; + case "close": + _owner.OnClose(); + return null; + default: + // equals, hashCode and toString + return base.Invoke(methodName, args); + } + } + catch (Exception e) + { + _owner._logger?.LogError(e, "Session replay recorder failed in '{0}'.", methodName); + return null; + } + } + } + + /// + /// Implements kotlin.jvm.functions.Function0, returning the recorder. The replay calls it when it registers. + /// + private sealed class RecorderProvider : AndroidJavaProxy + { + private readonly RecorderProxy _recorder; + + public RecorderProvider(RecorderProxy recorder) : base("kotlin.jvm.functions.Function0") => + _recorder = recorder; + + public override AndroidJavaObject? Invoke(string methodName, AndroidJavaObject[] args) + { + if (methodName != "invoke") + { + return base.Invoke(methodName, args); + } + + // Unity disposes the returned object, so each call returns a new one. Passing the proxy through Java gives + // the Java object behind it. + using var objects = new AndroidJavaClass("java.util.Objects"); + return objects.CallStatic("requireNonNull", _recorder); + } + } +} diff --git a/src/Sentry.Unity.Editor/Android/AndroidManifestConfiguration.cs b/src/Sentry.Unity.Editor/Android/AndroidManifestConfiguration.cs index 54b85b79c..e0d2b874a 100644 --- a/src/Sentry.Unity.Editor/Android/AndroidManifestConfiguration.cs +++ b/src/Sentry.Unity.Editor/Android/AndroidManifestConfiguration.cs @@ -317,7 +317,8 @@ internal void CopyAndroidSdkToGradleProject(string unityProjectPath, string grad internal void AddAndroidSdkDependencies(string gradleProjectPath) { - var tool = new GradleSetup(_logger, gradleProjectPath); + var sessionReplayEnabled = _options?.Experimental.SessionReplay.IsEnabled is true; + var tool = new GradleSetup(_logger, gradleProjectPath, sessionReplayEnabled); var nativeSupportEnabled = ShipsAndroidSdk; try diff --git a/src/Sentry.Unity.Editor/Android/GradleSetup.cs b/src/Sentry.Unity.Editor/Android/GradleSetup.cs index 53a7cd5fa..14d36d269 100644 --- a/src/Sentry.Unity.Editor/Android/GradleSetup.cs +++ b/src/Sentry.Unity.Editor/Android/GradleSetup.cs @@ -10,20 +10,33 @@ internal class GradleSetup private const string AndroidMarker = "android {"; private const string SdkDependenciesFull = SdkDependencies + "\n}\n\n" + AndroidMarker; + private const string SdkDependenciesWithReplayFull = + SdkDependencies + ReplayDependencies + "\n}\n\n" + AndroidMarker; public const string SdkDependencies = @"dependencies { implementation(name: 'sentry-android-ndk-release', ext:'aar') implementation(name: 'sentry-android-core-release', ext:'aar') implementation(name: 'sentry-native-ndk-release', ext:'aar')"; + + // Session replay is written in Kotlin. Local AARs don't bring their dependencies, so the Kotlin standard library + // comes from Maven, at the version sentry-android-replay builds with. + public const string ReplayDependencies = @" + implementation(name: 'sentry-android-replay-release', ext:'aar') + implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.9.24'"; public const string DependenciesAddedMessage = "The Sentry Gradle dependencies have already been added."; private readonly string _unityLibraryGradle; + private readonly bool _sessionReplayEnabled; - public GradleSetup(IDiagnosticLogger logger, string gradleProjectPath) + public GradleSetup(IDiagnosticLogger logger, string gradleProjectPath, bool sessionReplayEnabled = false) { _logger = logger; _unityLibraryGradle = Path.Combine(gradleProjectPath, "unityLibrary", "build.gradle"); + _sessionReplayEnabled = sessionReplayEnabled; } + private string Dependencies => _sessionReplayEnabled ? SdkDependenciesWithReplayFull : SdkDependenciesFull; + private string OtherDependencies => _sessionReplayEnabled ? SdkDependenciesFull : SdkDependenciesWithReplayFull; + public void UpdateGradleProject() { _logger.LogInfo("Adding Sentry to the gradle project."); @@ -37,26 +50,35 @@ public void ClearGradleProject() _logger.LogInfo("Removing Sentry from the gradle project."); var fileContent = LoadGradleScript(_unityLibraryGradle); - if (!fileContent.Contains(SdkDependenciesFull)) + // A persisted Gradle project can hold either variant of the dependencies. + if (!fileContent.Contains(SdkDependenciesFull) && !fileContent.Contains(SdkDependenciesWithReplayFull)) { _logger.LogDebug("The Sentry Gradle dependencies have already been removed."); return; } - fileContent = fileContent.Replace(SdkDependenciesFull, AndroidMarker); + fileContent = fileContent + .Replace(SdkDependenciesFull, AndroidMarker) + .Replace(SdkDependenciesWithReplayFull, AndroidMarker); File.WriteAllText(_unityLibraryGradle, fileContent); } public string AddSentryToGradle(string fileContent) { - if (fileContent.Contains(SdkDependenciesFull)) + if (fileContent.Contains(Dependencies)) { _logger.LogDebug(DependenciesAddedMessage); return fileContent; } + // A persisted Gradle project may hold the dependencies from a build with session replay toggled. + if (fileContent.Contains(OtherDependencies)) + { + return fileContent.Replace(OtherDependencies, Dependencies); + } + var regex = new Regex(Regex.Escape(AndroidMarker)); - return regex.Replace(fileContent, SdkDependenciesFull, 1); + return regex.Replace(fileContent, Dependencies, 1); } internal static string LoadGradleScript(string path) diff --git a/src/Sentry.Unity/ExperimentalSentryUnityOptions.cs b/src/Sentry.Unity/ExperimentalSentryUnityOptions.cs index 2fd3c683d..d3601d271 100644 --- a/src/Sentry.Unity/ExperimentalSentryUnityOptions.cs +++ b/src/Sentry.Unity/ExperimentalSentryUnityOptions.cs @@ -39,6 +39,11 @@ public class ExperimentalSentryUnityOptions /// [field: SerializeField] public LinuxBackend LinuxBackend { get; set; } = LinuxBackend.Breakpad; + /// + /// Session replay on Android. Off by default; set from code. + /// + public ExperimentalSessionReplayOptions SessionReplay { get; } = new(); + /// /// Legacy opt-in for native app hang detection. Use /// instead. This property will be removed in a future version. diff --git a/src/Sentry.Unity/ExperimentalSessionReplayOptions.cs b/src/Sentry.Unity/ExperimentalSessionReplayOptions.cs new file mode 100644 index 000000000..8f694d7a0 --- /dev/null +++ b/src/Sentry.Unity/ExperimentalSessionReplayOptions.cs @@ -0,0 +1,69 @@ +namespace Sentry.Unity; + +/// +/// Session replay on Android, recorded by the Android SDK (sentry-java). Off unless one of the sample rates is above 0. +/// Experimental: set these from code, in the options configuration used both at build time and at runtime. The build +/// adds the replay library to the Android project only when replay is enabled there. Replay needs the Android SDK +/// initialized at runtime (). +/// +public class ExperimentalSessionReplayOptions +{ + /// + /// The share of sessions that are recorded in full, from 0 to 1. Defaults to 0. + /// + public double SessionSampleRate { get; set; } + + /// + /// The share of errors that send the replay of the moments before them, from 0 to 1. Defaults to 0. + /// + public double OnErrorSampleRate { get; set; } + + /// + /// What captures the replay's frames. Defaults to . + /// + public SessionReplayCapture Capture { get; set; } = SessionReplayCapture.SentryJava; + + /// + /// The replay's video quality. Defaults to . + /// + public SessionReplayQuality Quality { get; set; } = SessionReplayQuality.Medium; + + internal bool IsEnabled => SessionSampleRate > 0 || OnErrorSampleRate > 0; +} + +/// +/// What captures the frames of a session replay. +/// +public enum SessionReplayCapture +{ + /// + /// The Android SDK copies the screen, including Unity's surface, at the replay's frame rate. + /// + SentryJava, + + /// + /// Unity captures its own frames and hands them to the Android SDK. + /// + Unity, +} + +/// +/// The video quality of a session replay. Higher quality sends larger replays. +/// +public enum SessionReplayQuality +{ + /// + /// Scaled down video at a low bit rate. + /// + Low, + + /// + /// Full size video at a medium bit rate. + /// + Medium, + + /// + /// Full size video at a high bit rate. + /// + High, +} diff --git a/src/Sentry.Unity/SentryScreenshot.cs b/src/Sentry.Unity/SentryScreenshot.cs index e2ea0e677..6ecac1864 100644 --- a/src/Sentry.Unity/SentryScreenshot.cs +++ b/src/Sentry.Unity/SentryScreenshot.cs @@ -97,6 +97,28 @@ internal static void CaptureAsync(SentryUnityOptions options, Action on } } + /// + /// Copies a screen captured with + /// into , scaling it to fit. The rows start at the bottom, as in Unity's textures, + /// or with at the top, as in Android's bitmaps. + /// + internal static void BlitScreen(RenderTexture screen, RenderTexture destination, bool topDown = false) + { + // The captured image is mirrored on platforms where UVs start at the top. + // See https://docs.unity3d.com/2019.4/Documentation/Manual/SL-PlatformDifferences.html for more info. + // Note, we can't use the `UNITY_UV_STARTS_AT_TOP` macro because it's only available in shaders. + // Instead, there's https://docs.unity3d.com/2019.4/Documentation/ScriptReference/SystemInfo-graphicsUVStartsAtTop.html + var uvStartsAtTop = SentrySystemInfoAdapter.Instance.GraphicsUVStartsAtTop ?? true; + if (uvStartsAtTop != topDown) + { + Graphics.Blit(screen, destination, new Vector2(1, -1), new Vector2(0, 1)); + } + else + { + Graphics.Blit(screen, destination); + } + } + // Returns a temporary render texture holding the screenshot, scaled down to the configured quality private static RenderTexture CaptureIntoRenderTexture(SentryUnityOptions options, int width, int height) { @@ -122,20 +144,7 @@ private static RenderTexture CaptureIntoRenderTexture(SentryUnityOptions options { ScreenCapture.CaptureScreenshotIntoRenderTexture(renderTextureFull); var renderTextureResized = RenderTexture.GetTemporary(width, height); - - // The image may be mirrored on some platforms - mirror it back. - // See https://docs.unity3d.com/2019.4/Documentation/Manual/SL-PlatformDifferences.html for more info. - // Note, we can't use the `UNITY_UV_STARTS_AT_TOP` macro because it's only available in shaders. - // Instead, there's https://docs.unity3d.com/2019.4/Documentation/ScriptReference/SystemInfo-graphicsUVStartsAtTop.html - if (SentrySystemInfoAdapter.Instance.GraphicsUVStartsAtTop ?? true) - { - Graphics.Blit(renderTextureFull, renderTextureResized, new Vector2(1, -1), new Vector2(0, 1)); - } - else - { - Graphics.Blit(renderTextureFull, renderTextureResized); - } - + BlitScreen(renderTextureFull, renderTextureResized); return renderTextureResized; } finally diff --git a/src/sentry-dotnet b/src/sentry-dotnet index d4a1de12c..9513c02c4 160000 --- a/src/sentry-dotnet +++ b/src/sentry-dotnet @@ -1 +1 @@ -Subproject commit d4a1de12c27529084925f6796cf68a837924a1dd +Subproject commit 9513c02c4dc403f235ce42a4ed7d71afd50b8519 diff --git a/test/Scripts.Tests/package-release.zip.snapshot b/test/Scripts.Tests/package-release.zip.snapshot index 7f03c416f..0547ec7cc 100644 --- a/test/Scripts.Tests/package-release.zip.snapshot +++ b/test/Scripts.Tests/package-release.zip.snapshot @@ -288,6 +288,7 @@ Plugins/Android/proguard-sentry-unity.pro.meta Plugins/Android/Sentry~/epitaph.jar Plugins/Android/Sentry~/sentry-android-core-release.aar Plugins/Android/Sentry~/sentry-android-ndk-release.aar +Plugins/Android/Sentry~/sentry-android-replay-release.aar Plugins/Android/Sentry~/sentry-native-ndk-release.aar Plugins/Android/Sentry~/sentry.jar Plugins/Switch/SentryStub~/sentry_native_stubs.c @@ -401,6 +402,8 @@ Samples~/unity-of-bugs/Scripts/Editor.meta Samples~/unity-of-bugs/Scripts/ForceCrashButtons.cs Samples~/unity-of-bugs/Scripts/ForceCrashButtons.cs.meta Samples~/unity-of-bugs/Scripts/NativeSupport.meta +Samples~/unity-of-bugs/Scripts/ReplayBenchmark.cs +Samples~/unity-of-bugs/Scripts/ReplayBenchmark.cs.meta Samples~/unity-of-bugs/Scripts/SceneButtons.cs Samples~/unity-of-bugs/Scripts/SceneButtons.cs.meta Samples~/unity-of-bugs/Scripts/SentryCliConfiguration.cs diff --git a/test/Sentry.Unity.Android.Tests/SentryNativeAndroidTests.cs b/test/Sentry.Unity.Android.Tests/SentryNativeAndroidTests.cs index 0634514d7..021fc1a5c 100644 --- a/test/Sentry.Unity.Android.Tests/SentryNativeAndroidTests.cs +++ b/test/Sentry.Unity.Android.Tests/SentryNativeAndroidTests.cs @@ -433,4 +433,137 @@ public void Configure_RuntimeAlreadyInitialized_KeepsOwnership() Assert.IsNotInstanceOf(options.ScopeObserver); Assert.NotNull(options.NativeSupportCloseCallback); } + + [Test] + public void Configure_SessionReplayEnabledAtRuntime_UsesAndroidReplaySession() + { + var options = new SentryUnityOptions(); + options.Experimental.SessionReplay.OnErrorSampleRate = 1; + + SentryNativeAndroid.Configure(options); + + Assert.IsInstanceOf(options.ReplaySession); + } + + [Test] + public void Configure_SessionReplayDisabled_KeepsDefaultReplaySession() + { + var options = new SentryUnityOptions(); + + SentryNativeAndroid.Configure(options); + + Assert.IsNull(options.ReplaySession); + } + + [Test] + [TestCase(NativeInitializationType.BuildTime)] + [TestCase(NativeInitializationType.External)] + public void Configure_SessionReplayEnabledWithoutRuntimeInit_LogsAndIgnoresIt( + NativeInitializationType initializationType) + { + var options = new SentryUnityOptions + { + AndroidNativeInitializationType = initializationType, + DiagnosticLogger = _logger, + Debug = true + }; + options.Experimental.SessionReplay.SessionSampleRate = 1; + + SentryNativeAndroid.Configure(options); + + Assert.IsNull(options.ReplaySession); + Assert.IsTrue(_logger.Logs.Any(log => + log.logLevel == SentryLevel.Warning && + log.message.Contains("Session replay requires the Android SDK to be initialized at runtime"))); + } + + [Test] + public void AndroidReplaySession_CaptureReplay_ReturnsCapturedReplayId() + { + var replayId = SentryId.Create(); + _testSentryJava.CapturedReplayId = replayId.ToString(); + var sut = new AndroidReplaySession(_testSentryJava); + + Assert.AreEqual(replayId, sut.CaptureReplay(new SentryEvent())); + Assert.AreEqual(1, _testSentryJava.CaptureReplayCalls); + } + + [Test] + [TestCase(null)] + [TestCase("00000000000000000000000000000000")] + public void AndroidReplaySession_NoReplay_ReturnsNull(string? nativeReplayId) + { + _testSentryJava.CapturedReplayId = nativeReplayId; + _testSentryJava.ReplayId = nativeReplayId; + var sut = new AndroidReplaySession(_testSentryJava); + + Assert.IsNull(sut.CaptureReplay(new SentryEvent())); + Assert.IsNull(sut.ActiveReplayId); + } + + [Test] + public void AndroidReplaySession_ActiveReplayId_ReadsNativeScope() + { + var replayId = SentryId.Create(); + _testSentryJava.ReplayId = replayId.ToString(); + var sut = new AndroidReplaySession(_testSentryJava); + + Assert.AreEqual(replayId, sut.ActiveReplayId); + Assert.AreEqual(0, _testSentryJava.CaptureReplayCalls); + } + + [Test] + public void Configure_SessionReplayWithoutProcessLifecycle_PausesAndResumesReplayWithUnity() + { + var options = new SentryUnityOptions { AutoSessionTrackingInterval = TimeSpan.FromHours(1) }; + options.Experimental.SessionReplay.OnErrorSampleRate = 1; + _testSentryJava.ProcessLifecycleObserved = false; + + SentryNativeAndroid.Configure(options); + SentryMonoBehaviour.Instance.UpdatePauseStatus(true); + SentryMonoBehaviour.Instance.UpdatePauseStatus(false); + options.AutoSessionTrackingInterval = TimeSpan.Zero; + SentryMonoBehaviour.Instance.UpdatePauseStatus(true); + SentryMonoBehaviour.Instance.UpdatePauseStatus(false); + options.NativeSupportCloseCallback?.Invoke(); + SentryMonoBehaviour.Instance.UpdatePauseStatus(true); + SentryMonoBehaviour.Instance.UpdatePauseStatus(false); + + CollectionAssert.AreEqual( + new[] { "pause", "resume:False", "pause", "resume:True" }, + _testSentryJava.ReplayLifecycleCalls); + } + + [Test] + public void Configure_SessionReplayWithoutProcessLifecycle_PausesOncePerBackground() + { + var options = new SentryUnityOptions { AutoSessionTrackingInterval = TimeSpan.FromHours(1) }; + options.Experimental.SessionReplay.SessionSampleRate = 1; + _testSentryJava.ProcessLifecycleObserved = false; + + SentryNativeAndroid.Configure(options); + // Losing focus and pausing both arrive when the game goes to the background. + SentryMonoBehaviour.Instance.OnApplicationFocus(false); + SentryMonoBehaviour.Instance.OnApplicationPause(true); + SentryMonoBehaviour.Instance.OnApplicationPause(false); + SentryMonoBehaviour.Instance.OnApplicationFocus(true); + options.NativeSupportCloseCallback?.Invoke(); + + CollectionAssert.AreEqual(new[] { "pause", "resume:False" }, _testSentryJava.ReplayLifecycleCalls); + } + + [Test] + public void Configure_SessionReplayWithProcessLifecycle_LeavesReplayLifecycleToNativeSdk() + { + var options = new SentryUnityOptions(); + options.Experimental.SessionReplay.OnErrorSampleRate = 1; + _testSentryJava.ProcessLifecycleObserved = true; + + SentryNativeAndroid.Configure(options); + SentryMonoBehaviour.Instance.UpdatePauseStatus(true); + SentryMonoBehaviour.Instance.UpdatePauseStatus(false); + options.NativeSupportCloseCallback?.Invoke(); + + CollectionAssert.IsEmpty(_testSentryJava.ReplayLifecycleCalls); + } } diff --git a/test/Sentry.Unity.Android.Tests/TestSentryJava.cs b/test/Sentry.Unity.Android.Tests/TestSentryJava.cs index 3dd755206..5eaa472fc 100644 --- a/test/Sentry.Unity.Android.Tests/TestSentryJava.cs +++ b/test/Sentry.Unity.Android.Tests/TestSentryJava.cs @@ -24,6 +24,11 @@ internal class TestSentryJava : ISentryJava public SentryUser? MainProcessUser { get; set; } public bool MainProcessUserReadable { get; set; } = true; public (SentryId TraceId, SpanId SpanId)? Trace { get; private set; } + public string? ReplayId { get; set; } + public string? CapturedReplayId { get; set; } + public int CaptureReplayCalls { get; private set; } + public bool? ProcessLifecycleObserved { get; set; } = true; + public List ReplayLifecycleCalls { get; } = new(); public bool? IsEnabled() => Enabled; @@ -57,6 +62,20 @@ public bool TryGetMainProcessUser(out SentryUser? user) public bool? CrashedLastRun() => IsCrashedLastRun; + public string? GetReplayId() => ReplayId; + + public bool? IsProcessLifecycleObserved() => ProcessLifecycleObserved; + + public void PauseReplay() => ReplayLifecycleCalls.Add("pause"); + + public void ResumeReplay(bool startNewSession) => ReplayLifecycleCalls.Add($"resume:{startNewSession}"); + + public string? CaptureReplay() + { + CaptureReplayCalls++; + return CapturedReplayId; + } + public (string? Type, string? EffectiveType) GetConnection() => Connection; public void Close() => CloseCalled = true; diff --git a/test/Sentry.Unity.Editor.Tests/Android/GradleSetupTests.cs b/test/Sentry.Unity.Editor.Tests/Android/GradleSetupTests.cs index 5d7ec7ea3..dde2538b0 100644 --- a/test/Sentry.Unity.Editor.Tests/Android/GradleSetupTests.cs +++ b/test/Sentry.Unity.Editor.Tests/Android/GradleSetupTests.cs @@ -87,6 +87,67 @@ public void ClearGradleProject_GradleFilesModified_RemovesModification() StringAssert.DoesNotContain(GradleSetup.SdkDependencies, unityLibraryGradleContent); } + private string UnityLibraryGradle => + File.ReadAllText(Path.Combine(GradleProjectPath, "unityLibrary", "build.gradle")); + + [Test] + public void UpdateGradleProject_SessionReplayEnabled_AddsReplayDependencies() + { + var sut = new GradleSetup(Logger, GradleProjectPath, sessionReplayEnabled: true); + + sut.UpdateGradleProject(); + + StringAssert.Contains(GradleSetup.SdkDependencies + GradleSetup.ReplayDependencies, UnityLibraryGradle); + } + + [Test] + public void UpdateGradleProject_SessionReplayDisabled_AddsNoReplayDependencies() + { + var original = UnityLibraryGradle; + var sut = new GradleSetup(Logger, GradleProjectPath, sessionReplayEnabled: false); + + sut.UpdateGradleProject(); + + Assert.AreEqual( + original.Replace("android {", GradleSetup.SdkDependencies + "\n}\n\nandroid {"), + UnityLibraryGradle); + StringAssert.DoesNotContain("sentry-android-replay", UnityLibraryGradle); + StringAssert.DoesNotContain("kotlin-stdlib:1.9.24", UnityLibraryGradle); + } + + [Test] + public void ClearGradleProject_SessionReplayDependenciesAdded_RestoresOriginal() + { + var original = UnityLibraryGradle; + new GradleSetup(Logger, GradleProjectPath, sessionReplayEnabled: true).UpdateGradleProject(); + + new GradleSetup(Logger, GradleProjectPath).ClearGradleProject(); + + Assert.AreEqual(original, UnityLibraryGradle); + } + + [Test] + public void UpdateGradleProject_SessionReplayToggled_SwapsDependencies() + { + var original = UnityLibraryGradle; + new GradleSetup(Logger, GradleProjectPath, sessionReplayEnabled: true).UpdateGradleProject(); + + new GradleSetup(Logger, GradleProjectPath, sessionReplayEnabled: false).UpdateGradleProject(); + + StringAssert.DoesNotContain("sentry-android-replay", UnityLibraryGradle); + StringAssert.DoesNotContain("kotlin-stdlib:1.9.24", UnityLibraryGradle); + Assert.AreEqual( + original.Replace("android {", GradleSetup.SdkDependencies + "\n}\n\nandroid {"), + UnityLibraryGradle); + + new GradleSetup(Logger, GradleProjectPath, sessionReplayEnabled: true).UpdateGradleProject(); + + StringAssert.Contains(GradleSetup.SdkDependencies + GradleSetup.ReplayDependencies, UnityLibraryGradle); + var coreDependencies = UnityLibraryGradle.Split( + new[] { "sentry-android-core-release" }, StringSplitOptions.None); + Assert.AreEqual(1, coreDependencies.Length - 1); + } + [Test] [TestCase("InsertIntoScope/build.gradle_test_1")] [TestCase("InsertIntoScope/build.gradle_test_2")]